panduan-php-fpm.md

🛠️ Panduan Lengkap Troubleshooting & Hardening PHP-FPM untuk API

Panduan ini FULL Markdown tanpa putus, ditulis untuk kasus:

• API lancar sebentar lalu timeout
• Error upstream timed out di Nginx
• PHP-FPM terlihat running tapi request macet
• Worker PHP-FPM habis / stuck / memory leak

Dokumen ini aman untuk copy–paste langsung.

---

1️⃣ Gejala Umum Masalah PHP-FPM

Tanda-tanda yang sering muncul:

• API tiba-tiba lambat atau tidak respons
• Error di Nginx:

  upstream timed out while reading response header from upstream
  

• Log PHP-FPM:

  execution timed out (120s)
  child exited on signal 15 (SIGTERM)
  child exited on signal 9 (SIGKILL)
  

• PHP-FPM uptime terlalu lama (mingguan / bulanan)
• Request API berjalan lebih dari 30–60 detik

---

2️⃣ Cek Status PHP-FPM

Melihat status service

systemctl status php-fpm

Perhatikan:

• Active since → jika terlalu lama, rawan memory leak
• Jumlah pool & worker
• Memory usage

---

3️⃣ Restart PHP-FPM (Langkah Darurat)

Jika API sudah error atau timeout:

systemctl restart php-fpm

Jika setelah restart API kembali normal: ➡ Hampir pasti masalah PHP-FPM worker exhaustion

---

4️⃣ Konfigurasi Pool PHP-FPM (WAJIB)

Edit file pool yang digunakan API, contoh:

vi /etc/php-fpm.d/service-kamu.conf

Konfigurasi Rekomendasi untuk API Production

pm = dynamic

pm.max_children = 40
pm.start_servers = 8
pm.min_spare_servers = 8
pm.max_spare_servers = 16

; WAJIB: recycle worker untuk cegah memory leak
pm.max_requests = 200

; Batasi request terlalu lama
request_terminate_timeout = 60s

; Aktifkan slow log
request_slowlog_timeout = 3s
slowlog = /var/log/php-fpm/service-kamu-slow.log

; Socket configuration
listen = /var/run/phpfpm-service-kamu.sock
listen.owner = nginx
listen.group = nginx
listen.mode = 0660

Restart PHP-FPM setelah perubahan:

systemctl restart php-fpm

---

5️⃣ Konfigurasi Timeout Nginx (Disarankan)

Tambahkan di server block API:

fastcgi_connect_timeout 60s;
fastcgi_send_timeout 120s;
fastcgi_read_timeout 120s;

Reload Nginx:

nginx -t
systemctl reload nginx

---

6️⃣ Cara Melihat Log PHP-FPM

Error Log PHP-FPM

tail -f /var/log/php-fpm/error.log

Contoh log penting:

execution timed out (121 sec)
child exited on signal 15 (SIGTERM)
child exited on signal 9 (SIGKILL)

---

Slow Request Log (PALING PENTING)

tail -f /var/log/php-fpm/service-kamu-slow.log

Slow log menampilkan:

• File PHP
• Fungsi
• Baris kode yang menyebabkan request lebih dari 3 detik

---

7️⃣ Cara Membaca Log & Tindakan

execution timed out

execution timed out (121 sec)

Makna:

• Request terlalu berat
• PHP worker tertahan lama

Tindakan:

• Optimasi query database
• Tambahkan pagination / limit
• Implement cache

---

child exited on signal 15 (SIGTERM)

child exited on signal 15

Makna:

• PHP-FPM mematikan worker karena timeout
• Normal jika request_terminate_timeout aktif

Tindakan:

• Pastikan request API < 60 detik
• Optimasi flow aplikasi

---

child exited on signal 9 (SIGKILL)

child exited on signal 9

Makna:

• OOM Killer atau resource limit
• RAM server hampir habis

Tindakan:

• Kurangi pm.max_children
• Cek memory (free -h, htop)

---

8️⃣ Perbaikan di Level Aplikasi (WAJIB)

Checklist optimasi:

• Tambahkan index database
• Hindari N+1 query
• Gunakan limit / paginate
• Cache data statis:
  • merchant
  • outlet
  • product
• Set timeout HTTP client (Guzzle / Curl):

timeout => 5,
connect_timeout => 3,

---

9️⃣ Maintenance Preventif (SANGAT DISARANKAN)

Auto restart PHP-FPM mingguan

Edit cron:

crontab -e

Tambahkan:

0 4 * * 0 systemctl restart php-fpm

Tujuan:

• Membersihkan memory leak
• Menjaga worker tetap fresh
• Mencegah downtime mendadak

---

🔚 Kesimpulan Akhir

• PHP-FPM harus dibatasi, direcycle, dan dimonitor
• API tidak boleh memiliki request lebih dari 60 detik
• Slow log adalah kunci utama debugging
• Restart berkala adalah best practice production

Dengan panduan ini, API akan:

• Lebih stabil
• Lebih tahan traffic
• Tidak mudah timeout
• Lebih mudah di-debug