PHP syslog() Funktion: Alles, was Sie wissen müssen

Die Funktion syslog() sendet eine Nachricht an den System-Logger — dieselbe Protokollierungseinrichtung, die vom Betriebssystem und anderen Diensten verwendet wird (das Ziel ist /var/log/syslog oder /var/log/messages auf den meisten Linux-Systemen, die Konsole/der Unified Log auf macOS und das Ereignisprotokoll unter Windows). Im Gegensatz zum Schreiben in eine Datei mit error_log() oder file_put_contents() übergibt syslog() Ihre Nachricht an einen Daemon, der sie für Sie weiterleiten, filtern, rotieren und weiterleiten kann. Diese Seite behandelt die Syntax, die Prioritäts- und Facility-Konstanten, ein vollständiges Arbeitsbeispiel sowie wichtige Fallstricke.

Syntax

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

Die Funktion nimmt zwei Parameter entgegen und gibt bei Erfolg true oder bei Fehler false zurück:

• $priority — die Schweregrad-Stufe der Nachricht, ausgedrückt als eine der unten aufgeführten LOG_*-Prioritätskonstanten.
• $message — der zu protokollierende Text. Die zweistellige Zeichenfolge %m wird durch die Fehlermeldung des aktuellen errno (dem letzten Systemfehler) ersetzt, was gelegentlich nützlich ist, jedoch müssen literale Prozentzeichen als %% maskiert werden.

Prioritätsstufen

Die Priorität teilt dem Logger mit, wie schwerwiegend die Nachricht ist. Von der dringendsten zur am wenigsten dringenden:

Die eigene Konfiguration des Loggers entscheidet, welche Prioritäten tatsächlich geschrieben werden. Eine LOG_DEBUG-Zeile kann verworfen werden, während eine LOG_ERR-Zeile gespeichert wird — Ihr Code ruft syslog() in jedem Fall gleich auf.

Ein vollständiges Beispiel

Sie benötigen openlog() nicht unbedingt — das direkte Aufrufen von syslog() funktioniert — aber das vorherige Öffnen der Verbindung ermöglicht es Ihnen, ein identifizierendes Präfix und eine Facility festzulegen, sodass Ihre Nachrichten leicht zu finden und weiterzuleiten sind.

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

Eine resultierende Zeile im System-Log sieht in etwa so aus:

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

openlog() akzeptiert drei Argumente: einen Bezeichner, der jeder Nachricht vorangestellt wird, eine Bitmaske von Optionen (LOG_PID fügt die Prozess-ID hinzu, LOG_PERROR gibt die Ausgabe auch auf stderr aus, LOG_CONS fällt auf die Konsole zurück, wenn der Logger nicht erreichbar ist) und eine Facility, die die Quelle kategorisiert. Häufige Facilities sind LOG_USER (Standard für generische Apps), LOG_LOCAL0–LOG_LOCAL7 (reserviert für eigenes benutzerdefiniertes Routing), LOG_DAEMON und LOG_MAIL. closelog() schließt die Verbindung — optional, aber sauber.

Wann sollte ich es verwenden?

• Lang laufende Dienste und CLI-Worker, bei denen kein Browser vorhanden ist, um Fehler anzuzeigen, und Sie möchten, dass Logs an derselben Stelle landen wie die übrigen System-Logs.
• Zentralisierte Protokollierung — ein Syslog-Daemon kann Nachrichten an einen Remote-Collector weiterleiten (rsyslog, journald, einen ELK/Graylog-Stack), sodass Sie Aggregation kostenlos erhalten.
• Schweregrad-basiertes Routing — wählen Sie die Facility/Priorität und lassen Sie den Daemon entscheiden, was gespeichert, gemeldet oder verworfen werden soll.

Für gewöhnliche anwendungsspezifische Fehlerprotokollierung, die nur in eine Datei schreibt, ist error_log() in der Regel einfacher. Greifen Sie auf syslog() zurück, wenn die Nachricht in die Logging-Pipeline auf Betriebssystemebene eintreten soll.

Häufige Fallstricke

• Literale Prozentzeichen maskieren. syslog() interpretiert %m; ein nicht maskiertes % in Ihrer Nachricht kann zu überraschender Ausgabe führen. Schreiben Sie %% für ein literales Prozentzeichen.
• Nachrichten können lautlos verworfen werden. Wenn die Konfiguration des Loggers Ihre Priorität/Facility herausfiltert, erscheint nichts — das ist Konfiguration, kein PHP-Fehler. Prüfen Sie /etc/rsyslog.conf oder journalctl, wenn eine Zeile fehlt.
• Es ist nicht dasselbe wie die error_log-Ini-Einstellung von PHP. Das Setzen von error_log = syslog in php.ini leitet PHPs interne Fehler an syslog weiter; das eigene Aufrufen von syslog() protokolliert Ihre eigenen Nachrichten und ist unabhängig von dieser Einstellung.
• Einen Zeilenumbruch pro Aufruf. Übergeben Sie eine einzelne Zeile; der Daemon fügt den Zeitstempel, den Host und das Tag hinzu. Verwenden Sie kein \n in der Nachricht.

Verwandte Funktionen

• openlog() — öffnet die Verbindung und setzt den Bezeichner und die Facility.
• closelog() — schließt die Syslog-Verbindung.
• error_log() — sendet eine Nachricht an eine Datei, E-Mail oder das konfigurierte Log.

Fazit

syslog() ist der PHP-Einstiegspunkt in die Logging-Pipeline des Betriebssystems. Wählen Sie eine aussagekräftige Priorität, öffnen Sie optional eine Verbindung mit openlog(), um einen Bezeichner und eine Facility hinzuzufügen, maskieren Sie literale Prozentzeichen und denken Sie daran, dass der Daemon — nicht PHP — entscheidet, was letztendlich gespeichert wird. Für einfache Dateiprotokollierung bevorzugen Sie error_log(); für Logs auf Betriebssystemebene, die weiterleitbar und zentralisierbar sind, ist syslog() das richtige Werkzeug.

Übungen