O módulo syslog envia mensagens diretamente para a infraestrutura de logs do Unix. Em vez de gravar um arquivo próprio, a aplicação entrega eventos ao daemon do sistema, que pode aplicar filtros, rotação, encaminhamento remoto, retenção e integração com ferramentas como journald ou rsyslog.
Essa interface é útil para serviços pequenos, scripts de inicialização, ferramentas administrativas e componentes que precisam participar do logging do sistema sem configurar toda a biblioteca logging. Para aplicações grandes, logging.handlers.SysLogHandler costuma oferecer integração mais flexível.
Disponibilidade
syslog está disponível em Unix, mas não em WASI nem iOS. A lista de facilities e opções depende do syslog.h da plataforma.
try:
import syslog
except ImportError:
syslog = None
Em Windows, use Event Log, logging para arquivo ou um handler remoto apropriado.
Primeira mensagem
import syslog
syslog.syslog("Processamento iniciado")
Sem prioridade explícita, o nível padrão é LOG_INFO. Se openlog() ainda não foi chamado, o módulo o chama automaticamente com valores padrão.
Prioridades
Os níveis, do mais grave ao mais detalhado, incluem LOG_EMERG, LOG_ALERT, LOG_CRIT, LOG_ERR, LOG_WARNING, LOG_NOTICE, LOG_INFO e LOG_DEBUG.
syslog.syslog(syslog.LOG_WARNING, "Fila próxima do limite")
syslog.syslog(syslog.LOG_ERR, "Falha ao gravar resultado")
Não marque todo erro como crítico. Prioridades exageradas tornam alertas reais difíceis de identificar.
Facility
A facility indica a categoria de origem, como LOG_USER, LOG_DAEMON, LOG_AUTH, LOG_MAIL e LOG_LOCAL0 a LOG_LOCAL7.
syslog.openlog(
ident="meu-servico",
logoption=syslog.LOG_PID,
facility=syslog.LOG_DAEMON,
)
Use facilities locais quando a política do servidor reservar uma delas para a aplicação. Coordene com a configuração do administrador.
Facility na própria prioridade
Uma mensagem pode combinar facility e nível com OR bit a bit.
prioridade = syslog.LOG_LOCAL0 | syslog.LOG_NOTICE
syslog.syslog(prioridade, "Configuração recarregada")
Quando a facility não está embutida, vale a definida por openlog().
Identificação
O argumento ident é prefixado às mensagens. Por padrão, usa o nome do programa derivado de sys.argv[0].
Escolha um identificador estável, curto e sem dados do usuário. Não inclua token, caminho temporário ou ID sensível.
LOG_PID
LOG_PID inclui o PID na mensagem, facilitando distinguir workers.
syslog.openlog("worker", syslog.LOG_PID, syslog.LOG_DAEMON)
PID não é identificador durável: o sistema o reutiliza. Para correlação, adicione um request ID ou job ID no conteúdo.
Outras opções
LOG_NDELAY abre a conexão imediatamente. LOG_PERROR, quando disponível, também escreve em stderr. LOG_CONS pode tentar o console se o logger falhar.
Constantes como LOG_NOWAIT e LOG_ODELAY não existem em todos os sistemas. Verifique com hasattr().
Fechar e redefinir
closelog() fecha a conexão e restaura os valores internos. A próxima chamada a syslog()` abrirá novamente com defaults.
try:
syslog.openlog("job", syslog.LOG_PID, syslog.LOG_USER)
syslog.syslog("Início")
finally:
syslog.closelog()
Em aplicações longas, não é necessário abrir e fechar para cada mensagem.
Máscara de prioridades
setlogmask() filtra níveis no processo antes de enviá-los.
mascara_anterior = syslog.setlogmask(syslog.LOG_UPTO(syslog.LOG_INFO))
try:
syslog.syslog(syslog.LOG_DEBUG, "Não será enviado")
syslog.syslog(syslog.LOG_INFO, "Será enviado")
finally:
syslog.setlogmask(mascara_anterior)
LOG_MASK()` seleciona um nível e LOG_UPTO()` todos até certa prioridade.
Não use concatenação de dados não confiáveis
Usuários podem inserir newlines, tabs, caracteres de controle e conteúdo que simula outra entrada.
def limpar_log(valor):
return str(valor).replace("\r", "\\r").replace("\n", "\\n")
syslog.syslog(syslog.LOG_INFO, f"usuario={limpar_log(usuario)}")
Isso reduz log injection, mas ainda aplique limites de tamanho e redija segredos.
Logs estruturados
O syslog clássico recebe texto. Você pode usar pares chave-valor ou JSON compacto.
import json
mensagem = json.dumps(
{"evento": "login", "resultado": "falha", "ip": ip},
ensure_ascii=False,
separators=(",", ":"),
)
syslog.syslog(syslog.LOG_WARNING, mensagem)
Confirme se o pipeline preserva JSON e não adiciona prefixos dentro do payload.
Limite de tamanho
Daemons, sockets Unix e encaminhadores podem truncar mensagens grandes. Não envie stack traces enormes como uma única linha.
Resuma o evento, use um ID de correlação e armazene detalhes em sistema apropriado.
Encoding
A API recebe str. A codificação efetiva e o comportamento com caracteres inválidos dependem da implementação do sistema.
Use Unicode válido e teste acentos no ambiente real. Para interoperabilidade legada, talvez seja necessário ASCII ou escaping explícito.
Exceções
O syslog do sistema é projetado para ser simples, mas operações ainda podem falhar por configuração, permissões ou ausência do socket. Não deixe logging secundário derrubar a tarefa principal sem decisão consciente.
try:
syslog.syslog(syslog.LOG_ERR, mensagem)
except OSError:
escrever_fallback_seguro(mensagem)
Evite recursão: o fallback não deve tentar usar o mesmo syslog novamente.
Segredos
Nunca registre senhas, tokens, cookies, chaves, strings de conexão completas, dados de cartão ou conteúdo privado. Logs do sistema podem ser acessíveis a operadores e encaminhados para terceiros.
Redija campos antes de formatar a mensagem.
Dados pessoais
Minimize IPs, e-mails e identificadores. Aplique retenção compatível com a finalidade e políticas de privacidade.
Subinterpretadores
Desde Python 3.12, openlog() e closelog() só podem ser chamados no interpretador principal. syslog() em subinterpretador exige que openlog() já tenha sido chamado no principal; caso contrário, gera RuntimeError.
Isso afeta hosts que usam múltiplos interpretadores, não a maioria dos scripts comuns.
Novas facilities
Python 3.13 adicionou constantes como LOG_FTP, LOG_NETINFO, LOG_REMOTEAUTH, LOG_INSTALL, LOG_RAS e LOG_LAUNCHD quando presentes na plataforma.
Teste existência antes de usar.
Auditoria
Chamadas a syslog(), openlog(), closelog() e setlogmask() geram eventos de auditoria. Ambientes restritos podem observar ou bloquear logs.
syslog ou logging?
O módulo syslog é direto e Unix-specific. A biblioteca logging oferece filtros, formatters, handlers, hierarquia e integração com testes.
Para aplicações maiores, configure logging.handlers.SysLogHandler. Ele também pode enviar para servidor remoto, enquanto o módulo nativo conversa com a biblioteca syslog local.
SysLogHandler
import logging
from logging.handlers import SysLogHandler
logger = logging.getLogger("app")
handler = SysLogHandler(address="/dev/log")
logger.addHandler(handler)
logger.warning("Fila próxima do limite")
O caminho do socket varia: Linux pode usar /dev/log, macOS outras interfaces. Teste a configuração.
journald
Em sistemas com systemd, mensagens syslog podem aparecer no journal. Campos estruturados nativos do journald exigem biblioteca específica; texto syslog não ganha estrutura automaticamente.
Containers
Em containers, geralmente é melhor escrever logs estruturados em stdout/stderr e deixar o runtime coletar. O socket syslog pode não existir.
Não monte /dev/log automaticamente sem avaliar segurança e operação.
Fork
Depois de fork, o filho herda estado. Reabra com um ident adequado se pai e filho representam componentes diferentes.
Não faça trabalho complexo entre fork e exec em processo multithread.
Rate limiting
Um loop de erro pode inundar syslog, consumir disco e esconder eventos úteis. Aplique amostragem, agregação ou rate limit.
if contador % 100 == 1:
syslog.syslog(syslog.LOG_WARNING, f"erro repetido vezes={contador}")
Correlação
Inclua IDs opacos para requisição, job ou sessão, mas não use dados secretos. Isso permite juntar eventos sem depender de ordem exata.
Teste local
Envie uma mensagem com identificador exclusivo e consulte a ferramenta da plataforma, como journalctl ou arquivos em /var/log. O destino depende da configuração do daemon.
Testes automatizados
Não faça testes dependerem do syslog global da máquina. Encapsule a função de envio e substitua por fake. Em integração, use container ou daemon dedicado.
Erros comuns
Os erros mais frequentes são registrar segredos, permitir newlines de usuário, exagerar prioridades, presumir facilities presentes, enviar mensagens enormes, depender de /dev/log em container, misturar estado global entre componentes e usar syslog direto quando logging seria mais testável.
Conclusão
syslog oferece uma ponte simples entre Python e o logger Unix. Use identificador estável, prioridades honestas, conteúdo limitado e sanitizado e fallback que não cause recursão.
Para aplicações complexas, considere logging.handlers.SysLogHandler ou stdout estruturado. Consulte a documentação oficial de syslog e o manual syslog(3).
