Log dan Pemantauan Aplikasi CFML

Log dan Pemantauan Aplikasi CFML

Penulis: Thalhah · Tarikh: 16 Oktober 2026

Log dan pemantauan aplikasi CFML bermaksud memahami fail log yang ditulis Lucee dan Tomcat, menulis log anda sendiri dengan cflog atau writeLog, dan menangkap ralat yang tidak ditangani melalui onError dalam Application.cfc. Dengan log yang teratur dan pemantauan kadar ralat, anda boleh mengesan masalah sebelum pengguna melaporkannya. Artikel ini menerangkan setiap fail log, cara menulis log, dan apa yang patut dipantau.

Fail Log Lucee dan Kandungannya

Lucee berjalan di atas enjin servlet seperti Tomcat, dan kedua-duanya menulis log. Panduan penyelesaian masalah rasmi membahagikannya kepada dua lapisan. Pada sisi Tomcat, fail utama ialah catalina-{date}.log dalam folder tomcat/logs, yang mengandungi log permulaan dan penutupan serta sebarang pengecualian daripada enjin servlet. Fail ini ialah tempat pertama untuk dilihat apabila pelayan tidak mula atau mati secara tiba-tiba.

Pada sisi Lucee, di bawah direktori lucee-server terdapat folder context/logs yang memegang log Lucee dalam konfigurasi lalai. Permulaan Lucee berlaku dalam dua peringkat. Sebelum log4j dimuatkan, Lucee menulis kepada out.log, log standard termasuk deploy fail dan muat konfigurasi, dan err.log, yang mengandungi ralat pada peringkat awal ini. Selepas log4j dikonfigurasi, Lucee beralih kepada fail biasa:

Aras Log dan Maksudnya

Setiap mesej log mempunyai aras yang menunjukkan keterukannya. Mengikut urutan menurun, aras itu ialah fatal untuk ralat teruk yang menamatkan proses lebih awal, error untuk ralat masa jalan, warn atau warning untuk penggunaan yang hampir silap atau tidak diingini, info atau information (lalai) untuk peristiwa masa jalan yang menarik, debug untuk butiran aliran sistem, dan trace untuk butiran paling terperinci.

Fungsi writeLog menerima nilai type yang lebih kecil: information (lalai), warning, error dan fatal. Ini bermakna writeLog tidak mendedahkan debug dan trace, tetapi cflog menyokong kesemua enam aras melalui atribut type. Memilih aras dengan betul menjadikan log anda bermakna dan bukannya bunyi: ralat sebenar sebagai error, amaran sebagai warning, dan peristiwa biasa sebagai information.

Menulis Log Sendiri dengan cflog dan writeLog

Untuk log mesej aplikasi sendiri, gunakan tag cflog atau fungsi writeLog. writeLog menerima argumen text yang wajib dan type pilihan:

writeLog( text="Pesanan #orderId# gagal diproses", type="error" );

Tag cflog menawarkan atribut yang lebih lengkap, termasuk log untuk menyasarkan log bernama yang ditakrifkan dalam Lucee Administrator, dan exception untuk melog pengecualian:

<cflog text="Pengguna #session.userId# log masuk" log="audit" type="information">

Dokumentasi menasihatkan supaya sentiasa menggunakan atribut log dengan nama yang ditakrifkan dalam Administrator atau melalui this.logs dalam Application.cfc, kerana sambungan fail dicache dan lebih pantas. Atribut file masih berfungsi tetapi sudah lapuk dan lebih perlahan kerana sambungannya tidak dicache.

Menulis Log Berstruktur supaya Mudah Dicari

Log yang konsisten lebih mudah dicari dan dijadikan amaran. Tetapkan satu corak untuk setiap mesej, contohnya menyertakan ID entiti yang terlibat, pengguna, dan tindakan, supaya anda boleh menapis log untuk satu pengguna atau satu pesanan. Gunakan aras yang konsisten supaya alat pemantauan boleh membezakan ralat sebenar daripada maklumat rutin. Elakkan mesej generik seperti "ada ralat" tanpa konteks, kerana ia tidak membantu anda mencari punca tiga bulan kemudian.

Pengendalian Ralat dengan onError dalam Application.cfc

Ralat yang tidak ditangani akan berakhir di exception.log, tetapi anda hampir selalu mahu mengendalikannya sendiri supaya pengguna tidak melihat timbunan ralat mentah. Application.cfc menyediakan kaedah onError yang dipanggil apabila pengecualian tidak ditangkap berlaku dalam konteks aplikasi:

component {
    this.name = "kedai-saya";

    function onError( required struct exception, required string eventName ) {
        writeLog( text="Ralat #eventName#: #exception.message#", type="error" );
        // paparkan mesej mesra, bukan timbunan mentah
        include "ralat.cfm";
    }
}

Kaedah ini menerima dua argumen: struct exception, iaitu blok cfcatch, dan eventName. Dengan menulis mesej ralat yang jelas di sini, anda membina jejak audit yang boleh dicari. Struktur lengkap Application.cfc dibincangkan dalam panduan memahami Application.cfc.

Konsol dan SystemOutput

Kadang-kadang anda mahu melihat log terus pada konsol, terutama semasa menyahpepijat permulaan pelayan. Fungsi SystemOutput() menulis kepada log catalina, yang dipaparkan pada konsol apabila Tomcat dijalankan secara manual. Sejak Lucee 6.2, anda juga boleh mengalihkan semua log log4j ke konsol dengan LUCEE_LOGGING_FORCE_APPENDER=console, dan menukar aras dengan LUCEE_LOGGING_FORCE_LEVEL. Ini amat berguna dalam bekas, di mana konsol diuruskan oleh runtime Docker.

Log dalam Mod Berbilang (Multi Mode)

Jika Lucee berjalan dalam mod berbilang, log dijana untuk kedua-dua pelayan dan setiap konteks web. Kebanyakan log dijana dalam konteks web, tetapi sesetengah log global mungkin muncul dalam konteks pelayan. Konfigurasi log dalam konfigurasi pelayan tidak diwarisi oleh konteks web, jadi ia mesti ditetapkan secara berasingan. Apabila anda menukar tetapan log dalam Lucee Administrator, sahkan anda mengubah konteks yang betul, jika tidak perubahan anda kelihatan tidak berkesan.

Menggabungkan Log dengan Alat Luaran

Untuk aplikasi yang lebih besar, menghantar log ke alat pemantauan pusat menjadikan pencarian dan amaran lebih mudah. Banyak alat boleh menghuraikan fail log Lucee dan mengesan corak ralat secara automatik. Gabungan paling berkesan ialah log berstruktur yang anda tulis sendiri, disalurkan kepada alat yang boleh memberi amaran berdasarkan kadar ralat. Mulakan dengan fail log setempat, dan hanya tambah alat luar apabila satu pelayan tidak lagi mencukupi.

Kitaran Putaran Log supaya Cakera Tidak Penuh

Log yang tidak diputar akan memenuhi cakera dan akhirnya menjatuhkan pelayan. Lucee menulis log melalui log4j, dan anda boleh mengawal konfigurasi log melalui .CFconfig.json. Dua pendekatan praktikal untuk putaran: gunakan alat putaran sistem pengendalian seperti logrotate pada direktori log, atau dalam bekas, alihkan log ke konsol supaya runtime bekas mengendalikannya.

Sejak Lucee 6.2, pemboleh ubah LUCEE_LOGGING_FORCE_APPENDER=console mengalihkan semua log ke konsol, yang berguna dalam Docker kerana stdout bekas diuruskan oleh pemacu log. Pantau penggunaan cakera direktori log dan tetapkan putaran berdasarkan kadar penulisan sebenar, bukan tekaan. Untuk persediaan bekas yang lengkap, rujuk panduan deploy Docker.

Amaran Berdasarkan Kadar Ralat

Log hanya berguna jika anda bertindak ke atasnya. Tetapkan amaran berdasarkan kadar ralat: contohnya, jika bilangan baris ralat dalam exception.log melebihi ambang tertentu dalam sejam, hantar pemberitahuan. Banyak alat pemantauan boleh menonton fail log atau mengeksport metrik, dan anda juga boleh menjadualkan pemeriksaan dengan penjadual Lucee. Yang penting ialah mengukur kadar asas dahulu supaya anda tahu apa itu normal, kemudian amaran apabila kadar menyimpang daripada asas itu.

Apa yang Perlu Dipantau

Tiga metrik paling penting ialah masa respons, kadar ralat HTTP 500, dan memori JVM. Masa respons menunjukkan kesihatan pengalaman pengguna; ralat 500 menunjukkan kod yang gagal; dan memori JVM menunjukkan tekanan yang boleh menjatuhkan pelayan. Lucee turut menyediakan pemboleh ubah persekitaran request timeout, seperti LUCEE_REQUESTTIMEOUT_MEMORYTHRESHOLD, yang menguatkuasakan timeout berdasarkan penggunaan memori. Pantau juga ruang cakera dan saiz fail log, kerana log yang membesar tanpa kawalan boleh menjatuhkan pelayan sebelum ralat aplikasi sempat dikesan.

Untuk memori JVM secara khusus, baca panduan menala JVM. Untuk debugging interaktif, rujuk panduan debugging CFML dalam VS Code.

Soalan Lazim (FAQ)

Di manakah fail log Lucee disimpan?

Log Lucee disimpan dalam folder context/logs di bawah direktori lucee-server, manakala log Tomcat berada dalam folder tomcat/logs.

Apakah beza application.log dan exception.log?

application.log ialah log lalai untuk Lucee dan aplikasi, manakala exception.log mengandungi ralat dan pengecualian.

Bagaimana cara menulis log daripada kod CFML?

Gunakan tag cflog atau fungsi writeLog dengan argumen text dan type. Gunakan atribut log untuk prestasi lebih baik berbanding atribut file yang sudah lapuk.

Apakah onError dalam Application.cfc?

onError ialah kaedah yang dipanggil apabila pengecualian tidak ditangkap berlaku dalam konteks aplikasi, menerima argumen exception dan eventName.

Bagaimana cara mengelakkan cakera penuh akibat log?

Putarkan log dengan logrotate pada direktori log, atau alihkan log ke konsol dengan LUCEE_LOGGING_FORCE_APPENDER=console supaya runtime bekas mengendalikannya.

Sumber

• Troubleshooting Lucee Server problems, docs.lucee.org
• WriteLog(), docs.lucee.org
• cflog, docs.lucee.org
• Application.cfc guide, docs.lucee.org
• Deploying Lucee, docs.lucee.org
• Environment Variables and System Properties, docs.lucee.org