Fonction PHP syslog() : Tout ce que vous devez savoir

La fonction syslog() envoie un message au journal système — la même infrastructure de journalisation utilisée par le système d'exploitation et les autres services (la destination est /var/log/syslog ou /var/log/messages sur la plupart des systèmes Linux, la Console / le journal unifié sur macOS, et le Journal d'événements sur Windows). Contrairement à l'écriture dans un fichier avec error_log() ou file_put_contents(), syslog() confie votre message à un démon qui peut l'acheminer, le filtrer, le faire tourner et le transférer à votre place. Cette page couvre la syntaxe, les constantes de priorité et de facility, un exemple complet fonctionnel, ainsi que les pièges à connaître.

Syntaxe

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

La fonction prend deux paramètres et retourne true en cas de succès ou false en cas d'échec :

• $priority — le niveau de sévérité du message, exprimé sous la forme d'une des constantes de priorité LOG_* listées ci-dessous.
• $message — le texte à enregistrer. La séquence de deux caractères %m est remplacée par la chaîne du message d'erreur du errno courant (la dernière erreur système), ce qui est parfois utile mais signifie que les signes de pourcentage littéraux doivent être échappés en %%.

Niveaux de priorité

La priorité indique au journal la gravité du message. Du plus au moins urgent :

La configuration propre au journal détermine quelles priorités sont effectivement écrites, de sorte qu'une ligne LOG_DEBUG peut être ignorée tandis qu'une ligne LOG_ERR est conservée — votre code appelle syslog() de la même manière quelle que soit la situation.

Un exemple complet

Il n'est pas strictement nécessaire d'utiliser openlog() — appeler syslog() seul fonctionne — mais ouvrir la connexion au préalable vous permet de définir un préfixe d'identification et une facility afin que vos messages soient faciles à trouver et à acheminer.

<?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();

Une ligne résultante dans le journal système ressemble à peu près à ceci :

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

openlog() accepte trois arguments : un identifiant préfixé à chaque message, un masque de bits d'options (LOG_PID ajoute l'identifiant de processus, LOG_PERROR imprime également sur stderr, LOG_CONS revient à la console si le journal est inaccessible), et une facility qui catégorise la source. Les facilities courantes sont LOG_USER (la valeur par défaut pour les applications génériques), LOG_LOCAL0–LOG_LOCAL7 (réservées pour votre propre routage personnalisé), LOG_DAEMON et LOG_MAIL. closelog() ferme la connexion — facultatif, mais propre.

Quand l'utiliser ?

• Services de longue durée et workers CLI où il n'y a pas de navigateur pour afficher les erreurs et où vous souhaitez que les journaux se retrouvent au même endroit que le reste des journaux système.
• Journalisation centralisée — un démon syslog peut transmettre les messages à un collecteur distant (rsyslog, journald, une pile ELK/Graylog), vous offrant ainsi une agrégation gratuite.
• Routage basé sur la sévérité — choisissez la facility/priorité et laissez le démon décider ce qu'il faut stocker, signaler ou ignorer.

Pour la journalisation d'erreurs ordinaire par application qui écrit simplement dans un fichier, error_log() est généralement plus simple. Utilisez syslog() lorsque vous souhaitez que le message entre dans le pipeline de journalisation au niveau du système d'exploitation.

Pièges courants

• Échappez les signes de pourcentage littéraux. syslog() interprète %m ; un % non échappé dans votre message peut produire une sortie surprenante. Écrivez %% pour un pourcentage littéral.
• Les messages peuvent être silencieusement ignorés. Si la configuration du journal filtre votre priorité/facility, rien n'apparaît — c'est une configuration, pas une erreur PHP. Vérifiez /etc/rsyslog.conf ou journalctl si une ligne disparaît.
• Ce n'est pas la même chose que le paramètre ini error_log de PHP. Définir error_log = syslog dans php.ini achemine les erreurs internes de PHP vers syslog ; appeler syslog() vous-même enregistre vos propres messages et est indépendant de ce paramètre.
• Une nouvelle ligne par appel. Passez une seule ligne ; le démon ajoute l'horodatage, l'hôte et le tag. N'intégrez pas \n dans le message.

Fonctions associées

• openlog() — ouvrir la connexion et définir l'identifiant et la facility.
• closelog() — fermer la connexion syslog.
• error_log() — envoyer un message vers un fichier, un e-mail ou le journal configuré.

Conclusion

syslog() est le point d'entrée PHP dans le pipeline de journalisation du système d'exploitation. Choisissez une priorité significative, ouvrez optionnellement une connexion avec openlog() pour ajouter un identifiant et une facility, échappez les signes de pourcentage littéraux, et n'oubliez pas que c'est le démon — pas PHP — qui décide de ce qui est finalement stocké. Pour une simple journalisation dans un fichier, préférez error_log() ; pour des journaux au niveau du système d'exploitation, routables et centralisables, syslog() est le bon outil.

Pratique