Error Log #

Error log (log kesalahan) adalah sistem pencatatan internal yang digunakan oleh server web Caddy untuk mendokumentasikan masalah operasional, kegagalan modul, kesalahan sistem, dan peringatan abnormalitas yang terjadi selama runtime Caddy berjalan. Berbeda secara fundamental dari access log yang mencatat setiap interaksi transaksi HTTP sukses maupun gagal dari klien luar, error log berfokus secara eksklusif pada kesehatan organ internal Caddy itu sendiri. Jika Caddy gagal memperbarui sertifikat SSL/TLS otomatis dari Let’s Encrypt, jika koneksi proxy ke server backend aplikasi terputus secara tiba-tiba, atau jika berkas konfigurasi Caddyfile gagal dimuat saat restart, semuanya akan dicatat di sini. Memiliki pemahaman mendalam tentang error log sangat penting untuk mendiagnosis masalah keandalan jaringan, memantau kegagalan sertifikat secara proaktif, serta mempercepat proses penyelesaian masalah (troubleshooting) di lingkungan produksi. Kita akan membahas perbedaan struktural antara log akses dan log kesalahan, mengonfigurasi blok logging global, menganalisis kategori pesan kesalahan dunia nyata, mengaktifkan mode debugging yang mendalam, serta mengintegrasikan sistem logging dengan daemon manajemen log OS.

Perbedaan Sistematis Access Log vs Error Log #

Sering kali administrator sistem pemula mencampuradukkan data log akses dan log kesalahan ke dalam satu berkas tunggal yang tidak terstruktur. Ini adalah praktik buruk karena mempersulit analisis log menggunakan mesin otomatis (parsing engine).

Berikut adalah tabel perbedaan karakteristik fundamental antara keduanya:

Konfigurasi Logging Global dan Level Verbositas #

Di Caddy, semua konfigurasi logging internal dikelola pada tingkat teratas di dalam blok Global Options (opsi global) di bagian paling atas berkas Caddyfile. Hal ini dilakukan karena proses inisialisasi modul logging sistem harus berjalan lebih awal sebelum Caddy mem-parsing domain situs web kita.

Sintaks dasar konfigurasi logging global di opsi global Caddyfile adalah:

{
    log {
        output <writer>
        format <encoder>
        level  <severity_level>
    }
}

Memahami Tingkat Keparahan Log (Severity Levels) #

Caddy menerapkan klasifikasi standar tingkat keparahan (log levels) untuk menyaring pesan berdasarkan kepentingannya. Kita dapat menentukan parameter level untuk mengontrol seberapa banyak informasi yang ingin dituliskan ke berkas log:

1. DEBUG: Level paling verbos (cerewet). Mencatat setiap aktivitas detail biner internal (seperti negosiasi TLS, kecocokan header rute, atau alokasi buffer). Hanya digunakan pada lingkungan pengembangan (development) atau saat memecahkan masalah rumit karena menulis data yang sangat besar.
2. INFO (Default): Mencatat pesan operasional standar (seperti reload konfigurasi berhasil, inisialisasi server dimulai, atau sertifikat TLS baru berhasil diterbitkan). Sangat cocok untuk operasional normal di produksi.
3. WARN (Peringatan): Mencatat kondisi abnormal yang tidak sampai menghentikan jalannya Caddy, namun perlu diperhatikan (misalnya, koneksi ke backend sempat gagal namun berhasil dicoba kembali, atau respons SSL lambat).
4. ERROR (Kesalahan): Mencatat kegagalan fungsi kritis yang langsung berdampak pada layanan klien (misalnya, backend mati total sehingga mengembalikan status 502 Bad Gateway, atau sertifikat SSL tidak dapat diperbarui).
5. PANIC / FATAL: Level darurat yang menandakan server Caddy mengalami kegagalan fatal tingkat kernel atau runtime sehingga aplikasi mati total.

Mari kita pelajari alur penyaringan level logging ini pada diagram flowchart berikut:

flowchart TD
    A["1. Event Internal Terjadi di Caddy\n(e.g., dial tcp backend refused)"] --> B["2. Tentukan Level Keparahan Event\n(e.g., Level = ERROR)"]
    B --> C{"3. Cek Konfigurasi 'level' Global Caddyfile\n(e.g. Setel level = WARN)"}
    
    C --> D{"Apakah Level Event >= Level Konfigurasi?\n(Dalam hal ini, ERROR >= WARN?)"}
    
    D -- "Ya" --> E["4. Susun pesan log kesalahan terstruktur"]
    D -- "Tidak" --> F["5. Abaikan event (Jangan tulis ke log)"]
    
    E --> G["6. Kirim ke Modul Output Log Kesalahan\n(e.g., stderr / systemd journald)"]

Contoh Konfigurasi Error Log di Opsi Global #

Berikut adalah konfigurasi Caddyfile standar industri untuk memisahkan log kesalahan Caddy secara tersendiri dengan rotasi file otomatis:

# 1. Blok Opsi Global Caddyfile
{
    log {
        # Tulis seluruh error log Caddy ke file terpisah
        output file /var/log/caddy/caddy_system.log {
            roll_size 50mb
            roll_keep 10
        }
        # Gunakan format JSON terstruktur untuk kompatibilitas monitoring
        format json
        
        # Hanya catat kejadian level WARN ke atas di berkas ini
        level warn
    }
}

# 2. Blok Rute Situs Normal
example.com {
    reverse_proxy localhost:8080
}

Penalaan Logging Spesifik Berdasarkan Nama Modul (Logger Filtering) #

Caddy membagi struktur log internalnya ke dalam berbagai kategori logger yang berbeda berdasarkan modul yang memicu aktivitas tersebut (misalnya, http.handlers.reverse_proxy, tls, admin.api, atau http.acme_client).

Jika kita menyetel tingkat keparahan global ke level ERROR demi menghemat kapasitas disk, namun kita sedang memecahkan masalah integrasi proxy backend dan membutuhkan verbositas tingkat DEBUG hanya untuk modul reverse proxy, Caddy membolehkan kita menetapkan aturan log level spesifik per nama logger:

# Contoh: Isolasi Verbositas Debugging Khusus Modul Reverse Proxy
{
    # 1. Log kesalahan sistem umum (Level WARN ke atas)
    log system_errors {
        output file /var/log/caddy/system.log
        level warn
    }

    # 2. Log investigasi reverse proxy (Level DEBUG khusus)
    log proxy_debug {
        output file /var/log/caddy/proxy_debug.log
        level debug
        
        # Hanya sertifikatkan logger modul reverse proxy ke berkas ini
        include http.handlers.reverse_proxy
    }
}

example.com {
    reverse_proxy localhost:8080
}

Analisis Kategori Error Caddy di Dunia Nyata #

Sebagai pengelola server, kita wajib mengenali pesan kesalahan khas yang sering muncul pada berkas error log Caddy guna mempercepat mitigasi pemulihan sistem.

1. Kegagalan Koneksi Upstream (Reverse Proxy Connection Failure) #

Pesan kesalahan ini terjadi ketika Caddy gagal menghubungi server backend aplikasi (misalnya Node.js atau PHP-FPM) yang kita definisikan pada direktif reverse_proxy.

Contoh Teks JSON Error Log:

{
  "level": "error",
  "ts": 1781609500.654,
  "logger": "http.handlers.reverse_proxy",
  "msg": "aborting request due to backend write failure",
  "error": "dial tcp 127.0.0.1:8080: connect: connection refused"
}

• Arti Masalah: Aplikasi backend di port 8080 sedang mati, mengalami crash (out of memory), atau tidak berjalan di alamat IP local loopback tersebut.
• Tindakan Perbaikan: Periksa status runtime aplikasi backend kita menggunakan systemctl status or jalankan ulang proses container aplikasi tersebut.

2. Isu TLS / ACME Challenge (TLS Certificate Failure) #

Terjadi ketika Caddy mengalami kegagalan saat mencoba mendapatkan atau memperbarui sertifikat SSL/TLS gratis dari Let’s Encrypt atau ZeroSSL.

Contoh Teks JSON Error Log:

{
  "level": "error",
  "ts": 1781609510.987,
  "logger": "http.acme_client",
  "msg": "challenge failed",
  "challenge_type": "http-01",
  "error": "accepting challenge: HTTP 400 Bad Request - urn:ietf:params:acme:error:connection - Connection refused"
}

• Arti Masalah: Server tantangan Let’s Encrypt mencoba mengakses port 80 (HTTP) dari server Caddy kita untuk memvalidasi kepemilikan domain, namun koneksi ditolak.
• Tindakan Perbaikan: Pastikan port 80 pada server Caddy kita terbuka bebas di tingkat firewall jaringan (seperti AWS Security Groups atau cloud provider firewall) dan tidak diblokir oleh ISP.

3. Masalah SNI Mismatch (Unknown TLS Client Hello) #

Pesan kesalahan ini sering dipicu ketika ada bot pemindai jaringan (IP scanner) yang mencoba menghubungi server Caddy kita langsung melalui alamat IP tanpa mengirimkan nama domain (SNI) yang sah.

Contoh Teks JSON Error Log:

{
  "level": "warn",
  "ts": 1781609520.123,
  "logger": "tls.handshake",
  "msg": "no certificate available for the requested server name",
  "server_name": "203.0.113.10"
}

• Arti Masalah: Server TLS Caddy menolak jabat tangan enkripsi karena tidak memiliki sertifikat SSL yang valid untuk domain bernama alamat IP 203.0.113.10.
• Tindakan Perbaikan: Ini adalah pesan peringatan normal di produksi akibat aktivitas bot internet. Tidak memerlukan tindakan mitigasi kecuali jika volume request bot tersebut sangat besar (DDoS), yang dapat diredam menggunakan blocklist IP.

Penanganan Panic dan Stack Trace Go Runtime #

Caddy ditulis menggunakan bahasa pemrograman Go (Golang). Salah satu karakteristik aplikasi Go adalah ketika terjadi masalah tingkat rendah yang sangat parah di dalam bodi kode memori—misalnya kehabisan memori RAM biner (out of memory panic) atau kegagalan penulisan map secara bersamaan oleh goroutine (concurrent map writes)—Go runtime akan mengalami panic dan mencetak seluruh tumpukan pemanggilan fungsi (stack trace).

// Ilustrasi format output Go Runtime Panic di Log
panic: runtime error: invalid memory address or nil pointer dereference
[signal SIGSEGV: segmentation violation code=0x1 addr=0x0 pc=0x10b2df4]

goroutine 127 [running]:
github.com/caddyserver/caddy/v2/modules/caddyhttp/reverseproxy.(*Handler).ServeHTTP(0xc00045f800, 0x140e700, ...)
    /go/pkg/mod/github.com/caddyserver/caddy/[email protected]/modules/caddyhttp/reverseproxy/reverseproxy.go:342 +0x234

• Arti Masalah: Ini bukan sekadar kesalahan konfigurasi Caddyfile biasa. Ini adalah bug perangkat lunak tingkat runtime (software bug) atau crash sistem yang fatal yang menyebabkan proses biner Caddy mati seketika.
• Tindakan Penyelamatan: Caddy tidak dapat memulihkan dirinya sendiri dari kondisi panic. Kita wajib menggunakan sistem supervisor eksternal (seperti daemon systemd di Linux dengan konfigurasi Restart=on-failure atau Docker restart policy unless-stopped) untuk memastikan server Caddy kita otomatis dinyalakan kembali oleh OS dalam hitungan detik setelah mengalami crash.

Mengaktifkan Mode Debugging Mendalam (Verbose Logging) #

Saat kita melakukan pengembangan lokal (local development) atau ketika rute server Caddy kita tidak merespons sesuai harapan (misalnya, request dialihkan ke blok server yang salah), kita harus mengaktifkan level debug untuk melihat proses kalkulasi internal Caddy.

# Contoh Caddyfile untuk Debugging Lokal
{
    log {
        output stderr
        format console
        # Aktifkan level debug yang sangat verbos
        level debug
    }
}

example.com {
    @restricted {
        header X-Special-Token "secret"
    }
    
    # Rute khusus yang ingin kita selidiki perilakunya
    handle @restricted {
        respond "Akses Khusus Diterima" 200
    }
    
    handle {
        respond "Akses Publik" 200
    }
}

Dengan mengaktifkan level debug dan mengarahkan output ke stderr (ditampilkan langsung di terminal konsol), Caddy akan mencatat setiap langkah evaluasi named matcher:

• Caddy akan menulis: @restricted matcher evaluated: Header match false (Value did not match)
• Ini sangat membantu kita mendeteksi apakah kesalahan rute disebabkan oleh kesalahan penulisan nama header, spasi tersembunyi, atau ketidakcocokan tipe parameter.

Integrasi Alerts dan Notifikasi Error Real-Time #

Menulis log kesalahan ke berkas lokal adalah langkah awal yang baik, namun tidak berguna jika tidak ada yang membacanya hingga website kita mati. Di lingkungan produksi kritis, kita wajib mengintegrasikan log kesalahan Caddy dengan sistem peringatan otomatis (automated alert systems).

Kita dapat menggunakan utilitas Promtail (dari ekosistem Grafana) untuk memindai berkas /var/log/caddy/system.log secara terus-menerus. Jika mendeteksi entri JSON yang memiliki field "level": "error", Promtail akan mengirimkan metrik ke Prometheus, yang kemudian memicu Alertmanager` untuk mengirimkan notifikasi ke saluran Slack tim developer kita secara instan:

# Contoh Alur Pipa Promtail Alerting
pipeline_stages:
  - json:
      expressions:
        level_value: level
        logger_name: logger
        error_msg: error
  - match:
      selector: '{job="caddy-system"} | json | level_value = "error"'
      stages:
        - metrics:
            caddy_error_counter:
              type: Counter
              description: "Jumlah total error kritis sistem Caddy"
              source: level_value
              config:
                action: inc

Dengan cara ini, tim operasional kita dapat langsung mengidentifikasi adanya anomali server (seperti kegagalan resolusi DNS upstream) dalam hitungan detik sebelum memicu komplain dari pengguna akhir aplikasi kita.

Tindakan Defensif Mengatasi Log Kesalahan yang Membengkak #

Pada server produksi dengan volume traffic tinggi, berkas log kesalahan yang menyertakan level WARN dapat membengkak akibat rentetan request dari bot internet yang memicu peringatan TLS (seperti SNI mismatch). Kita harus tahu cara membatasi logging ini secara defensif agar tidak menghabiskan kapasitas disk server:

1. Gunakan Log Level ERROR di Produksi: Untuk server publik yang terekspos langsung ke internet tanpa firewall Cloudflare di depannya, hindari penyusunan level INFO atau WARN sebagai default global. Gunakan level error agar Caddy hanya merekam kejadian kegagalan fungsionalitas yang benar-benar kritis bagi aplikasi backend kita.
2. Rotasi Otomatis Berkas Log: Selalu konfigurasikan parameter rotasi log (roll parameters) pada blok output file kita, misalnya membatasi ukuran maksimal per berkas hingga 50mb dan menyimpan maksimal 5 cadangan lama untuk mengamankan disk I/O.
3. Optimasi Firewall Tepi Jaringan: Redam lalu lintas bot pemindai jaringan di tingkat terluar (seperti AWS Security Groups atau Cloudflare IP Firewall) sebelum sempat masuk ke sistem socket TCP server Caddy kita, yang secara otomatis memotong rekaman log kesalahan TLS yang mengotori sistem.

Ringkasan #

• Fungsi Utama: Log kesalahan merekam status operasional internal Caddy seperti kegagalan TLS, error pemuatan berkas Caddyfile, dan kegagalan dial reverse proxy.
• Penyuntingan Global: Konfigurasi log kesalahan dikelola secara terpusat pada tingkat blok teratas Opsi Global Caddyfile.
• Tingkat Severity: Caddy mengklasifikasikan keparahan log dari yang paling rendah hingga kritis: DEBUG, INFO, WARN, ERROR, PANIC, dan FATAL.
• Isolasi Logger: Kita dapat mengisolasi verbositas debug khusus untuk modul tertentu (seperti http.handlers.reverse_proxy) untuk mencegah pembengkakan log.
• Mode Debugging: Aktifkan level debug untuk menyelidiki evaluasi named matcher dan kegagalan handshake TLS di lingkungan pengembangan lokal.
• TLS & ACME Alert: Pantau log kesalahan secara proaktif untuk mendeteksi kegagalan ACME challenge Let’s Encrypt sebelum sertifikat kedaluwarsa.
• Tindakan Defensif: Batasi ukuran log di produksi dengan menyetel level error guna menyaring rentetan log TLS warning akibat aktivitas bot internet.
• Supervisor systemd: Go Runtime Panic memerlukan supervisor systemd luar dengan opsi Restart=on-failure agar Caddy otomatis berjalan kembali pasca crash biner.

← Sebelumnya: Access Log   Berikutnya: Format Log →