Membaca Log Nginx dan PHP-FPM untuk Melacak Sumber Error 502

Pesan error 502 Bad Gateway di browser pada dasarnya hanya memberi tahu satu hal sederhana: Nginx bertindak sebagai reverse proxy atau web server di depan, mencoba meneruskan permintaan pengunjung ke backend PHP-FPM, tetapi backend tersebut tidak memberikan respons yang valid. Masalahnya, browser tidak pernah memberi tahu apakah PHP-FPM mati mendadak, kehabisan worker, atau script PHP yang dijalankan mengalami hanging. Di meja bantuan hosting, kesalahan paling umum saat menangani kasus ini adalah langsung mengubah parameter timeout di konfigurasi web server secara acak tanpa memeriksa catatan log terlebih dahulu. Menemukan biang keladi dari error 502 sebenarnya tidak membutuhkan tebak-tebakan. Log Nginx mencatat sudut pandang dari sisi penerima gerbang, sementara log PHP-FPM dan slowlog mencatat apa yang sebenarnya terjadi di dapur eksekusi script. Berikut adalah checklist terurut yang biasa kita gunakan untuk melacak sumber masalah secara sistematis.

Checklist 1: Identifikasi pola kalimat di error log Nginx

Langkah pertama yang wajib dilakukan adalah membuka file error log Nginx (biasanya berada di /var/log/nginx/error.log atau direktori log virtual host masing-masing domain). Nginx sangat spesifik dalam menuliskan alasan kegagalan koneksi FastCGI ke PHP-FPM. Pesan teks pada log ini langsung mengarahkan kita ke akar persoalan tanpa perlu berspekulasi. Jika log mencatat connect() failed (111: Connection refused) while connecting to upstream, artinya Nginx mencoba mengirim request ke port TCP atau socket UNIX milik PHP-FPM, tetapi tidak ada proses yang mendengarkan di sana. Ini indikasi jelas bahwa service PHP-FPM sedang berhenti, mengalami crash, atau path socket di konfigurasi Nginx salah ketik. Jika log menunjukkan connect() to unix:/run/php/php-fpm.sock failed (2: No such file or directory), Nginx mencari file socket UNIX yang tidak eksis di filesystem. Kondisi ini sering terjadi setelah upgrade versi PHP ketika service PHP versi baru aktif pada path socket yang berbeda dengan yang didefinisikan di virtual host Nginx. Jika pesan yang muncul adalah recv() failed (104: Connection reset by peer) while reading response header from upstream, berarti PHP-FPM sempat menerima koneksi, tetapi proses worker yang mengeksekusi script mati secara mendadak sebelum sempat mengirimkan header HTTP kembali ke Nginx. Kematian mendadak ini biasanya dipicu oleh worker yang terkena terminasi sinyal SIGSEGV akibat bug pada ekstensi PHP tertentu, atau dibunuh oleh Out of Memory (OOM) Killer dari kernel sistem operasi. Jika log menampilkan 110: Connection timed out, artinya worker PHP-FPM masih hidup dan menerima request, tetapi tidak kunjung menyelesaikan komputasi hingga batas fastcgi_read_timeout Nginx terlampaui. Ini gejala klasik script macet karena database query yang lambat atau panggilan API eksternal yang tidak memiliki timeout.

Checklist 2: Periksa status service dan master error log PHP-FPM

Setelah mendapatkan petunjuk dari Nginx, checklist berikutnya adalah memeriksa log utama milik PHP-FPM. Di Ubuntu atau Debian, log ini umumnya berada di /var/log/phpX.Y-fpm.log, sedangkan pada keluarga RHEL atau CentOS berada di /var/log/php-fpm/error.log. Cari entri log dengan tanda level peringatan (WARNING) atau bahaya (ALERT) pada timestamp yang sama saat error 502 muncul. Salah satu pesan yang paling sering ditemukan di lingkungan produksi dengan lalu lintas tinggi adalah server reached pm.max_children setting, consider raising it. Pesan ini menandakan bahwa seluruh worker pool PHP yang dialokasikan sudah terpakai penuh untuk melayani request sebelumnya, sehingga request baru harus mengantre di backlog socket atau langsung ditolak bila antrean penuh. Cari juga apakah ada pesan seperti WARNING: [pool www] child <PID> exited on signal 9 (SIGKILL) atau signal 11 (SIGSEGV). Jika Anda melihat sinyal SIGKILL, ada kemungkinan besar proses worker tersebut diterminasi paksa oleh kernel karena server kehabisan memori fisik. Kita bisa mengonfirmasi apakah sistem mengalami tekanan RAM dengan memeriksa log kernel dmesg, serupa dengan langkah diagnosa yang dibahas pada artikel How to Spot Memory Pressure on a VPS Before the OOM Killer Hits.

Checklist 3: Aktifkan dan bedah Slowlog PHP-FPM

Bila log Nginx menunjukkan timeout atau worker penuh akibat antrean panjang, Anda tidak bisa sekadar menyimpulkan bahwa server kekurangan spesifikasi. Sering kali penyebabnya adalah satu atau dua script tertentu yang memakan waktu eksekusi puluhan detik, menyandera worker PHP, dan memicu efek domino hingga worker lain habis. Di sinilah slowlog PHP-FPM menjadi alat pelacak yang sangat berharga. Slowlog berfungsi merekam jejak eksekusi (stack trace) dari script yang berjalan melebihi ambang batas waktu tertentu. Fitur ini secara default sering kali belum diaktifkan di konfigurasi bawaan pool PHP-FPM. Anda dapat mengaktifkannya pada file konfigurasi pool (misalnya www.conf) dengan menentukan parameter slowlog dan request_slowlog_timeout.

INI

; Contoh konfigurasi pada file pool PHP-FPM (misal: /etc/php/8.2/fpm/pool.d/www.conf)
[www]
request_slowlog_timeout = 5s
slowlog = /var/log/php-fpm/www-slow.log
request_terminate_timeout = 60s

Dengan konfigurasi di atas, setiap kali ada request PHP yang membutuhkan waktu eksekusi lebih dari 5 detik, PHP-FPM akan mencatat file PHP mana yang sedang berjalan, nomor baris kode yang sedang diproses, dan fungsi apa yang sedang dieksekusi ke dalam file www-slow.log. Ini memungkinkan Anda atau tim developer langsung mengetahui apakah script macet di pemanggilan fungsi database seperti mysqli_query(), cURL eksternal, atau proses kalkulasi data yang tidak efisien. Parameter request_terminate_timeout juga berfungsi sebagai batas pengaman sisi PHP. Jika script PHP macet melebihi nilai ini (misalnya 60 detik), worker PHP-FPM akan menghentikan eksekusi script tersebut secara paksa agar worker bisa segera kembali ke pool dan melayani pengunjung berikutnya, alih-alih mengunci resource selamanya.

Checklist 4: Evaluasi sinkronisasi timeout antara Nginx dan PHP-FPM

Setelah script penyebab latensi diketahui, periksa kembali keselarasan konfigurasi timeout antara Nginx dan PHP. Ketidaksinkronan nilai timeout sering menjadi sumber kebingungan teknis. Secara umum, Nginx memiliki directive fastcgi_read_timeout yang mengatur berapa lama Nginx bersedia menunggu PHP-FPM mengirimkan data balasan sebelum Nginx memutus koneksi dan menyajikan error 502 atau 504 Gateway Timeout. Di sisi PHP, batas eksekusi diatur oleh max_execution_time di php.ini serta request_terminate_timeout di konfigurasi pool PHP-FPM. Jika fastcgi_read_timeout di Nginx disetel ke 30 detik sementara max_execution_time di PHP adalah 60 detik, Nginx akan memutus koneksi di detik ke-30 dan memunculkan error gateway ke pengunjung, meskipun script PHP di backend sebenarnya masih berjalan di latar belakang hingga selesai atau mencapai batas 60 detik. Pastikan batas waktu diatur secara berjenjang dan logis: perbaiki bottleneck pada script terlebih dahulu daripada menaikkan timeout Nginx ke angka yang terlampau tinggi, karena menaikkan timeout hanya akan menumpuk request macet di antrean worker.

Checklist 5: Pastikan kepemilikan dan permission file socket tepat

Jika error log Nginx mencatat pesan (13: Permission denied) while connecting to upstream, masalahnya bukan pada kinerja script, melainkan izin akses pada file socket UNIX FastCGI. Masalah permission ini kerap muncul saat salah satu service berjalan di bawah user yang berbeda setelah perubahan konfigurasi atau deploy aplikasi manual. Nginx biasanya berjalan dengan user nginx atau www-data tergantung sistem operasi yang digunakan. Begitu pula dengan PHP-FPM yang memiliki konfigurasi listen.owner, listen.group, dan listen.mode pada file pool miliknya. Pastikan user yang menjalankan Nginx memiliki izin baca dan tulis ke file socket tersebut. Jika Nginx berjalan sebagai user www-data, pastikan socket PHP-FPM juga dimiliki oleh atau dapat diakses oleh grup www-data dengan mode permission yang sesuai (misalnya 0660). Menganalisis error 502 selalu bermula dari korelasi log: baca alasan penolakan pada log error Nginx untuk mengetahui titik putusnya, cocokkan dengan log utama PHP-FPM untuk memeriksa kondisi worker dan sistem, lalu bedah slowlog untuk menemukan baris kode yang menghabiskan waktu. Dengan alur ini, Anda bisa langsung menunjuk sumber masalah yang sebenarnya tanpa perlu meraba-raba konfigurasi server secara membabi buta.