Funzione PHP syslog(): Tutto Quello che Devi Sapere

La funzione syslog() invia un messaggio al logger di sistema — la stessa struttura di logging utilizzata dal sistema operativo e da altri servizi (la destinazione è /var/log/syslog o /var/log/messages sulla maggior parte dei sistemi Linux, Console / unified log su macOS e il Registro eventi su Windows). A differenza della scrittura su file con error_log() o file_put_contents(), syslog() consegna il messaggio a un daemon che può instradarlo, filtrarlo, ruotarlo e inviarlo per te. Questa pagina tratta la sintassi, le costanti di priorità e facility, un esempio completo funzionante e le insidie da conoscere.

Sintassi

syslog(int $priority, string $message): bool

La funzione accetta due parametri e restituisce true in caso di successo o false in caso di errore:

• $priority — il livello di gravità del messaggio, espresso come una delle costanti di priorità LOG_* indicate di seguito.
• $message — il testo da registrare. La sequenza di due caratteri %m viene sostituita dalla stringa del messaggio di errore dell'errno corrente (l'ultimo errore del sistema), il che è talvolta utile ma significa che i segni di percentuale letterali devono essere preceduti da escape come %%.

Livelli di priorità

La priorità indica al logger quanto è grave il messaggio. Dal più al meno urgente:

La configurazione del logger stesso decide quali priorità vengono effettivamente scritte, quindi una riga LOG_DEBUG potrebbe essere scartata mentre una riga LOG_ERR viene mantenuta — il tuo codice chiama syslog() nello stesso modo indipendentemente da ciò.

Un esempio completo

Non è strettamente necessario usare openlog() — chiamare syslog() da solo funziona — ma aprire prima la connessione ti permette di impostare un prefisso identificativo e una facility, così i tuoi messaggi sono facili da trovare e instradare.

<?php

// Open a connection: tag every line with "myapp", include the PID,
// and also echo to stderr. LOG_USER is the generic application facility.
openlog("myapp", LOG_PID | LOG_PERROR, LOG_USER);

syslog(LOG_INFO,    "User #42 logged in");
syslog(LOG_WARNING, "Disk usage above 80%%");   // %% = a literal percent sign
syslog(LOG_ERR,     "Payment gateway timed out");

closelog();

Una riga risultante nel log di sistema appare all'incirca così:

Jun 21 14:03:11 host myapp[3187]: Payment gateway timed out

openlog() accetta tre argomenti: un identificatore da anteporre a ogni messaggio, una bitmask di opzioni (LOG_PID aggiunge l'ID del processo, LOG_PERROR stampa anche su stderr, LOG_CONS ricade sulla console se il logger non è raggiungibile) e una facility che categorizza la sorgente. Le facility più comuni sono LOG_USER (quella predefinita per le applicazioni generiche), LOG_LOCAL0–LOG_LOCAL7 (riservate per il proprio instradamento personalizzato), LOG_DAEMON e LOG_MAIL. closelog() chiude la connessione — facoltativo, ma è buona prassi.

Quando usarla?

• Servizi a esecuzione prolungata e worker CLI dove non c'è un browser per mostrare gli errori e si vuole che i log finiscano nello stesso posto degli altri log di sistema.
• Logging centralizzato — un daemon syslog può inoltrare i messaggi a un collettore remoto (rsyslog, journald, uno stack ELK/Graylog), ottenendo l'aggregazione gratuitamente.
• Instradamento basato sulla gravità — scegli la facility/priorità e lascia che il daemon decida cosa archiviare, segnalare o scartare.

Per il normale logging degli errori per applicazione che scrive semplicemente su file, error_log() è generalmente più semplice. Usa syslog() quando vuoi che il messaggio entri nella pipeline di logging a livello di sistema operativo.

Insidie comuni

• Esegui l'escape dei segni di percentuale letterali. syslog() interpreta %m; un % non preceduto da escape nel messaggio può produrre output inaspettato. Scrivi %% per un segno di percentuale letterale.
• I messaggi possono essere eliminati silenziosamente. Se la configurazione del logger filtra la tua priorità/facility, non compare nulla — è una questione di configurazione, non un errore PHP. Controlla /etc/rsyslog.conf o journalctl se una riga scompare.
• Non è la stessa cosa dell'impostazione ini error_log di PHP. Impostare error_log = syslog in php.ini instrada gli errori interni di PHP verso syslog; chiamare syslog() manualmente registra i tuoi propri messaggi ed è indipendente da quella impostazione.
• Una riga di testo per chiamata. Passa una singola riga; il daemon aggiunge il timestamp, l'host e il tag. Non incorporare \n nel messaggio.

Funzioni correlate

• openlog() — apre la connessione e imposta l'identificatore e la facility.
• closelog() — chiude la connessione syslog.
• error_log() — invia un messaggio a un file, email o al log configurato.

Conclusione

syslog() è il punto di ingresso PHP nella pipeline di logging del sistema operativo. Scegli una priorità significativa, apri facoltativamente una connessione con openlog() per aggiungere un identificatore e una facility, esegui l'escape dei segni di percentuale letterali e ricorda che è il daemon — non PHP — a decidere cosa viene effettivamente archiviato. Per il semplice logging su file, preferisci error_log(); per log a livello di sistema operativo, instradabili e centralizzabili, syslog() è lo strumento giusto.

Esercitazione