QueueHandler y QueueListener para Logs en Python resuelve un problema frecuente en proyectos Python: Envía LogRecord a una cola y procesa handlers lentos en un thread dedicado. Esta guía explica el mecanismo, presenta un ejemplo ejecutable y marca los límites que evitan una implementación frágil.
Concepto y caso de uso
QueueHandler encola registros; QueueListener los entrega a handlers fuera del thread que atiende la petición.
Para repasar los fundamentos relacionados, consulta también la guía de dictConfig. La integración es más simple cuando cada función recibe dependencias y datos explícitamente en lugar de depender de estado global.
Ejemplo práctico
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()Define capacidad y política de cola llena, respeta niveles y detén el listener en el shutdown para vaciar registros.
Decisiones importantes
La elección correcta depende del contrato público, del volumen y del comportamiento ante fallos.
Considera concurrencia, entradas vacías y fallos parciales. Documenta cada límite que afecte a consumidores y usa nombres que expresen intención.
Errores frecuentes
El ejemplo mínimo no sustituye límites, manejo de errores y observabilidad. Una cola ilimitada consume memoria. Con multiprocessing, compartir su cola con logs internos puede producir recursión o bloqueo.
Evita capturar excepciones sin contexto o devolver resultados parciales como si fueran completos. Un fallo explícito suele ser más seguro que datos silenciosamente incorrectos.
Cómo validar
Valida el comportamiento y no solo el camino feliz. Prueba saturación, excepciones, shutdown y orden necesario. Comprueba que los datos sensibles se filtran antes de encolar.