Error Log #

Jika access log bertindak sebagai buku harian lalu lintas data yang mencatat setiap aktivitas normal, maka Error Log adalah catatan diagnosis medis server kita. Berbeda dari access log yang mencatat semua interaksi tanpa terkecuali, error log dirancang secara eksklusif untuk mendokumentasikan kegagalan, peringatan keamanan, ketidaksesuaian konfigurasi, dan kondisi abnormal lainnya yang ditemui Nginx saat beroperasi.

Mampu membaca, menginterpretasikan, dan menelusuri pesan dalam error log adalah keahlian mutlak yang harus dikuasai oleh administrator sistem. Melalui pemahaman yang mendalam terhadap error log, kita dapat mendeteksi kegagalan backend aplikasi sebelum pengguna merasakannya, mengidentifikasi serangan pemindaian eksploitasi, hingga memperbaiki masalah performa jaringan internal. Di artikel ini, kita akan membahas 8 tingkatan severity level error log, membedah anatomi pesan kesalahan secara baris demi baris, mempelajari cara mengatasi masalah umum produksi, serta menggunakan teknik debug per-IP secara aman di lingkungan produksi.

Perbedaan Fundamental: Access Log vs Error Log #

Sebelum masuk lebih dalam, mari kita luruskan perbedaan mendasar antara kedua berkas log utama Nginx ini agar kita tidak salah mencari informasi saat pemecahan masalah:

Memahami 8 Tingkatan Severity Level #

Nginx mengklasifikasikan setiap kejadian dalam error log ke dalam salah satu dari delapan tingkat keparahan (severity levels). Tingkatan ini diturunkan dari standar logging Syslog.

Berikut adalah urutan tingkat keparahan dari yang paling kritis hingga yang paling rinci (verbose):

flowchart TD
    emerg("1. emerg - Kritis - Sistem Tidak Stabil")
    alert("2. alert - Perlu Tindakan Segera")
    crit("3. crit - Kondisi Kritis")
    error("4. error - Kesalahan Request/Sistem")
    warn("5. warn - Peringatan/Abaikan Sementara")
    notice("6. notice - Informasi Signifikan")
    info("7. info - Informasi Umum")
    debug("8. debug - Sangat Verbose - Pengembangan")

    emerg --> alert
    alert --> crit
    crit --> error
    error --> warn
    warn --> notice
    notice --> info
    info --> debug

    classDef default fill:#f9f9f9,stroke:#d1d5db,stroke-width:1px,color:#111827;
    classDef dangerStyle fill:#fee2e2,stroke:#ef4444,stroke-width:2px,color:#991b1b;
    classDef warnStyle fill:#fef3c7,stroke:#f59e0b,stroke-width:2px,color:#92400e;
    classDef infoStyle fill:#eff6ff,stroke:#3b82f6,stroke-width:2px,color:#1e3a8a;
    
    class emerg,alert,crit dangerStyle;
    class error,warn warnStyle;
    class notice,info,debug infoStyle;

Mari kita bedah karakteristik masing-masing level:

1. emerg (Emergency): Kondisi darurat di mana server Nginx tidak dapat berjalan atau berada dalam kondisi sangat tidak stabil (misalnya, kehabisan alokasi memori sistem secara total atau kegagalan kritis pada pustaka OS utama).
2. alert: Masalah serius yang memerlukan intervensi manusia segera (misalnya, kegagalan membuka file socket penting, kegagalan database internal yang mengunci proses master, atau batas file descriptor OS yang tercapai).
3. crit (Critical): Kejadian kritis yang menyebabkan sebagian fungsi Nginx terhambat (misalnya, kegagalan alokasi memori untuk worker process baru atau kegagalan membuka file konfigurasi saat melakukan reload).
4. error: Masalah operasional standar yang mengakibatkan sebuah permintaan klien gagal diproses (misalnya, kegagalan terhubung ke backend upstream, file lokal tidak ditemukan, atau masalah handshake SSL dengan klien).
5. warn (Warning): Peringatan tentang perilaku mencurigakan atau penggunaan konfigurasi usang (deprecated), namun tidak sampai menghentikan proses pengiriman respons (misalnya, ukuran buffer log terlalu kecil atau konfigurasi host ganda yang tumpang tindih).
6. notice: Kejadian operasional yang berjalan normal namun memiliki signifikansi penting bagi administrator (misalnya, proses master Nginx mendeteksi perubahan konfigurasi setelah reload, atau worker process baru berhasil dijalankan).
7. info: Pesan informasi umum yang berguna untuk memantau aktivitas sistem (misalnya, informasi negosiasi ulang koneksi SSL).
8. debug: Informasi pelacakan internal tingkat rendah yang sangat detail mengenai setiap operasi soket, pembacaan buffer, dan alur kode C. Level ini sangat verbose.

Pengaruh Threshold Level Logging #

Ketika kita menetapkan tingkat keparahan tertentu pada konfigurasi, Nginx akan mencatat kejadian pada level tersebut beserta seluruh tingkatan di atasnya.

Sebagai contoh, jika kita menyetel level ke warn, maka Nginx akan mencatat kejadian berkategori warn, error, crit, alert, dan emerg. Pesan dengan kategori notice, info, dan debug akan diabaikan.

# Konfigurasi di tingkat global (biasanya di baris teratas nginx.conf)
# Sangat disarankan menyetel level ke 'warn' untuk lingkungan produksi
error_log /var/log/nginx/error.log warn;

[!WARNING] Jangan pernah menyetel level error log ke debug di lingkungan produksi. Level debug akan menulis jutaan baris informasi setiap menitnya, yang akan membebaskan kinerja CPU hanya untuk menulis log, menghabiskan ruang disk dalam hitungan jam, dan memperlambat waktu respons aplikasi web kita secara drastis.

Anatomi Pesan Error Nginx #

Pesan error Nginx dirancang dengan format terstruktur yang padat informasi untuk membantu melacak akar permasalahan (root cause analysis). Mari kita bedah contoh baris pesan error produksi berikut:

2026/06/16 13:20:45 [error] 4821#4821: *30412 connect() failed (111: Connection refused) while connecting to upstream, client: 203.0.113.102, server: api.unisbadri.com, request: "POST /v1/users HTTP/2.0", upstream: "http://127.0.0.1:8080/v1/users", host: "api.unisbadri.com"

Jika kita bedah baris log tersebut, kita mendapatkan elemen-elemen informasi berikut:

1. 2026/06/16 13:20:45: Stempel waktu kejadian dalam format lokal server (Tahun/Bulan/Tanggal Jam:Menit:Detik).
2. [error]: Tingkat keparahan kejadian (severity level).
3. 4821#4821: PID (Process Identifier) dari worker process Nginx yang memproses koneksi tersebut, diikuti oleh ID thread internal.
4. *30412: Nomor ID unik request internal Nginx (connection ID). Ini sangat berguna karena jika request tersebut memicu beberapa pesan error, kita bisa melacaknya dengan mencari ID *30412 yang sama di seluruh file log.
5. connect() failed (111: Connection refused) while connecting to upstream: Deskripsi detail kesalahan. Di sini Nginx menginformasikan bahwa panggilan sistem connect() ke backend gagal dengan kode kesalahan OS 111 (Koneksi ditolak) saat mencoba meneruskan request ke upstream.
6. client: 203.0.113.102: Alamat IP klien asli yang memicu request ini.
7. server: api.unisbadri.com: Nama domain server block (virtual host) tempat kesalahan terjadi.
8. request: "POST /v1/users HTTP/2.0": Baris permintaan HTTP asli, menunjukkan metode, path, dan protokol yang digunakan klien.
9. upstream: "http://127.0.0.1:8080/v1/users": Alamat tujuan upstream/backend yang gagal dihubungi (dalam hal ini, aplikasi backend lokal yang berjalan di port 8080).
10. host: "api.unisbadri.com": Nilai header Host HTTP yang dikirimkan oleh klien.

Masalah Umum dan Cara Penyelesaiannya #

Berikut adalah kompilasi pesan error yang paling sering muncul di server Nginx produksi, makna di balik pesan tersebut, penyebab umum, dan langkah-langkah solutif untuk memperbaikinya:

1. connect() failed (111: Connection refused) while connecting to upstream #

• Arti: Nginx berhasil menerima request dari klien dan mencoba meneruskannya ke server backend (seperti PHP-FPM, Node.js, Go, Python), namun server backend menolak koneksi tersebut.
• Penyebab Umum:
  • Aplikasi backend kita belum berjalan (crashed atau belum dinyalakan).
  • Backend mendengarkan (listening) pada port atau path socket Unix yang salah di konfigurasi Nginx.
  • Firewall lokal (seperti UFW atau iptables) memblokir komunikasi port internal tersebut.
• Solusi:
  • Cek status backend kita (misal: systemctl status php8.2-fpm atau pm2 status).
  • Pastikan port pada direktif proxy_pass http://127.0.0.1:PORT; cocok dengan konfigurasi aplikasi backend kita.

2. no live upstreams while connecting to upstream #

• Arti: Nginx menandai semua server backend yang dideklarasikan di dalam blok upstream sebagai tidak aktif (down) karena kegagalan interaksi sebelumnya (passive healthcheck).
• Penyebab Umum:
  • Semua instance backend mengalami crash secara bersamaan.
  • Parameter max_fails dan fail_timeout pada konfigurasi upstream disetel terlalu ketat, sehingga fluktuasi kecil pada backend langsung membuat Nginx memblokir pengiriman trafik ke sana.
• Solusi:
  • Perbaiki backend yang mati.
  • Longgarkan parameter kesehatan di blok upstream kita:

    upstream backend_servers {
        server 10.0.0.10:3000 max_fails=3 fail_timeout=30s;
        server 10.0.0.11:3000 max_fails=3 fail_timeout=30s;
    }
    

3. upstream timed out (110: Connection timed out) while reading response header from upstream #

• Arti: Nginx berhasil terhubung ke backend, tetapi backend membutuhkan waktu terlalu lama untuk memproses data dan tidak kunjung mengirimkan respons balik hingga batas waktu terlampaui.
• Penyebab Umum:
  • Kueri database pada aplikasi backend kita sangat lambat.
  • Backend mengalami kebocoran memori (memory leak) atau kelebihan beban CPU.
  • Nilai timeout Nginx (proxy_read_timeout) disetel terlalu rendah untuk transaksi yang legitimate (seperti pemrosesan laporan bulanan).
• Solusi:
  • Optimalkan kode aplikasi backend kita.
  • Naikkan batas waktu respons di blok konfigurasi server Nginx kita:

    location /api/laporan {
        proxy_read_timeout 300s;
        proxy_pass http://backend_servers;
    }
    

4. (13: Permission denied) while reading response header from upstream #

• Arti: Nginx diblokir oleh sistem keamanan sistem operasi saat mencoba membaca atau menulis data.
• Penyebab Umum:
  • Pada sistem RedHat/CentOS/Rocky Linux, fitur keamanan SELinux secara bawaan memblokir Nginx agar tidak dapat membuat koneksi jaringan keluar (outbound network connections) ke port backend.
  • Berkas socket Unix (misalnya /var/run/php-fpm.sock) memiliki hak akses berkas (file permission) yang tidak dapat dibaca oleh pengguna sistem Nginx (www-data atau nginx).
• Solusi:
  • Jika disebabkan oleh SELinux, jalankan perintah:

    sudo setsebool -P httpd_can_network_connect 1
    

  • Jika disebabkan oleh izin file socket, sesuaikan pemilik socket di konfigurasi PHP-FPM/backend agar Nginx memiliki hak akses read/write.

5. open() "/var/www/html/missing.html" failed (2: No such file or directory) #

• Arti: Klien meminta berkas statik yang tidak ada di direktori fisik server kita.
• Penyebab Umum:
  • Klien salah mengetik URL (menyebabkan HTTP 404).
  • Direktif root atau alias di konfigurasi Nginx mengarah ke folder yang salah di server.
• Solusi:
  • Pastikan path di direktif root mengarah ke folder yang benar.
  • Jika aplikasi kita adalah Single Page Application (SPA) seperti React/Vue/Angular, pastikan kita menggunakan direktif try_files agar request dialihkan ke index.html dan ditangani oleh routing frontend:

    location / {
        root /var/www/my-spa;
        try_files $uri $uri/ /index.html;
    }
    

Teknik Debug Connection: Debug Logging Aman di Produksi #

Ketika ada laporan kesalahan dari pengguna tertentu di lingkungan produksi, kita sering kali tergoda untuk menaikkan level log global menjadi debug untuk memantau detail request secara mendalam. Namun, seperti yang telah dibahas sebelumnya, tindakan ini sangat berbahaya bagi performa server dan ruang penyimpanan disk kita.

Untuk memecahkan masalah ini, Nginx menyediakan solusi cerdas bernama direktif debug_connection. Direktif ini diletakkan di dalam blok konteks events dan memungkinkan kita mengaktifkan debug logging hanya untuk alamat IP atau segmen CIDR tertentu.

Berikut adalah contoh konfigurasinya:

# Letakkan konfigurasi ini di file /etc/nginx/nginx.conf
error_log /var/log/nginx/error.log warn; # Level log global tetap aman di level 'warn'

events {
    worker_connections 1024;

    # Aktifkan level debug HANYA untuk IP di bawah ini
    # (Misal: IP milik tim developer internal kita atau IP spesifik pengguna yang mengalami error)
    debug_connection 203.0.113.205;
    
    # Kita juga bisa menentukan seluruh blok subnet CIDR
    debug_connection 10.10.0.0/24;
}

Cara Kerja debug_connection #

Saat request masuk dari IP 203.0.113.205, Nginx akan mengalihkan pemrosesan logging request tersebut ke level debug, mencatat seluruh histori internal transaksi secara rinci ke berkas /var/log/nginx/error.log. Sementara itu, untuk jutaan trafik dari pengguna lain yang berasal dari IP berbeda, Nginx tetap menerapkan aturan logging level warn yang hemat memori dan penyimpanan.

Ini adalah teknik tingkat lanjut yang sangat berharga untuk mendiagnosis masalah SSL handshake yang aneh atau anomali parameter request di tingkat produksi dengan aman.

Mengelola Error Log per Virtual Host #

Sama seperti access log, kita harus selalu mengisolasi file error log untuk setiap domain agar proses triage dan identifikasi masalah tidak terhambat oleh campur aduk data domain lain.

# Virtual Host: portal.unisbadri.com
server {
    listen 80;
    server_name portal.unisbadri.com;

    # Isolasi error log dengan level spesifik untuk portal
    access_log /var/log/nginx/portal-access.log combined;
    error_log /var/log/nginx/portal-error.log warn;

    location / {
        root /var/www/portal;
        index index.html;
    }
}

Dengan mengisolasi error log per server block, jika tim pemantau kita (monitoring team) mendapatkan peringatan bahwa domain portal mengalami masalah, mereka cukup fokus menganalisis berkas /var/log/nginx/portal-error.log.

Analisis Cepat Error Log via CLI #

Berikut adalah beberapa perintah CLI praktis untuk mempercepat penelusuran masalah di berkas error log Nginx kita:

1. Memantau Error Baru Secara Real-time (Sangat berguna saat deploy aplikasi baru) #

sudo tail -f /var/log/nginx/error.log

2. Mencari Jenis Error Tertentu (Misal: masalah koneksi ke backend upstream) #

sudo grep -i "connect() failed" /var/log/nginx/error.log

3. Menghitung Jumlah Kejadian Berdasarkan Level Severity (Melihat tingkat keparahan error) #

sudo grep -oP '\[\K[^\]]+' /var/log/nginx/error.log | sort | uniq -c | sort -rn

• Cara Kerja: Perintah ini menggunakan regular expression untuk mengekstrak string di dalam kurung siku [...] (yang berisi level severity seperti error, warn, crit), lalu menghitung frekuensi kemunculannya.

4. Menemukan IP Klien yang Paling Sering Memicu Error #

sudo grep -oP 'client: \K[^,]+' /var/log/nginx/error.log | sort | uniq -c | sort -rn | head -n 10

Jika kita melihat satu IP memicu ribuan error 404 atau Permission denied dalam waktu singkat, itu adalah indikator kuat bahwa IP tersebut sedang melakukan aktivitas scanning otomatis (vulnerability scanning) di situs kita. Kita dapat segera memblokir IP tersebut menggunakan firewall atau modul IP restriction.

Ringkasan dan Praktik Terbaik #

• Setel Tingkat Keparahan ke warn: Di lingkungan produksi, selalu setel direktif error_log ke tingkat keparahan warn untuk menyeimbangkan kebutuhan informasi pemecahan masalah dengan efisiensi performa server.
• Manfaatkan debug_connection: Gunakan debug connection untuk mengaktifkan logging level debug secara selektif per-IP klien tanpa mempengaruhi performa server secara global.
• Pisahkan Error Log per Virtual Host: Deklarasikan file error log yang berbeda pada setiap server block domain agar pengelolaan administrasi server kita tetap bersih.
• Analisis Log Secara Berkala: Gunakan perintah CLI standar seperti grep, awk, dan uniq untuk memantau tren kesalahan dan mengidentifikasi anomali lalu lintas yang berpotensi menjadi ancaman keamanan.

← Sebelumnya: Access Log   Berikutnya: Format Log Kustom →