Format Log #

Format log adalah representasi visual dan struktur data dari rekaman log yang dihasilkan oleh server Caddy sebelum dikirimkan ke target keluaran (log output). Konfigurasi format log yang tepat bertindak sebagai jembatan penting antara data biner mentah sistem Caddy dengan kecerdasan sistem pemantau (monitoring systems) kita. Secara bawaan, Caddy menyediakan format JSON terstruktur yang sangat ideal untuk mesin pengolah data, serta format konsol kustom yang ramah untuk mata manusia selama proses pengembangan lokal. Namun pada skala produksi, kita sering kali dituntut untuk memodifikasi format log tersebut: membuang field data yang tidak digunakan demi menghemat bandwidth, mengganti nama field agar sesuai dengan skema basis data terpusat, menyembunyikan parameter query yang sensitif, serta melakukan penyamaran (masking) alamat IP klien demi mematuhi regulasi privasi data global seperti GDPR. Kita akan mengupas tuntas arsitektur encoder log Caddy, membandingkan format JSON dan konsol, mempelajari teknik penyaringan dan anonimisasi data sensitif, mempraktikkan penggunaan penyeleksi field (field selectors), serta menyusun transformasi format log untuk kompatibilitas tingkat tinggi.

Arsitektur Log Encoder Caddy #

Dalam sistem internal server Caddy, perekaman log tidak dilakukan secara monolitik atau langsung ditulis ke dalam berkas media penyimpanan. Caddy membagi proses logging menjadi dua modul terpisah yang berkolaborasi secara longgar: Writer dan Encoder. Writer memiliki tanggung jawab tunggal untuk menentukan ke mana aliran data log dikirimkan (misalnya ke berkas lokal di disk, ke konsol standard output, atau dialirkan melalui jaringan ke server syslog). Sementara itu, Encoder memegang tanggung jawab eksklusif untuk mendefinisikan bagaimana data kejadian (event) terstruktur dikonversi menjadi representasi teks atau biner sebelum dikirimkan ke Writer.

Ketika sebuah request HTTP masuk atau terjadi kegagalan sistem, subsistem logging Caddy (yang dibangun di atas pustaka logging terstruktur Go berkecepatan tinggi bernama zap) mengumpulkan seluruh metadata kejadian dalam bentuk struktur data terstruktur di memori RAM. Struktur data ini berisi berbagai informasi mulai dari timestamp presisi tinggi, level keparahan (severity level), nama logger, pesan utama, hingga detail HTTP request dan respons. Setelah data terkumpul, Caddy memanggil modul Encoder yang telah dikonfigurasi pada Caddyfile. Encoder ini kemudian menelusuri seluruh data biner tersebut, menerapkan filter manipulasi yang kita minta, dan menyerialisasikannya menjadi string terformat (misalnya baris JSON terkompresi atau teks konsol dengan warna-warna penanda level). Hasil serialisasi berupa teks string inilah yang kemudian diserahkan kepada Writer untuk disimpan ke disk atau dikirim ke jaringan.

Pemisahan arsitektural antara formatting (Encoder) dan I/O writing (Writer) ini memberikan fleksibilitas luar biasa. Kita dapat mengubah format log dari JSON menjadi teks biasa, menyembunyikan data sensitif pengguna, atau memodifikasi format waktu tanpa perlu khawatir tentang bagaimana file log tersebut dirotasi, dikompresi, atau dikirimkan ke luar server.

Format Log Terintegrasi: JSON vs Console vs Logfmt #

Caddy menyediakan tiga modul log encoder bawaan yang siap kita gunakan tanpa memerlukan instalasi modul eksternal. Masing-masing encoder memiliki karakteristik unik yang dirancang untuk skenario deployment yang berbeda.

1. JSON Encoder (format json) #

JSON encoder merupakan pilihan standar dan paling direkomendasikan untuk seluruh lingkungan produksi (production environments). Format ini menuliskan setiap entri log sebagai satu baris objek JSON (single-line JSON object) terkompresi. JSON encoder mempertahankan tipe data asli dari setiap metrik—seperti angka integer untuk status respons, angka float desimal untuk durasi pemrosesan, array string untuk header HTTP, dan boolean untuk status keamanan TLS.

• Mengapa Memilih JSON: Mesin log aggregator modern seperti Elasticsearch, Grafana Loki, Datadog, Splunk, dan AWS CloudWatch dapat langsung membaca dan mengindeks objek JSON secara efisien tanpa memerlukan konfigurasi parsing ekspresi reguler (regex) yang rumit. Ini mempercepat proses pencarian log dan pembuatan dashboard metrik pemantauan secara real-time.
• Kelemahan JSON: Sangat sulit dibaca secara langsung oleh mata manusia di layar terminal karena baris teks tidak memiliki spasi indentasi (minified) demi menghemat ruang penyimpanan.

Berikut adalah contoh baris log akses mentah yang dihasilkan oleh JSON encoder Caddy:

{"level":"info","ts":1781609400.1234,"logger":"http.log.access","msg":"handled request","request":{"remote_ip":"203.0.113.50","proto":"HTTP/2.0","method":"GET","host":"example.com","uri":"/api/users","headers":{"User-Agent":["curl/7.81.0"],"Authorization":["Bearer secret_token"]}},"duration":0.0045,"size":142,"status":200}

2. Console Encoder (format console) #

Console encoder dirancang khusus untuk meningkatkan produktivitas kita selama proses pengembangan aplikasi lokal (local development). Format ini menerjemahkan objek terstruktur di memori menjadi baris teks berkolom yang rapi, memformat timestamp Unix desimal menjadi waktu lokal yang mudah dibaca, serta memberikan efek warna teks (color coding) berbasis terminal ANSI pada level keparahan log (kuning untuk warning, merah untuk error, hijau untuk info).

• Mengapa Memilih Console: Kita dapat dengan cepat membaca alur request masuk, mendeteksi error HTTP, dan membaca pesan debug secara langsung di terminal console interaktif kita tanpa alat bantu parsing tambahan.
• Kelemahan Console: Sangat tidak efisien untuk lingkungan produksi. Pembuatan teks console berwarna memakan siklus CPU yang lebih tinggi, membuang sebagian metadata terperinci untuk estetika keterbacaan, dan sangat menyulitkan agen pengumpul log (log shipper) untuk melakukan analisis query otomatis.

Berikut adalah representasi visual dari entri log yang sama ketika diformat menggunakan Console encoder:

2026-06-16T18:44:15.123+0700    INFO    http.log.access    handled request    {"request": {"remote_ip": "203.0.113.50", "proto": "HTTP/2.0", "method": "GET", "host": "example.com", "uri": "/api/users"}, "duration": 0.0045, "status": 200}

3. Logfmt Encoder (format logfmt) #

Logfmt encoder memformat data log menjadi rangkaian pasangan kunci-nilai (key-value pairs) yang dipisahkan oleh spasi. Nilai yang mengandung spasi atau karakter khusus akan dibungkus secara otomatis dengan tanda kutip ganda.

• Mengapa Memilih Logfmt: Sangat populer di ekosistem Go, Kubernetes, dan Heroku. Format ini menawarkan jalan tengah yang baik: lebih mudah dibaca oleh mata manusia dibandingkan JSON mentah, namun tetap sangat mudah di-parsing secara efisien oleh mesin pengumpul log seperti Grafana Loki atau Fluentd.
• Kelemahan Logfmt: Struktur data bersarang (nested data) seperti objek HTTP request Caddy harus diratakan (flattened) menjadi format satu dimensi (misalnya request.method=GET), yang terkadang dapat membingungkan jika struktur datanya sangat kompleks.

Berikut adalah contoh baris log yang sama terformat dalam Logfmt:

ts=1781609400.1234 level=info logger=http.log.access msg="handled request" method=GET host=example.com uri=/api/users duration=0.0045 status=200

Membandingkan Kode: Kapan Memilih Format yang Tepat? #

Mari kita pelajari contoh perbandingan Caddyfile di bawah ini untuk melihat kesalahan konfigurasi umum (anti-pattern) dan solusinya:

# Contoh perbandingan penulisan format log berdasarkan environment
example.com {
    # ANTI-PATTERN: Menggunakan format console di lingkungan produksi skala besar.
    # Tindakan ini memperlambat penulisan I/O disk karena formatting teks warna-warni,
    # serta mempersulit log aggregator (Loki/Elasticsearch) dalam mem-parsing data.
    log {
        output file /var/log/caddy/production.log
        format console
    }
    
    # BENAR: Gunakan format JSON terstruktur untuk lingkungan produksi.
    # Ini memastikan retensi data log yang efisien, pemakaian CPU minimal,
    # dan kompatibilitas 100% dengan log aggregator.
    log {
        output file /var/log/caddy/production.json.log
        format json
    }
}

Kustomisasi Format JSON: Format Waktu (Timestamp) #

Secara bawaan, JSON encoder di Caddy merekam waktu kejadian (timestamp) dalam format angka pecahan Unix epoch desimal (misalnya, "ts": 1781609400.1234). Format ini mencatat jumlah detik yang telah berlalu sejak tanggal 1 Januari 1970 UTC. Bagi komputer dan database, format ini sangat ideal karena operasi pengurutan (sorting) angka jauh lebih cepat daripada pengurutan string tanggal. Namun bagi kita manusia, format ini sangat membingungkan saat kita harus membaca log secara manual untuk investigasi cepat.

Untuk mengatasi hal ini, Caddy membolehkan kita melakukan kustomisasi representasi timestamp di dalam JSON format. Ada beberapa format waktu yang didukung oleh Caddy:

Berikut adalah contoh implementasi Caddyfile untuk mengubah format waktu menjadi ISO-8601 standar internasional yang sangat direkomendasikan untuk integrasi monitoring:

# Contoh kustomisasi format waktu JSON Caddy
example.com {
    log {
        output file /var/log/caddy/access.log
        format json {
            # Kustomisasi format waktu ke standar internasional ISO8601.
            # Sangat direkomendasikan karena langsung dikenali oleh Elasticsearch dan Loki
            # sebagai penanda waktu indeks utama tanpa pemrosesan ekstra.
            time_format "iso8601"
            
            # Kita juga bisa menggunakan format "wall" jika ingin memantau log
            # di server lokal dengan zona waktu server setempat.
            # time_format "wall"
        }
    }
    reverse_proxy localhost:8080
}

Manipulasi Field Log: Menghapus dan Mengaburkan Data Sensitif #

Pada aplikasi web modern di lingkungan produksi yang sesungguhnya, keamanan dan kerahasiaan data pengguna adalah prioritas nomor satu. Secara bawaan, log akses Caddy merekam informasi header HTTP request secara utuh. Masalah serius muncul ketika request tersebut membawa data sensitif seperti token otentikasi di header Authorization, cookie otentikasi di header Cookie, atau data pribadi pengguna di parameter header lainnya. Jika data ini ditulis langsung ke berkas log teks biasa di server, server kita akan melanggar kepatuhan regulasi privasi global seperti GDPR (Uni Eropa) atau PCI-DSS (standar keamanan kartu kredit).

Untuk mencegah kebocoran data sensitif ini, Caddy menyediakan fitur manipulasi field log yang tangguh melalui mekanisme filter langsung di dalam konfigurasi encoder Caddyfile.

1. Menghapus Field Sensitif (filter delete) #

Kita dapat menghapus field tertentu dari struktur JSON log agar field tersebut tidak pernah dikonversi menjadi string dan tidak pernah menyentuh hard disk server kita. Kita melakukan ini dengan menggunakan kata kunci filter diikuti oleh penyeleksi field (field selector) dan aksi delete.

# Contoh penghapusan header sensitif untuk kepatuhan keamanan
example.com {
    log {
        output file /var/log/caddy/access.log
        format json {
            # Hapus token otentikasi dari log akses request
            filter request>headers>Authorization delete
            
            # Hapus data Cookie dari log request untuk mencegah kebocoran sesi
            filter request>headers>Cookie delete
            
            # Hapus data Cookie respons dari backend web kita
            filter resp_headers>Set-Cookie delete
        }
    }
    reverse_proxy localhost:8080
}

Pada contoh di atas, karakter lebih besar dari (>) bertindak sebagai penyeleksi jalur bersarang (nested path selector) untuk menemukan letak data header di dalam objek JSON log Caddy.

[!CAUTION] JANGAN menggunakan karakter titik (.) sebagai pemisah penyeleksi field. Developer yang terbiasa dengan sintaks JSONpath (seperti request.headers.Cookie) sering kali salah menuliskan penyeleksi di Caddyfile dengan karakter titik. Caddyfile wajib menggunakan karakter lebih besar dari (>) sebagai pemisah token. Jika kita menuliskan tanda titik (misalnya filter request.headers.Cookie delete), parser Caddyfile akan menganggap request.headers.Cookie sebagai satu nama field tunggal yang datar, sehingga filter tersebut gagal bekerja dan menyebabkan data sensitif kita tetap bocor ke disk.

2. Anonimisasi Alamat IP Pengunjung (filter ip_mask) #

Di bawah regulasi perlindungan data GDPR Uni Eropa, alamat IP pengunjung dianggap sebagai data pribadi (Personally Identifiable Information / PII) karena secara teoritis dapat digunakan untuk melacak identitas individu. Menyimpan alamat IP lengkap pengunjung tanpa enkripsi atau persetujuan ketat adalah pelanggaran hukum. Namun, kita tetap membutuhkan informasi alamat IP untuk analisis statistik keamanan (seperti mendeteksi serangan DDoS atau mengetahui asal negara pengunjung).

Solusi terbaik adalah melakukan anonimisasi alamat IP dengan menyamarkan (masking) sebagian bit alamat IP tersebut sebelum ditulis ke file log. Caddy menyediakan filter ip_mask bawaan yang sangat efisien untuk tujuan ini:

# Contoh konfigurasi anonimisasi alamat IP untuk kepatuhan GDPR
example.com {
    log {
        output file /var/log/caddy/access.log
        format json {
            # Menyamarkan alamat IP klien dengan CIDR mask:
            # - Untuk IPv4: gunakan mask 16 bit (menyembunyikan 2 octet terakhir, misal 203.0.113.50 menjadi 203.0.0.0)
            # - Untuk IPv6: gunakan mask 32 bit (menyembunyikan sebagian besar blok heksadesimal)
            filter request>client_ip ip_mask 16 32
            filter request>remote_ip ip_mask 16 32
        }
    }
    reverse_proxy localhost:8080
}

Dengan konfigurasi di atas:

• IP address 203.0.113.50 akan disimpan di berkas log sebagai 203.0.0.0.
• Kita tetap dapat mengetahui bahwa pengunjung berasal dari blok provider internet regional tersebut tanpa melanggar privasi data pribadi mereka karena data IP asli sudah terhapus secara permanen di memori RAM sebelum sempat ditulis ke penyimpanan disk.

Log Enrichment: Injeksi Data Kustom ke Log #

Sering kali kita perlu melacak perjalanan sebuah request HTTP di seluruh arsitektur sistem kita (distributed tracing). Untuk mempermudah pelacakan ini, kita harus menyuntikkan pengenal unik (Unique Request ID) ke dalam log akses Caddy serta ke header request yang dikirimkan ke server backend aplikasi kita.

Caddy membolehkan kita memanfaatkan variabel dinamis (placeholders) untuk menyuntikkan data kustom ke dalam request header. Karena log Caddy merekam isi header request secara otomatis, tindakan penambahan header ini secara langsung memperkaya (enrich) informasi di dalam log akses kita:

# Contoh konfigurasi Log Enrichment dengan Request ID kustom
example.com {
    log {
        output file /var/log/caddy/access.log
        format json
    }

    # Ambil UUID unik yang dibuat otomatis oleh Caddy untuk setiap request,
    # lalu masukkan ke header request X-Request-ID.
    # Header ini otomatis terekam di bawah request>headers>X-Request-Id pada JSON log.
    header_up X-Request-ID {http.request.uuid}
    
    # Masukkan informasi username jika user berhasil login menggunakan Basic Auth
    header_up X-Authenticated-User {http.auth.user.id}

    reverse_proxy localhost:8080
}

Dengan menerapkan taktik di atas, tim operasional kita dapat dengan mudah menyalin nilai X-Request-ID dari log akses Caddy dan mencarinya di database log backend aplikasi kita untuk melihat seluruh jejak eksekusi database yang dipicu oleh request tersebut.

Menyaring Parameter Query Menggunakan Regex Filter #

Kebocoran data sensitif tidak hanya terjadi pada header HTTP request. Masalah klasik lainnya adalah kebocoran token rahasia atau kunci API yang dikirimkan oleh aplikasi klien melalui parameter URL query string (misalnya, request ke /api/auth/callback?token=rahasia12345).

Secara bawaan, Caddy mencatat parameter query string ini di dalam field request>uri. Kita tidak bisa begitu saja menghapus field request>uri karena kita tetap membutuhkan informasi path URL untuk analisis rute aplikasi. Solusinya adalah menyaring dan mengganti bagian nilai query yang sensitif menggunakan filter ekspresi reguler (regexp):

# Contoh penyaringan token sensitif pada URL query log
example.com {
    log {
        output file /var/log/caddy/access.log
        format json {
            # Filter regexp untuk mendeteksi parameter token di URL query
            # Sintaks: filter <field> regexp <pattern> <replacement>
            # Ini akan mendeteksi token=[karakter] dan menggantinya dengan token=REDACTED
            filter request>uri regexp "token=[a-zA-Z0-9]+" "token=REDACTED"
            
            # Filter tambahan untuk menyembunyikan API key
            filter request>uri regexp "api_key=[a-zA-Z0-9]+" "api_key=REDACTED"
        }
    }
    reverse_proxy localhost:8080
}

Ketika filter di atas dieksekusi, entri log untuk request /users?token=secretXYZ&status=active akan ditulis sebagai /users?token=REDACTED&status=active.

[!TIP] Perhatikan Performa Regex. Pencocokan ekspresi reguler (regex pattern matching) membutuhkan daya komputasi CPU yang lebih besar dibandingkan pencocokan string biasa. Jika server Caddy kita menangani puluhan ribu request per detik, buatlah pola regex sespesifik mungkin dan hindari penggunaan wildcard serakah seperti .* yang dapat memicu penurunan performa penanganan lalu lintas server Caddy.

Analisis Query LogQL pada Grafana Loki #

Setelah kita merancang format log JSON yang bersih dan mengirimkannya ke log aggregator terpusat seperti Grafana Loki, kita dapat menggunakan kekuatan bahasa kueri LogQL untuk melakukan pemantauan sistem secara mendalam tanpa perlu menulis skrip parsing manual.

Berikut adalah beberapa contoh praktis kueri LogQL untuk menganalisis log JSON terstruktur yang dihasilkan oleh Caddy:

1. Menghitung Rata-Rata Waktu Respons (95th Percentile) #

Kita ingin memantau performa latensi respons aplikasi kita untuk rute API. LogQL dapat langsung mengurai objek JSON dan mengekstrak field duration (dalam detik) untuk dihitung sebagai metrik:

# Menghitung durasi pemrosesan request 95th percentile dalam interval 5 menit
quantile_over_time(0.95, {job="caddy-access"} | json | unwrap duration [5m])

2. Mendeteksi Lonjakan Kesalahan Server (HTTP 5xx) #

Kita ingin memantau jika ada backend aplikasi yang mendadak mati dan menyebabkan Caddy mengembalikan error HTTP 502 Bad Gateway atau 504 Gateway Timeout:

# Menampilkan semua entri log yang memiliki status respons HTTP 500 ke atas
{job="caddy-access"} | json | status >= 500

3. Mengelompokkan Volume Request Berdasarkan Domain #

Jika Caddy kita melayani banyak nama domain (multi-tenancy), kita dapat membuat grafik total request per detik yang dikelompokkan berdasarkan host domain:

# Menghitung total request per detik dikelompokkan berdasarkan field host request
sum by (request_host) (rate({job="caddy-access"} | json | __error__="" | unwrap request_host [1m]))

Log Formatting DSL: Single Field & Field Selector #

Caddy menyediakan alat bantu yang sangat efisien untuk memanipulasi format log secara radikal tanpa membuang-buang memori CPU. Konsep ini menggunakan penyeleksi field (field selector) dan format DSL khusus.

1. Single Field Encoder (format single_field) #

Ada kalanya kita tidak membutuhkan data JSON terstruktur yang besar dan kompleks. Sebagai contoh, saat kita men-deploy Caddy di dalam kontainer minimalis (seperti Kubernetes pod) dan kita ingin agar Caddy hanya mengeluarkan string pesan kesalahan mentah saja ke stdout agar bisa langsung diproses oleh supervisor sistem luar:

# Contoh konfigurasi Single Field Encoder
example.com {
    log {
        output stdout
        # Hanya keluarkan nilai dari field "msg" saja sebagai teks biasa.
        # Output: "handled request" atau "connection refused" tanpa ada skema JSON.
        format single_field msg
    }
    reverse_proxy localhost:8080
}

2. Panduan Field Selector Caddy #

Untuk mempermudah kita dalam menyusun filter manipulasi log, berikut adalah tabel referensi penulisan jalur penyeleksi field kustom yang didukung penuh oleh parser log Caddy:

Diagram Alur Pemrosesan Transformasi Log oleh Encoder #

Untuk mempermudah pemahaman kita mengenai siklus pemrosesan data log dari data mentah hingga menjadi string yang aman dan bersih, mari kita perhatikan diagram pipa pemrosesan (processing pipeline) di bawah ini:

flowchart TD
    A["1. Kejadian (Event) Terdeteksi\n(Data biner di memori RAM Caddy)"] --> B["2. Evaluasi Format Encoder Utama\n(e.g., format json / console / logfmt)"]
    
    B --> C{"3. Apakah ada filter 'delete'?"}
    C -- "Ya" --> D["Potong field target dari memori\n(e.g. Hapus header Authorization)"]
    C -- "Tidak" --> E{"4. Apakah ada filter 'ip_mask'?"}
    D --> E
    
    E -- "Ya" --> F["Samarkan bit IP address klien\n(e.g. Ubah 203.0.113.50 -> 203.0.0.0)"]
    E -- "Tidak" --> G{"5. Apakah ada filter 'regexp'?"}
    F --> G
    
    G -- "Ya" --> H["Ganti nilai teks menggunakan regex\n(e.g. token=secret -> token=REDACTED)"]
    G -- "Tidak" --> I["6. Konversi objek akhir menjadi string teks"]
    H --> I
    
    I --> J["7. Serahkan string terformat ke modul Output\n(Tulis ke berkas access.log via Writer)"]

Proses transformasi ini menjamin bahwa modifikasi data log dilakukan sepenuhnya di dalam lingkungan terisolasi memori RAM. Data asli yang sensitif tidak pernah sempat ditulis ke dalam media penyimpanan fisik disk kita, sehingga meminimalisasi risiko kebocoran data akibat serangan peretasan fisik pada server.

Ringkasan #

• Pemisahan Peran: Encoder menangani visualisasi dan struktur data log di memori RAM, sedangkan Writer menangani penyimpanan fisik data tersebut ke tujuan akhir.
• JSON Terstruktur: Format terbaik untuk lingkungan produksi, memudahkan integrasi 100% dengan Elasticsearch dan Grafana Loki tanpa regex tambahan.
• Console Interaktif: Format ramah mata manusia dengan warna penanda level, sangat ideal dipasang hanya di lingkungan development lokal kita.
• Standardisasi Waktu: Gunakan opsi time_format "iso8601" di dalam JSON encoder untuk standarisasi indeks pencarian log di sistem monitoring.
• Perlindungan GDPR: Terapkan filter ip_mask pada request>client_ip guna mematuhi regulasi privasi global dengan menyamarkan alamat IP pengunjung.
• Keamanan Kredensial: Selalu bersihkan log dari data otentikasi sensitif dengan menerapkan filter delete pada header Authorization dan Cookie.
• Redaksi URL Query: Manfaatkan filter regexp untuk mengganti nilai token sesi dinamis di parameter URL query string dengan kata REDACTED.
• Penyeleksi Field: Gunakan karakter pemisah > (bukan tanda titik) untuk menavigasi struktur objek JSON bersarang pada Caddyfile.
• Single Field: Gunakan encoder single_field jika kita ingin menyajikan satu metrik teks mentah saja ke stdout kontainer guna menghemat beban pemrosesan.

← Sebelumnya: Error Log   Berikutnya: Log Output →