Função PHP syslog(): Tudo o Que Você Precisa Saber

A função syslog() envia uma mensagem para o logger do sistema — o mesmo mecanismo de registro usado pelo sistema operacional e outros serviços (o destino é /var/log/syslog ou /var/log/messages na maioria dos sistemas Linux, o Console / log unificado no macOS, e o Visualizador de Eventos no Windows). Ao contrário de escrever em um arquivo com error_log() ou file_put_contents(), syslog() entrega sua mensagem a um daemon que pode roteá-la, filtrá-la, rotacioná-la e encaminhá-la por você. Esta página aborda a sintaxe, as constantes de prioridade e facilidade, um exemplo completo e funcional, além das armadilhas mais importantes.

Sintaxe

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

A função aceita dois parâmetros e retorna true em caso de sucesso ou false em caso de falha:

• $priority — o nível de severidade da mensagem, expresso como uma das constantes de prioridade LOG_* abaixo.
• $message — o texto a ser registrado. A sequência de dois caracteres %m é substituída pela string de mensagem de erro do errno atual (o último erro do sistema), o que às vezes é útil, mas significa que sinais de porcentagem literais devem ser escapados como %%.

Níveis de prioridade

A prioridade informa ao logger o quão grave é a mensagem. Da mais para a menos urgente:

A própria configuração do logger decide quais prioridades são realmente gravadas, portanto, uma linha LOG_DEBUG pode ser descartada enquanto uma linha LOG_ERR é mantida — seu código ainda chama syslog() da mesma forma, independentemente disso.

Um exemplo completo

Você não precisa estritamente de openlog() — chamar syslog() por conta própria funciona — mas abrir a conexão primeiro permite definir um prefixo de identificação e uma facilidade para que suas mensagens sejam fáceis de encontrar e rotear.

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

Uma linha resultante no log do sistema se parece mais ou menos com isso:

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

openlog() aceita três argumentos: um identificador prefixado a cada mensagem, uma máscara de bits de opções (LOG_PID adiciona o ID do processo, LOG_PERROR também imprime no stderr, LOG_CONS recorre ao console se o logger estiver inacessível) e uma facilidade que categoriza a origem. As facilidades comuns são LOG_USER (o padrão para aplicações genéricas), LOG_LOCAL0–LOG_LOCAL7 (reservadas para roteamento personalizado), LOG_DAEMON e LOG_MAIL. closelog() fecha a conexão — opcional, mas organizado.

Quando devo usá-la?

• Serviços de longa execução e workers de CLI onde não há navegador para exibir erros e você quer que os logs sejam registrados no mesmo lugar que os demais logs do sistema.
• Registro centralizado — um daemon syslog pode encaminhar mensagens a um coletor remoto (rsyslog, journald, uma pilha ELK/Graylog), oferecendo agregação gratuitamente.
• Roteamento baseado em severidade — escolha a facilidade/prioridade e deixe o daemon decidir o que armazenar, alertar ou descartar.

Para registro de erros comum por aplicação que apenas grava em um arquivo, error_log() geralmente é mais simples. Use syslog() quando quiser que a mensagem entre no pipeline de registro em nível de SO.

Armadilhas comuns

• Escape sinais de porcentagem literais. syslog() interpreta %m; um % não escapado na sua mensagem pode produzir saídas inesperadas. Escreva %% para uma porcentagem literal.
• Mensagens podem ser descartadas silenciosamente. Se a configuração do logger filtrar sua prioridade/facilidade, nada aparece — isso é configuração, não um erro do PHP. Verifique /etc/rsyslog.conf ou journalctl se uma linha sumir.
• Não é o mesmo que a configuração error_log do PHP. Definir error_log = syslog no php.ini roteia os erros internos do PHP para o syslog; chamar syslog() você mesmo registra suas próprias mensagens e é independente dessa configuração.
• Uma linha por chamada. Passe uma única linha; o daemon adiciona o timestamp, o host e a tag. Não incorpore \n na mensagem.

Funções relacionadas

• openlog() — abre a conexão e define o identificador e a facilidade.
• closelog() — fecha a conexão syslog.
• error_log() — envia uma mensagem para um arquivo, e-mail ou o log configurado.

Conclusão

syslog() é o ponto de entrada do PHP no pipeline de registro do sistema operacional. Escolha uma prioridade significativa, opcionalmente abra uma conexão com openlog() para adicionar um identificador e uma facilidade, escape sinais de porcentagem literais e lembre-se de que o daemon — não o PHP — decide o que é finalmente armazenado. Para registro simples em arquivo, prefira error_log(); para logs em nível de SO, roteáveis e centralizáveis, syslog() é a ferramenta certa.

Prática