Función PHP syslog(): Todo lo que necesitas saber

La función syslog() envía un mensaje al registrador del sistema — la misma instalación de registro utilizada por el sistema operativo y otros servicios (el destino es /var/log/syslog o /var/log/messages en la mayoría de sistemas Linux, la Consola / registro unificado en macOS y el Registro de eventos en Windows). A diferencia de escribir en un archivo con error_log() o file_put_contents(), syslog() entrega tu mensaje a un demonio que puede enrutarlo, filtrarlo, rotarlo y reenviarlo. Esta página cubre la sintaxis, las constantes de prioridad y facilidad, un ejemplo funcional completo y las consideraciones importantes a tener en cuenta.

Sintaxis

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

La función acepta dos parámetros y devuelve true en caso de éxito o false en caso de error:

• $priority — el nivel de severidad del mensaje, expresado como una de las constantes de prioridad LOG_* que se muestran a continuación.
• $message — el texto a registrar. La secuencia de dos caracteres %m se reemplaza por la cadena del mensaje de error del errno actual (el último error del sistema), lo cual es ocasionalmente útil, pero significa que los signos de porcentaje literales deben escaparse como %%.

Niveles de prioridad

La prioridad indica al registrador cuán grave es el mensaje. De más a menos urgente:

La configuración propia del registrador decide qué prioridades se escriben realmente, por lo que una línea LOG_DEBUG puede descartarse mientras que una línea LOG_ERR se conserva — tu código sigue llamando a syslog() de la misma manera independientemente.

Un ejemplo completo

No es estrictamente necesario usar openlog() — llamar a syslog() por sí solo funciona — pero abrir la conexión primero te permite establecer un prefijo identificador y una facilidad para que tus mensajes sean fáciles de encontrar y enrutar.

<?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 línea resultante en el registro del sistema tiene un aspecto similar a este:

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

openlog() acepta tres argumentos: un identificador que se añade como prefijo a cada mensaje, una máscara de bits de opciones (LOG_PID añade el ID del proceso, LOG_PERROR también imprime en stderr, LOG_CONS recurre a la consola si el registrador no está disponible) y una facilidad que categoriza el origen. Las facilidades más comunes son LOG_USER (el predeterminado para aplicaciones genéricas), LOG_LOCAL0–LOG_LOCAL7 (reservadas para tu propio enrutamiento personalizado), LOG_DAEMON y LOG_MAIL. closelog() cierra la conexión — opcional, pero recomendable.

¿Cuándo debo usarlo?

• Servicios de larga ejecución y trabajadores CLI donde no hay navegador para mostrar errores y deseas que los registros lleguen al mismo lugar que el resto de los registros del sistema.
• Registro centralizado — un demonio syslog puede reenviar mensajes a un recolector remoto (rsyslog, journald, una pila ELK/Graylog), por lo que obtienes agregación de forma gratuita.
• Enrutamiento basado en severidad — elige la facilidad/prioridad y deja que el demonio decida qué almacenar, sobre qué alertar o qué descartar.

Para el registro de errores ordinario por aplicación que simplemente escribe en un archivo, error_log() suele ser más sencillo. Recurre a syslog() cuando quieras que el mensaje entre en la canalización de registro a nivel del sistema operativo.

Consideraciones comunes

• Escapa los signos de porcentaje literales. syslog() interpreta %m; un % sin escapar en tu mensaje puede producir resultados inesperados. Escribe %% para un signo de porcentaje literal.
• Los mensajes pueden descartarse silenciosamente. Si la configuración del registrador filtra tu prioridad/facilidad, no aparece nada — eso es configuración, no un error de PHP. Comprueba /etc/rsyslog.conf o journalctl si falta una línea.
• No es lo mismo que la configuración ini error_log de PHP. Establecer error_log = syslog en php.ini enruta los errores internos de PHP a syslog; llamar a syslog() tú mismo registra tus propios mensajes y es independiente de esa configuración.
• Una línea nueva por llamada. Pasa una sola línea; el demonio añade la marca de tiempo, el host y la etiqueta. No insertes \n en el mensaje.

Funciones relacionadas

• openlog() — abre la conexión y establece el identificador y la facilidad.
• closelog() — cierra la conexión syslog.
• error_log() — envía un mensaje a un archivo, correo electrónico o el registro configurado.

Conclusión

syslog() es el punto de entrada de PHP a la canalización de registro del sistema operativo. Elige una prioridad significativa, abre opcionalmente una conexión con openlog() para añadir un identificador y una facilidad, escapa los signos de porcentaje literales y recuerda que el demonio — no PHP — decide qué se almacena finalmente. Para el registro simple en archivos, prefiere error_log(); para registros a nivel del sistema operativo, enrutables y centralizables, syslog() es la herramienta adecuada.

Práctica