QueueHandler e QueueListener para Logs em Python resolve um problema recorrente em projetos Python: Envie LogRecord a uma fila e processe handlers lentos em uma thread dedicada. Este guia mostra o mecanismo, um exemplo executável e os limites que evitam uma implementação frágil.
Conceito e caso de uso
QueueHandler coloca registros na fila; QueueListener os entrega a um ou mais handlers fora da thread que atendeu a requisição.
Para revisar os fundamentos relacionados, consulte também o guia de dictConfig. A integração fica mais simples quando cada função recebe dependências e dados explicitamente, em vez de depender de estado global.
Exemplo prático
import logging
from logging.handlers import QueueHandler, QueueListener
from queue import Queue
queue = Queue(maxsize=10_000)
console = logging.StreamHandler()
listener = QueueListener(queue, console, respect_handler_level=True)
logger = logging.getLogger("app")
logger.addHandler(QueueHandler(queue))
listener.start()
try:
logger.info("request completed")
finally:
listener.stop()Defina capacidade e política para fila cheia, respeite níveis dos handlers e pare o listener durante o shutdown para drenar registros.
Decisões importantes
A escolha correta depende do contrato público, do volume e do comportamento em caso de falha.
Considere como a solução se comporta sob concorrência, entradas vazias e falhas parciais. Documente qualquer limite que afete consumidores e mantenha nomes que expressem a intenção.
Erros comuns
O exemplo mínimo não substitui limites, tratamento de erros e observabilidade. Uma fila ilimitada pode consumir memória. Com multiprocessing, a fila e logs internos do próprio multiprocessing exigem cuidado para evitar recursão.
Evite capturar exceções sem contexto ou retornar resultados parciais como se fossem completos. Uma falha explícita costuma ser mais segura que dados silenciosamente incorretos.
Como validar
Valide o comportamento, não apenas a linha feliz. Teste saturação, exceções, shutdown e ordem esperada. Confirme que dados sensíveis são filtrados antes de entrar na fila.