Log Output #

Output adalah tujuan akhir dari seluruh aliran data log yang dihasilkan oleh server Caddy setelah melalui tahap pemrosesan dan pemformatan oleh modul encoder. Dalam siklus hidup perekaman log, konfigurasi output yang tepat memegang peranan krusial untuk menjaga stabilitas sistem dan efisiensi operasional. Kesalahan dalam menentukan target keluaran atau kelalaian dalam mengatur kebijakan penyimpanan dapat berakibat fatal, mulai dari disk server penuh yang memicu crash seluruh sistem, hingga hilangnya data audit penting saat terjadi insiden keamanan. Caddy menawarkan dukungan bawaan yang sangat fleksibel terhadap berbagai jenis target output: mulai dari penulisan ke berkas lokal dengan fitur rotasi otomatis (log rotation), standard output streams (stdout dan stderr) yang sangat ideal untuk containerization, target discard untuk membuang lalu lintas log tidak penting, hingga streaming langsung melalui jaringan (network socket) ke server pengumpul log pusat. Kita akan mempelajari karakteristik masing-masing tipe output, cara mengonfigurasi rotasi log secara agresif, strategi logging di lingkungan container dan Kubernetes, penanganan buffering untuk performa tinggi, hingga teknik pemisahan berkas log secara modular.

Tipe Output yang Tersedia di Caddy #

Caddy membagi target keluaran log menjadi lima modul output utama. Memahami perbedaan karakteristik kinerja dan tujuan dari kelima tipe ini sangat penting agar kita dapat memilih strategi logging yang paling sesuai dengan arsitektur infrastruktur server kita.

Berikut adalah ringkasan singkat dari tipe-tipe output yang didukung secara bawaan oleh Caddy:

• file — Menuliskan baris log ke dalam berkas fisik di media penyimpanan lokal. Sangat cocok untuk deployment tradisional di Virtual Machine (VM) atau Bare Metal karena dilengkapi dengan sistem rotasi, pembatasan ukuran, kompresi, dan manajemen retensi berkas secara otomatis.
• stdout — Mengalirkan data log ke Standard Output (File Descriptor 1). Ini merupakan standar emas untuk aplikasi kontainer karena runtime kontainer seperti Docker dan Kubernetes akan menangkap stream ini untuk diserahkan ke agen logging level node.
• stderr — Mengalirkan data log ke Standard Error (File Descriptor 2). Ini adalah output default global dari sistem Caddy jika kita tidak mendefinisikan direktif output secara eksplisit.
• discard — Membuang seluruh entri log yang masuk tanpa memproses atau menulisnya ke media mana pun. Sangat berguna untuk mengabaikan logging pada endpoint dengan lalu lintas tinggi namun tidak memiliki nilai audit.
• net — Mengirimkan log secara real-time melalui koneksi jaringan (socket TCP atau UDP) ke remote server pengumpul log seperti Syslog daemon, Logstash, Fluentd, atau Grafana Loki.

Untuk memberikan gambaran perbandingan yang lebih jelas, mari kita perhatikan tabel di bawah ini yang membandingkan kecocokan setiap tipe output berdasarkan metrik operasional:

Output ke Berkas Lokal (File Logging) #

Menulis log ke dalam berkas lokal di disk merupakan pendekatan yang paling umum digunakan pada arsitektur server tradisional. Berikut adalah contoh penulisan dasar direktif log dengan target berkas pada Caddyfile:

# Contoh konfigurasi logging ke berkas lokal dasar
example.com {
    log {
        output file /var/log/caddy/access.log
        format json
    }
    reverse_proxy localhost:8080
}

Pentingnya Rotasi Berkas Otomatis (Log Rotation) #

Menulis log secara terus-menerus ke satu berkas tunggal tanpa batas adalah salah satu penyebab utama kegagalan operasional server produksi. Seiring berjalannya waktu, file log akses akan terus membesar hingga mencapai puluhan atau ratusan gigabyte, menghabiskan seluruh kapasitas ruang hard disk, dan akhirnya menyebabkan kernel sistem operasi menghentikan proses server Caddy secara paksa (out-of-space crash).

Caddy mengatasi masalah ini secara elegan dengan menyediakan modul rotasi berkas otomatis (log rotation) yang terintegrasi langsung di dalam modul output file. Kita tidak memerlukan utilitas pihak ketiga seperti logrotate bawaan Linux.

Berikut adalah contoh konfigurasi manajemen rotasi berkas log secara lengkap dan aman di Caddyfile:

# Contoh konfigurasi lengkap dengan manajemen rotasi log
example.com {
    log {
        output file /var/log/caddy/access.log {
            # 1. Rotasi berkas jika ukurannya mencapai 100 Megabyte.
            # Caddy akan mengganti nama file aktif menjadi nama ber-timestamp,
            # dan membuat berkas access.log baru yang kosong secara otomatis.
            roll_size 100mb
            
            # 2. Batasi jumlah berkas arsip log yang disimpan maksimal 7 file.
            # Berkas arsip tertua ke-8 akan dihapus secara otomatis.
            roll_keep 7
            
            # 3. Hapus berkas arsip log yang usianya sudah melebihi 30 hari.
            # Membantu kepatuhan retensi data tanpa membebani disk.
            roll_keep_days 30
            
            # 4. Secara default, Caddy mengompresi file log terotasi menjadi berkas .gz.
            # Jika kita ingin menonaktifkan kompresi gzip demi kecepatan CPU,
            # kita dapat mengaktifkan opsi di bawah ini (tidak direkomendasikan).
            # roll_uncompressed
        }
        format json
    }
    reverse_proxy localhost:8080
}

Cara Kerja Penamaan Berkas Rotasi Caddy #

Ketika kriteria roll_size terpenuhi, Caddy akan menutup berkas log aktif /var/log/caddy/access.log, lalu mengganti namanya menggunakan format penomoran timestamp ISO-8601 lokal seperti berikut:

/var/log/caddy/access-2026-06-16T18-44-15.000.log.gz

Karena berkas diarsipkan dalam format .gz terkompresi secara default, ukuran file arsip biasanya menyusut hingga 80-90% dari ukuran aslinya. Hal ini sangat menghemat kapasitas penyimpanan disk kita secara signifikan.

Penulisan Log ke stdout dan stderr (Containerization) #

Dalam era infrastruktur modern berbasis cloud dan kontainer, praktik menulis log ke berkas lokal di dalam kontainer dianggap sebagai sebuah anti-pattern. Kontainer dirancang bersifat sekali pakai (ephemeral), yang berarti data di dalam sistem file kontainer akan hilang ketika kontainer di-restart atau di-build ulang.

Berdasarkan metodologi The Twelve-Factor App untuk membangun aplikasi modern, log harus diperlakukan sebagai aliran kejadian (event streams). Aplikasi tidak boleh dibebani dengan tanggung jawab mengelola berkas lognya sendiri. Sebaliknya, aplikasi harus menuliskan seluruh lognya secara mentah ke stdout (standard output) atau stderr (standard error).

Caddy sangat mematuhi filosofi ini. Kita dapat mengarahkan log Caddy langsung ke stdout terminal kontainer:

# Contoh konfigurasi logging cloud-native untuk Docker / Kubernetes
example.com {
    log {
        output stdout
        format json
    }
    reverse_proxy localhost:8080
}

Ketika kita menjalankan Caddy di dalam Docker menggunakan konfigurasi di atas, runtime Docker akan menangkap seluruh aliran teks JSON dari stdout Caddy secara real-time. Docker kemudian akan menyerahkan data log tersebut ke log driver yang terkonfigurasi pada host Docker (misalnya json-file, journald, atau syslog).

Berikut adalah contoh konfigurasi docker-compose.yml yang menerapkan pembatasan ukuran log di tingkat Docker host:

version: '3.8'

services:
  caddy:
    image: caddy:2.8.4-alpine
    restart: always
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - caddy_data:/data
      - caddy_config:/config
    # Mengatur log driver pada level Docker untuk mencegah disk host penuh
    logging:
      driver: "json-file"
      options:
        max-size: "50m"
        max-file: "3"

volumes:
  caddy_data:
  caddy_config:

Kita dapat memantau log kontainer Caddy secara real-time dari terminal host dengan perintah berikut:

# Memantau 100 baris log terakhir dan terus mengalir (follow)
docker logs caddy --tail 100 -f

# Memantau log dan mem-parsing JSON agar rapi menggunakan utilitas jq
docker logs caddy -f 2>&1 | jq .

Output discard: Menonaktifkan Logging #

Tidak semua request HTTP memiliki nilai penting untuk diaudit. Pada lingkungan produksi berskala besar, server Caddy kita sering kali dibombardir oleh ribuan request otomatis dari sistem luar, seperti:

1. Panggilan health check dari Load Balancer (misalnya AWS ALB atau HAProxy) yang memeriksa kesehatan server setiap beberapa detik sekali.
2. Request aset statis berukuran kecil (seperti file favicon, file CSS, gambar ikon) yang diakses berulang kali oleh browser klien.

Jika request pemantau kesehatan (health check) ini terus dicatat ke berkas log akses utama, ukuran berkas log kita akan membengkak dengan cepat oleh informasi sampah. Ini mempersulit pencarian log transaksi riil milik pengguna manusia.

Caddy menyediakan modul output discard yang berfungsi sebagai “lubang hitam” (blackhole) untuk membuang log tanpa memprosesnya sama sekali. Kita dapat memadukan named matcher dengan direktif log untuk menyaring lalu lintas log ini:

# Contoh mengabaikan logging untuk health check LB dan mematikan log global
example.com {
    # Buat named matcher untuk mendeteksi rute healthcheck
    @healthcheck {
        path /healthz
        method GET
    }

    # Terapkan penanganan modular:
    # Rute health check akan diproses tanpa dicatat ke berkas log akses utama
    handle @healthcheck {
        log {
            output discard
        }
        respond "OK" 200
    }

    # Request rute selain health check akan dicatat ke berkas utama
    handle {
        log {
            output file /var/log/caddy/access.log {
                roll_size 50mb
                roll_keep 3
            }
            format json
        }
        reverse_proxy localhost:8080
    }
}

Dengan taktik modular di atas, performa I/O server Caddy tetap terjaga optimal karena penulisan log hanya difokuskan pada transaksi bisnis yang penting.

Output net: Streaming Log Jaringan (Remote Logging) #

Pada infrastruktur berskala besar yang terdiri dari puluhan hingga ratusan server Caddy di bawah autoscaling groups, mengelola file log lokal di setiap VM adalah mimpi buruk bagi tim operasional. Kita harus masuk ke setiap VM secara manual untuk memeriksa log, atau membuat skrip cron rumit untuk menyalin file log secara berkala.

Solusi terbaiknya adalah mengirimkan log Caddy secara real-time langsung melalui jaringan ke log aggregator terpusat. Caddy menyediakan modul output net yang dapat mengalirkan log melalui protokol TCP atau UDP.

1. Remote Logging Menggunakan Protokol UDP #

UDP adalah protokol tanpa koneksi (connectionless). Caddy akan mengirimkan paket log tanpa menunggu konfirmasi apakah paket tersebut telah sampai di server pengumpul log atau tidak.

# Contoh streaming log via UDP ke remote Syslog server
{
    log {
        # Format: output net udp/<host>:<port>
        # Sangat cepat, tanpa overhead koneksi, namun ada risiko data hilang jika jaringan tidak stabil
        output net udp/syslog-server.local:514
        format json
    }
}

2. Remote Logging Menggunakan Protokol TCP #

TCP adalah protokol berorientasi koneksi yang menjamin pengiriman paket data secara aman dan berurutan.

# Contoh streaming log via TCP ke remote Logstash / Loki
{
    log {
        # Format: output net tcp/<host>:<port>
        # Menjamin seluruh log terkirim, namun dapat memicu sedikit latensi jika server tujuan lambat
        output net tcp/logstash.local:5000
        format json
    }
}

Konfigurasi Integrasi Syslog Lokal di Linux #

Jika kita ingin Caddy mengirimkan log ke daemon syslog lokal yang berjalan di server Linux yang sama, kita dapat mengonfigurasi Syslog rsyslog untuk mendengarkan port UDP lokal:

# Tambahkan konfigurasi berikut pada berkas /etc/rsyslog.d/caddy.conf:
# 1. Muat modul UDP dan jalankan server pada port 514 lokal
$ModLoad imudp
$UDPServerRun 514

# 2. Tangkap log dari program caddy dan simpan ke file terpisah
:programname, isequal, "caddy" /var/log/caddy/syslog-caddy.log
& stop

Setelah rsyslog di-restart (systemctl restart rsyslog), seluruh aliran log dari Caddy via output net udp/127.0.0.1:514 akan secara aman dicatat ke dalam berkas syslog pusat server.

Buffering dan Flush Interval #

Menulis data ke media penyimpanan fisik (SSD/HDD) untuk setiap baris log yang dihasilkan adalah operasi I/O yang sangat mahal secara komputasi. Jika server Caddy melayani ribuan request per detik, disk I/O akan menjadi hambatan utama (bottleneck) yang membatasi kecepatan respons server.

Untuk meningkatkan performa penulisan, Caddy menerapkan teknik buffering memori secara internal. Caddy tidak langsung menulis log ke disk begitu request selesai diproses. Sebaliknya, Caddy mengumpulkan beberapa baris log terlebih dahulu di dalam buffer memori RAM sementara. Setelah ukuran buffer mencapai batas tertentu atau setelah interval waktu pembilasan (flush interval) tercapai, Caddy akan menuliskan seluruh tumpukan log tersebut ke disk sekaligus dalam satu operasi I/O.

Namun, strategi ini memiliki sebuah kompromi (trade-off):

[!WARNING] Risiko Kehilangan Data pada Buffering Memori. Karena sebagian data log terbaru masih tertahan di memori RAM sebelum dibilas ke disk, terjadi risiko hilangnya log jika server tiba-tiba mengalami mati listrik secara mendadak, mengalami kegagalan kernel (kernel panic), atau proses Caddy dihentikan paksa menggunakan sinyal SIGKILL. Data log yang berada di dalam buffer RAM akan hilang selamanya dan tidak pernah tercatat ke disk.

Untuk aplikasi kritikal yang memerlukan audit kepatuhan tanpa toleransi kehilangan data, pertimbangkan untuk mengalirkan log ke stdout atau menggunakan remote logging dengan protokol TCP yang andal.

Log ke Multiple Files Menggunakan Penanganan Modular (Handle) #

Dalam arsitektur web modern, kita sering kali dihadapkan pada skenario di mana kita ingin memisahkan tujuan berkas log berdasarkan karakteristik rute lalu lintas aplikasi. Sebagai contoh:

• Lalu lintas API (/api/*) harus dicatat ke berkas khusus /var/log/caddy/api-access.log dengan retensi rotasi yang lama (misal 90 hari) untuk kebutuhan audit transaksi bisnis.
• Lalu lintas aset statis atau halaman web biasa dicatat ke berkas /var/log/caddy/web-access.log dengan rotasi agresif (retensi 7 hari saja) untuk menghemat kapasitas disk.

Caddyfile membolehkan kita mendefinisikan blok log terpisah di dalam blok penanganan modular handle untuk mencapai isolasi berkas log ini:

# Contoh pemisahan log ke berkas berbeda menggunakan handle modular
example.com {
    # Penanganan khusus untuk rute API
    handle /api/* {
        log {
            output file /var/log/caddy/api-access.log {
                roll_size 200mb
                roll_keep 14
                roll_keep_days 90 # Retensi audit jangka panjang
            }
            format json
        }
        reverse_proxy api-backend:8080
    }
    
    # Penanganan default untuk rute lainnya
    handle {
        log {
            output file /var/log/caddy/web-access.log {
                roll_size 50mb
                roll_keep 3
                roll_keep_days 7 # Retensi jangka pendek
            }
            format json
        }
        file_server { root /var/www/html }
    }
}

Perencanaan Kapasitas: Estimasi Kebutuhan Disk untuk Log #

Sebelum men-deploy server Caddy ke lingkungan produksi skala besar, kita harus melakukan kalkulasi kapasitas penyimpanan untuk merancang spesifikasi hard disk server. Kita dapat memperkirakan konsumsi ruang disk harian log Caddy dengan langkah-langkah praktis berikut:

1. Menghitung Rata-Rata Ukuran per Baris Log #

Kita dapat mengambil sampel 100 baris log akses aktif dan menghitung ukuran byte rata-ratanya menggunakan perintah shell berikut di server Linux kita:

# Menghitung rata-rata ukuran per baris entri log (dalam bytes)
head -100 /var/log/caddy/access.log | \
    awk '{sum += length($0)} END {print "Avg entry size:", sum/NR, "bytes"}'

Biasanya, satu baris JSON log akses Caddy berukuran sekitar 400 hingga 700 bytes (tergantung seberapa banyak data header HTTP yang ikut dicatat).

2. Rumus Estimasi Kebutuhan Ruang Disk Harian #

Gunakan rumus matematika sederhana di bawah ini untuk memperkirakan pertumbuhan log harian:

[\text{Kapasitas Harian (Bytes)} = \text{Jumlah Request Per Detik (RPS)} \times 86400 \text{ detik} \times \text{Ukuran Rata-Rata Entry (Bytes)}]

Sebagai contoh skenario dunia nyata:

• Rata-rata lalu lintas server: 500 request per detik (RPS).
• Ukuran rata-rata per entri log: 500 bytes.
• Estimasi data mentah per hari: [500 \times 86400 \times 500 = 21,600,000,000 \text{ bytes} \approx 21.6 \text{ GB per hari}]
• Jika kita mengaktifkan fitur rotasi dengan kompresi gzip (asumsi rasio kompresi 80%), konsumsi riil akan menyusut menjadi: [21.6 \text{ GB} \times 0.20 \approx 4.32 \text{ GB per hari}]

Strategi Output Berdasarkan Lingkungan (Development vs Staging vs Production) #

Untuk memberikan panduan praktis yang siap pakai, berikut adalah rangkuman praktik terbaik konfigurasi output log Caddy yang disesuaikan dengan karakteristik masing-masing lingkungan kerja:

1. Lingkungan Development Lokal #

Pada komputer lokal, kita mengutamakan kemudahan membaca proses debug secara langsung di terminal console.

# Konfigurasi Caddyfile - Lingkungan Development Lokal
{
    # Aktifkan level debug global
    debug
}

localhost:8080 {
    log {
        output stderr    # Keluarkan ke terminal stderr
        format console   # Format teks berwarna ramah mata manusia
        level debug      # Rekam hingga informasi debug detail
    }
    file_server { root ./public }
}

2. Lingkungan Staging #

Staging adalah replika produksi. Kita ingin log sudah berformat JSON dan dicatat ke berkas, namun dengan verbositas level yang lebih tinggi untuk mempermudah QA mendeteksi bug integrasi.

# Konfigurasi Caddyfile - Lingkungan Staging
staging.example.com {
    log {
        output file /var/log/caddy/staging-access.log {
            roll_size 50mb
            roll_keep 3
            roll_keep_days 7
        }
        format json
        level info
    }
    reverse_proxy staging-app:8000
}

3. Lingkungan Produksi Skala Besar #

Di produksi, kita memprioritaskan performa tinggi, retensi jangka panjang untuk compliance keamanan, dan proteksi dari disk penuh.

# Konfigurasi Caddyfile - Lingkungan Produksi
example.com {
    log {
        output file /var/log/caddy/production-access.log {
            roll_size 500mb     # Ukuran file lebih besar agar tidak terlalu sering rotasi saat peak
            roll_keep 14        # Retensi 2 minggu arsip
            roll_keep_days 90   # 3 bulan retensi log historis
        }
        # Gunakan format json dengan filter pembersihan data sensitif
        format json {
            filter request>headers>Authorization delete
            filter request>headers>Cookie delete
            filter request>client_ip ip_mask 16 32
        }
        level warn # Hanya rekam level warning ke atas untuk menghemat I/O (opsional)
    }
    reverse_proxy production-app:8000
}

Diagram Alur Penulisan Log Entry Caddy #

Untuk memberikan visualisasi perjalanan data log dari modul pemrosesan internal hingga didistribusikan ke berbagai media keluaran, mari kita pelajari diagram alir (flowchart) di bawah ini:

flowchart TD
    A["Kejadian Log Terformat\n(JSON / Teks Terstruktur)"] --> B{"Tipe Output Terkonfigurasi"}
    
    B -->|"output file"| C["Modul File Writer"]
    B -->|"output stdout / stderr"| D["Modul Stream Writer"]
    B -->|"output net"| E["Modul Network Writer"]
    B -->|"output discard"| F["Modul Blackhole"]
    
    C --> C1{"Apakah ukuran file > roll_size?"}
    C1 -- "Ya" --> C2["Proses Rotasi Berkas\n(Ubah nama & kompresi .gz)"]
    C2 --> C3["Evaluasi Retensi\n(Batasi roll_keep / roll_keep_days)"]
    C1 -- "Tidak" --> C4["Tulis ke penyimpanan disk fisik"]
    C3 --> C4
    
    D --> D1["Aliran teks masuk ke shell terminal"]
    D1 --> D2["Ditangkap oleh Log Driver host\n(e.g., Docker Engine / systemd)"]
    
    E --> E1["Bungkus data ke dalam paket jaringan"]
    E1 --> E2{"Protokol Pilihan?"}
    E2 -- "UDP" --> E3["Kirim cepat tanpa konfirmasi\n(Fire and Forget)"]
    E2 -- "TCP" --> E4["Koneksi jabat tangan aman\n(Guaranteed Delivery)"]
    
    F --> F1["Data dihapus instan dari RAM\n(Tanpa konsumsi resource I/O)"]

Pipa distribusi di atas menunjukkan fleksibilitas arsitektur logging Caddy yang modular, di mana penanganan akhir aliran log sepenuhnya disesuaikan dengan kebutuhan arsitektur sistem yang kita bangun.

Ringkasan #

• Manajemen Disk: Selalu konfigurasikan roll_size, roll_keep, dan roll_keep_days pada output file guna mencegah risiko disk server penuh yang memicu sistem crash.
• Standar Kontainer: Gunakan output stdout di lingkungan kontainer (Docker/Kubernetes) agar log dapat dikelola secara eksternal oleh log driver runtime host.
• Optimalisasi I/O: Manfaatkan output discard berpasangan dengan named matcher untuk mengabaikan logging request health check load balancer guna menghemat resource I/O disk.
• Distribusi Terpusat: Kirimkan log secara real-time ke log aggregator jarak jauh menggunakan output net dengan pilihan protokol TCP (keandalan) atau UDP (kecepatan).
• Performa Buffering: Caddy melakukan buffering log di memori RAM untuk performa tinggi, namun sadari adanya risiko kehilangan log terbaru jika terjadi mati listrik mendadak.
• Pemisahan Log Terarah: Gunakan blok handle modular untuk memisahkan direktori tujuan penulisan log akses (misalnya log API dipisah dari log web biasa).
• Kalkulasi Kapasitas: Lakukan estimasi konsumsi ruang disk log harian dengan menghitung rata-rata ukuran per baris JSON log sebelum men-deploy server ke produksi.

← Sebelumnya: Format Log   Berikutnya: xcaddy →