Log server e errori 502/503: leggere i log Nginx prima di aprire un ticket

Un 502 Bad Gateway o un 503 Service Unavailable sono i due errori che generano più ticket aperti in preallarme. Il cliente vede il sito giù, scrive 'non funziona nulla', e da quel momento parte una conta alla rovescia in cui ogni minuto è un minuto di traffico perso. Ma nella maggior parte dei casi i log del server dicono già cosa è successo — e lo dicono in secondi, non in ore.

Il primo passo è capire cosa significano davvero questi due codici. Un 502 significa che Nginx ha cercato di parlare con il backend (PHP-FPM) e non ha ricevuto una risposta valida: il processo PHP è morto, ha fatto timeout, o ha restituito un header malformato. Un 503 significa che il backend non era raggiungibile del tutto: PHP-FPM era fermo, il pool era esaurito, o il socket era chiuso. Diversi sintomi, diagnosi diverse.

Il primo posto da guardare: error.log di Nginx

Su quasi ogni hosting che usa Nginx (e su Cloudflare con origine Nginx), il log degli errori è in /var/log/nginx/error.log. Le righe che interessano sono quelle con 'upstream', 'connect', 'recv' o 'timeout' nell'arco temporale del problema. Un esempio tipico di 502 da pool esaurito:

# Ultimi 20 errori di Nginx (filtra per upstream/connect/timeout)
sudo tail -100 /var/log/nginx/error.log | grep -iE 'upstream|connect|recv|timeout'

# Esempio di output per un 502 da pool PHP-FPM esaurito:
# 2026-11-05 12:42:11 [error] 12345#0: *6789 connect() to unix:/run/php/php8.1-fpm.sock
#   failed (11: Resource temporarily unavailable) while connecting to upstream,
#   client: 192.168.1.50, server: miosito.com, request: "GET / HTTP/1.1"

# Cerca gli errori nell'arco di un'ora precisa
sudo grep '2026-11-05 12:' /var/log/nginx/error.log | tail -30

Il secondo posto: il log di PHP-FPM

Se Nginx dice 'upstream timed out' o 'connect() failed', il passo successivo è il log di PHP-FPM. È lì che si vede il vero motivo per cui un worker non risponde: un fatal error, un out of memory, o un timeout del max_execution_time. Su Debian/Ubuntu il log è in /var/log/php8.1-fpm.log (o versione equivalente); su altre distribuzioni spesso in /var/log/php-fpm.log.

# Log di PHP-FPM (worker terminati, pool warnings)
sudo tail -50 /var/log/php8.1-fpm.log

# Esempi di righe critiche:
# WARNING: [pool www] child 5678 exited on signal 9 (SIGKILL)
#   -> PHP è stato ucciso dall'OOM killer (memoria esaurita)
# WARNING: [pool www] server reached pm.max_children (50)
#   -> pool esaurito, nuove richieste in coda
# WARNING: [pool www] seems busy (you may need to increase pm.max_children)

# Verifica se l'OOM killer ha colpito PHP
dmesg | grep -i 'out of memory' | tail -10

Il terzo posto: il log degli errori PHP dell'applicazione

L'ultimo livello è il log degli errori PHP dell'applicazione stessa, dove compaiono i fatal error, i warning di deprecato e gli stack trace. Su hosting gestiti con Nginx, spesso è in /var/www/miosito/logs/ o definito da error_log() nel wp-config.php:

# Definisci un log degli errori dedicato nel wp-config.php
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

# Il file di debug si crea in wp-content/debug.log
tail -100 wp-content/debug.log | grep -iE 'fatal|error|warning' | tail -20

Il processo in 90 secondi quando il sito va giù

Quando arriva un alert di 502/503, la sequenza che seguiamo è quasi sempre la stessa. Primo: tail dell'error.log di Nginx per vedere se è upstream o connection. Secondo: tail del log PHP-FPM per capire se è memoria, pool o fatal. Terzo: tail del debug.log di WordPress per vedere il fatal error specifico del plugin. In tre comandi hai la diagnosi. Il ticket all'hosting diventa allora un ticket informativo ('PHP-FPM pool esaurito, aumentato pm.max_children, in monitoraggio') invece di un 'aiuto, il sito non funziona' da cui bisogna partire da zero.

Il punto è che i log ci sono già. Non servono strumenti di monitoring complessi per fare la prima diagnosi — servono tre comandi di tail e la capacità di leggere cosa dicono. Il monitoraggio continuo poi conferma e previene, ma quando il sito è giù in quel momento, i log sono la fonte di verità più rapida che esista.

Un piano di gestione che include il monitoraggio uptime con alert in tempo reale significa che il primo a sapere che il sito è giù sei tu, non il cliente che scrive su WhatsApp. E sapere già cosa dicono i log prima di intervenire riduce i tempi di ripristino da ore a minuti.