Tools Diagnostik #

Mendiagnosis masalah jaringan dan server web tidak boleh dilakukan berdasarkan tebakan atau intuisi tanpa dasar. Menguasai alat diagnostik (diagnostic tools) yang tepat dapat mengubah proses pemecahan masalah (troubleshooting) yang membingungkan menjadi investigasi yang sistematis, presisi, dan efisien. Artikel ini mengulas secara mendalam arsenal alat bantu wajib bagi setiap administrator sistem yang mengelola Caddy, lengkap dengan parameter perintah produksi dan interpretasi hasilnya secara detail.

Alur Data Observabilitas Log & Metrik Caddy #

Dalam mengelola Caddy skala besar, kita tidak hanya mengandalkan pengecekan manual di terminal, melainkan menyusun pipa pengumpulan data (data pipeline) terpadu untuk memantau kesehatan server secara visual.

Berikut adalah visualisasi alur perpindahan data log dan metrik dari Caddy menuju sistem pemantauan terpusat:

flowchart LR
    Caddy["Caddy Web Server"] -->|"JSON Logs"| LogFile["api-access.log"]
    LogFile -->|"Scrape"| Promtail["Grafana Promtail"]
    Promtail -->|"Push HTTP"| Loki["Grafana Loki"]
    Loki -->|"Query LogQL"| Grafana["Grafana Dashboard"]
    
    Caddy -->|"Metrics (/metrics)"| Prometheus["Prometheus Server"]
    Prometheus -->|"Query PromQL"| Grafana
    
    style Caddy stroke:#0288d1,stroke-width:2px
    style Grafana stroke:#7b1fa2,stroke-width:2px

Dengan memahami alur ini, kita bisa menelusuri di mana data diagnostik kita tersimpan dan bagaimana memanfaatkannya saat terjadi kegagalan sistem.

curl — Swiss Army Knife HTTP #

curl adalah alat utama untuk memverifikasi respons HTTP secara langsung dari terminal. Kita bisa mengisolasi perilaku header, status kode, dan memetakan waktu latensi di setiap tahapan koneksi.

Penjelasan Parameter Timing pada curl #

Saat kita menjalankan pengujian latensi dengan curl, kita mendapatkan beberapa variabel waktu yang sangat penting untuk dianalisis:

  1. time_namelookup (Pencarian DNS): Waktu yang dibutuhkan (dalam detik) sejak awal permintaan hingga resolusi nama domain selesai. Jika nilai ini tinggi (misal > 0.5s), berarti server DNS kita lambat atau mengalami masalah propagasi.
  2. time_connect (Handshake TCP): Waktu yang dibutuhkan untuk menjalin koneksi TCP (3-way handshake) antara klien dan Caddy. Nilai yang besar menandakan adanya latensi jaringan fisik atau firewall yang memperlambat paket SYN-ACK.
  3. time_appconnect (Jabat Tangan TLS/SSL): Waktu hingga jabat tangan TLS selesai. Jika tahapan ini memakan waktu lama, bisa jadi karena komputasi SSL yang berat pada server atau negosiasi versi protokol yang tidak optimal.
  4. time_starttransfer (TTFB - Time to First Byte): Waktu sejak request dikirim hingga byte pertama respons diterima dari Caddy. Ini adalah indikator performa backend: jika TTFB tinggi, berarti backend lambat memproses logika aplikasi atau query database.
  5. time_total (Total Waktu): Waktu keseluruhan transaksi selesai.
# 1. Mengirim permintaan dengan output verbose lengkap
# Menampilkan detail jabat tangan TLS, header request (>), dan header response (<)
curl -v https://example.com

# 2. Mengambil header respons saja (tanpa mengunduh bodi berkas)
curl -I https://example.com

# 3. Menampilkan status kode HTTP saja (sangat berguna untuk skrip otomatisasi)
curl -o /dev/null -s -w "%{http_code}\n" https://example.com

# 4. Breakdown metrik waktu koneksi secara detail
curl -o /dev/null -s -w "
Pencarian DNS:  %{time_namelookup}s
Handshake TCP:  %{time_connect}s
Jabat Tangan TLS: %{time_appconnect}s
TTFB Backend:   %{time_starttransfer}s
Total Waktu:    %{time_total}s
Ukuran Respon:  %{size_download} bytes
Status HTTP:    %{http_code}
" https://example.com

# 5. Mengirim request dengan custom header dan autentikasi token
curl -H "Authorization: Bearer token123" \
     -H "X-Gateway-Trace: debug-mode" \
     https://api.example.com/v1/users

# 6. Mengirim data berformat JSON (POST Request)
curl -X POST https://api.example.com/v1/users \
     -H "Content-Type: application/json" \
     -d '{"name": "Budi", "role": "admin"}'

# 7. Mengikuti rantai redirect (Location header) dan melihat alurnya
curl -L -v https://www.example.com 2>&1 | grep -E "< HTTP|Location:"

# 8. Memaksa pengujian menggunakan versi TLS tertentu
curl --tlsv1.3 https://example.com
curl --tlsv1.2 https://example.com

# 9. Mengabaikan validasi sertifikat SSL (Hanya untuk keperluan pengujian lokal!)
curl -k https://localhost:8443/

openssl — TLS/SSL Diagnostik #

Saat Caddy mengalami masalah sertifikat SSL/TLS, kita menggunakan openssl untuk memeriksa secara mendalam rantai sertifikat (certificate chain) dan kecocokan algoritma keamanan (cipher suite).

# 1. Mengunduh dan menampilkan seluruh data sertifikat yang disajikan oleh Caddy
echo | openssl s_client -connect example.com:443 -servername example.com 2>/dev/null | \
    openssl x509 -noout -text

# 2. Menampilkan ringkasan subjek, penerbit, dan masa aktif sertifikat
echo | openssl s_client -connect example.com:443 2>/dev/null | \
    openssl x509 -noout -subject -issuer -dates

# 3. Menampilkan seluruh rantai kepercayaan sertifikat (Chain of Trust)
# Membantu memastikan apakah Root CA dan Intermediate CA terkirim secara utuh
echo | openssl s_client -connect example.com:443 -showcerts 2>/dev/null | \
    grep -E "subject=|issuer="

# 4. Memverifikasi berkas sertifikat lokal menggunakan berkas CA sistem
openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt /var/lib/caddy/.local/share/caddy/certificates/acme-v02.api.letsencrypt.org-directory/example.com/example.com.crt

# 5. Memeriksa tanggal kedaluwarsa sertifikat
echo | openssl s_client -connect example.com:443 2>/dev/null | \
    openssl x509 -noout -enddate

dig / nslookup — DNS Diagnostik #

Tantangan sertifikat otomatis Caddy (ACME) sangat bergantung pada DNS. Jika domain kita tidak mengarah ke IP publik server dengan benar, Let’s Encrypt akan gagal melakukan validasi.

# 1. Mengambil IP Address (A record) secara singkat
dig example.com A +short

# 2. Mengambil IP Address IPv6 (AAAA record)
dig example.com AAAA +short

# 3. Melacak jalur resolusi DNS dari Root DNS hingga Nameserver domain kita (DNS Trace)
# Sangat berguna untuk mendeteksi caching DNS yang usang
dig example.com +trace

# 4. Memeriksa TXT record
# Wajib dilakukan saat mendebug kegagalan DNS-01 Challenge
dig _acme-challenge.example.com TXT

# 5. Menguji propagasi DNS ke berbagai DNS resolver publik dunia secara cepat
for dns in 8.8.8.8 1.1.1.1 9.9.9.9; do
    echo -n "DNS $dns: "
    dig @$dns example.com A +short
done

ss / netstat — Network Sockets #

Kita menggunakan ss untuk mendeteksi port mana saja yang terbuka, mendeteksi konflik binding port, serta menghitung jumlah koneksi aktif yang sedang ditangani oleh proses Caddy.

# 1. Menampilkan semua port TCP yang sedang dalam status LISTENING lengkap dengan nama prosesnya
sudo ss -tlnp

# 2. Memfilter port spesifik yang digunakan oleh Caddy dan Admin API
sudo ss -tlnp | grep -E ':80|:443|:2019'

# 3. Menghitung jumlah koneksi TCP aktif yang saat ini terhubung ke proses Caddy
sudo ss -tnp | grep caddy | wc -l

# 4. Menganalisis jumlah koneksi berdasarkan status soket (ESTABLISHED, TIME_WAIT, dll.)
sudo ss -tan | awk '{print $1}' | sort | uniq -c | sort -rn

journalctl — Systemd Logs #

Pada distribusi Linux modern, log standar Caddy yang dijalankan sebagai layanan sistem dikumpulkan oleh unit systemd-journald.

# 1. Memantau log Caddy secara real-time (Tailing)
sudo journalctl -u caddy -f

# 2. Melihat log Caddy khusus untuk boot sistem saat ini
sudo journalctl -u caddy -b

# 3. Memfilter log Caddy dalam rentang waktu 1 jam terakhir
sudo journalctl -u caddy --since "1 hour ago"

# 4. Menyaring log khusus pada level ERROR dan WARNING saja
sudo journalctl -u caddy -p err..warning --no-pager

# 5. Mengekstrak dan mencari teks tertentu dalam log (misal TLS handshake issues)
sudo journalctl -u caddy | grep -i "handshake" | tail -n 20

tcpdump — Raw Packet Capture #

Ketika masalah jaringan berada di tingkat paket data terendah (seperti gangguan rute MTU atau pemotongan paket oleh firewall jaringan), kita perlu menggunakan tcpdump untuk merekam paket jaringan mentah.

# 1. Merekam lalu lintas pada port 443 pada interface jaringan tertentu (misal eth0)
# -n menonaktifkan resolusi nama domain agar pemrosesan cepat
sudo tcpdump -i eth0 port 443 -n

# 2. Merekam paket data port 80/443 dan menyimpannya ke berkas pcap
# Berkas ini nantinya dapat diunduh dan dianalisis secara visual menggunakan Wireshark
sudo tcpdump -i any port 80 or port 443 -w /tmp/caddy-traffic.pcap

# 3. Membaca isi berkas rekaman pcap secara terbatas
sudo tcpdump -r /tmp/caddy-traffic.pcap | head -n 30

Menganalisis Berkas Capture PCAP dengan Wireshark #

Setelah kita membuat berkas caddy-traffic.pcap menggunakan tcpdump, kita bisa membukanya di Wireshark untuk melakukan debugging tingkat lanjut:

  • Mencari TCP Retransmissions: Filter dengan tcp.analysis.retransmission. Jika banyak paket retransmisi, berarti ada packet loss antara klien dan Caddy.
  • Menganalisis TLS Client Hello: Cari paket Client Hello untuk melihat versi TLS dan cipher suites yang ditawarkan oleh browser klien menggunakan filter tls.handshake.type == 1.
  • Mengidentifikasi RST (Reset) Packets: Filter dengan tcp.flags.reset == 1 untuk melihat apakah koneksi ditutup secara sepihak oleh klien, Caddy, atau middleware jaringan.

Caddy Admin API Diagnostics #

Caddy menyediakan REST API bawaan pada port localhost:2019 untuk memantau keadaan internal runtime secara langsung.

Penjelasan Respons JSON API Upstream #

Ketika kita memanggil endpoint http://localhost:2019/reverse_proxy/upstreams/, Caddy akan mengembalikan array objek JSON yang merepresentasikan status setiap upstream server:

  • address: Alamat IP dan port backend (misal 127.0.0.1:3000).
  • healthy: Status boolean kesehatan upstream berdasarkan pemantau pasif/aktif.
  • num_requests: Jumlah koneksi HTTP aktif yang saat ini sedang diproses oleh upstream tersebut.
  • fails: Akumulasi kegagalan koneksi TCP yang terdeteksi dalam jendela waktu pemantau pasif.
# 1. Memantau status kesehatan server backend (upstreams) secara aktif
curl -s http://localhost:2019/reverse_proxy/upstreams/ | \
    jq -r '.[] | "\(.address): \(if .healthy then "UP" else "DOWN" end) (active connections: \(.num_requests), fails: \(.fails))"'

# 2. Menampilkan konfigurasi perutean aktif yang diterjemahkan Caddy
curl -s http://localhost:2019/config/apps/http/servers/srv0/routes/ | jq .

wrk / ab — Load Testing #

Sebelum melepaskan konfigurasi Caddy baru ke lingkungan produksi, kita perlu menguji ketahanan server terhadap beban tinggi (load testing).

# Menggunakan wrk (alat load testing berbasis HTTP berkinerja tinggi)
# Parameter: 4 utas (threads), 100 koneksi simultan, durasi 30 detik
wrk -t4 -c100 -d30s https://example.com/

# Menggunakan Apache Benchmark (ab) untuk pengujian cepat
# Mengirim total 1000 request dengan concurrency 100 request simultan
ab -n 1000 -c 100 https://example.com/

mtr — Network Path Analysis #

mtr menggabungkan fungsionalitas ping dan traceroute untuk menganalisis kualitas koneksi jaringan dari server kita menuju server tujuan/klien.

# Menjalankan pemantauan rute jaringan secara interaktif
mtr example.com

# Menghasilkan laporan statis (non-interaktif, mengirim 20 paket)
# Berguna untuk dikirimkan ke tim infrastruktur cloud
mtr --report --report-cycles 20 example.com

httpie — Alternatif curl yang Lebih User-Friendly #

httpie adalah alat bantu terminal alternatif untuk mengirim HTTP request dengan sintaksis yang jauh lebih mudah diingat manusia dan dilengkapi visualisasi teks berwarna (syntax highlighting). Alat ini sangat disarankan untuk pengembang API karena kita tidak perlu lagi memikirkan pembungkusan tanda kutip ganda dan pendefinisian header Content-Type yang rumit saat melakukan pengiriman data berformat JSON, karena httpie secara otomatis mem-parse argumen masukan dan menyesuaikan header request yang tepat.

# 1. Mengirim GET request biasa (output terformat indah secara otomatis)
http https://api.example.com/v1/users

# 2. Mengirim POST data berformat JSON (tidak perlu menulis header manual)
http POST https://api.example.com/v1/users \
    name="Dewi" \
    email="[email protected]"

# 3. Mengirim request dengan otentikasi basic
http --auth admin:secret https://example.com/admin/

Grafana + Loki + Promtail Stack (Visualisasi Log Terpusat) #

Untuk analisis log jangka panjang, kita mengagregasikan log JSON Caddy secara terpusat menggunakan Docker compose stack.

Berkas docker-compose.yml untuk menjalankan Loki stack lokal:

version: "3.8"

services:
  loki:
    image: grafana/loki:3.0.0
    ports:
      - "3100:3100"
    command: -config.file=/etc/loki/local-config.yaml
    networks:
      - monitoring

  promtail:
    image: grafana/promtail:3.0.0
    volumes:
      - /var/log/caddy:/var/log/caddy:ro
      - ./promtail-config.yml:/etc/promtail/config.yml
    command: -config.file=/etc/promtail/config.yml
    networks:
      - monitoring

  grafana:
    image: grafana/grafana:10.4.0
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin
    networks:
      - monitoring

networks:
  monitoring:
    driver: bridge

Berkas konfigurasi Promtail (promtail-config.yml) untuk mem-parse berkas log JSON Caddy:

server:
  http_listen_port: 9080
  grpc_listen_port: 0

positions:
  filename: /tmp/positions.yaml

clients:
  - url: http://loki:3100/loki/api/v1/push

scrape_configs:
  - job_name: caddy-access-logs
    static_configs:
      - targets:
          - localhost
        labels:
          job: caddy
          __path__: /var/log/caddy/*.log
    pipeline_stages:
      - json:
          expressions:
            status: status
            duration: duration
            method: request.method
            uri: request.uri
            client_ip: request.remote_ip
      - labels:
          status:
          method:
          client_ip:

Dengan infrastruktur pemantauan ini, kita dapat membuat grafik diagram batang kode status HTTP (2xx, 4xx, 5xx) dan memantau lonjakan latensi secara grafis dari dashboard Grafana.

Ringkasan #

  • Analisis Waktu curl — Gunakan metrik parameter formatting pada curl untuk mengisolasi apakah latensi tinggi berasal dari DNS resolution, TCP handshake, atau dari backend.
  • Rantai Kepercayaan SSL — Verifikasi integritas pengiriman Intermediate dan Root CA menggunakan utilitas openssl s_client -showcerts untuk mencegah isu SSL untrusted di perangkat klien.
  • Penjejakan Rute DNS — Gunakan perintah dig +trace untuk mendeteksi propagasi dan caching record DNS yang salah saat mendebug kegagalan ACME challenge.
  • Koneksi Soket — Diagnosis ketersediaan port dan konflik binding socket di sistem Linux secara instan dengan menggunakan utility ss -tlnp.
  • Packet Sniffing — Manfaatkan tcpdump untuk merekam paket jaringan mentah ke berkas pcap untuk dianalisis lebih detail menggunakan aplikasi eksternal Wireshark.
  • Visualisasi Loki & Grafana — Mengintegrasikan log terstruktur JSON Caddy dengan Loki dan Promtail memberikan visibilitas penuh terhadap performa API jangka panjang.

← Sebelumnya: Caddy Validate   Berikutnya: Best Practices →

About | Author | Content Scope | Editorial Policy | Privacy Policy | Disclaimer | Contact