logging.config.dictConfig centraliza la configuración de logs en un diccionario. En lugar de que cada módulo cree handlers y formatos, la aplicación define destinos, niveles y propagación una vez. Esto evita registros duplicados y facilita cambiar el comportamiento entre desarrollo y producción.

Este artículo amplía la guía de logging en Python. Las bibliotecas solo deben emitir eventos mediante logging.getLogger(__name__); la aplicación configura la salida.

Configuración mínima para consola

import logging
from logging.config import dictConfig

LOGGING = {
    "version": 1,
    "disable_existing_loggers": False,
    "formatters": {
        "standard": {
            "format": "%(asctime)s %(levelname)s %(name)s %(message)s",
        },
    },
    "handlers": {
        "console": {
            "class": "logging.StreamHandler",
            "formatter": "standard",
            "level": "INFO",
        },
    },
    "root": {"handlers": ["console"], "level": "INFO"},
}

dictConfig(LOGGING)
logger = logging.getLogger(__name__)
logger.info("aplicación iniciada")

version es obligatorio y actualmente debe valer 1. Mantener disable_existing_loggers en False evita silenciar loggers creados por dependencias antes de la configuración. Los niveles del logger y del handler filtran registros, así que ajústalos conscientemente.

Loggers por módulo y propagación

"loggers": {
    "mi_app.db": {
        "level": "WARNING",
        "handlers": [],
        "propagate": True,
    },
    "urllib3": {
        "level": "WARNING",
        "handlers": [],
        "propagate": True,
    },
}

Un logger con propagate=True envía el registro a sus ancestros. Si también posee un handler equivalente, el mensaje puede aparecer dos veces. Concentra los handlers en el logger raíz cuando todos los módulos comparten destinos.

Rota archivos para limitar su tamaño

"handlers": {
    "file": {
        "class": "logging.handlers.RotatingFileHandler",
        "filename": "logs/app.log",
        "maxBytes": 10_000_000,
        "backupCount": 5,
        "encoding": "utf-8",
        "formatter": "standard",
        "level": "INFO",
    },
}

Crea el directorio antes de aplicar la configuración. En contenedores y plataformas gestionadas suele ser mejor escribir en consola y dejar que la infraestructura recopile y rote. No dependas de un archivo local para auditoría persistente sin conocer el almacenamiento del despliegue.

Añade contexto sin construir frases

logger.info(
    "pedido procesado",
    extra={"request_id": request_id, "pedido_id": pedido.id},
)

Añade esos nombres al formatter. Asegura que cada registro los incluya o usa un filtro con valores predeterminados; de lo contrario, el formato fallará. Nunca registres contraseñas, tokens, cookies de sesión ni datos personales innecesarios.

Configura una vez y prueba

Llama a dictConfig en el punto de entrada antes de iniciar workers. Las reconfiguraciones repetidas dificultan el diagnóstico. En pruebas, pytest y caplog observan eventos sin depender del archivo final; consulta cómo probar logs con caplog.

Valida niveles por entorno, ausencia de duplicados, encoding y rotación. Genera un error controlado y llama a logger.exception() dentro de except para comprobar el traceback. Asegura que los secretos se eliminen antes de llegar al handler.

La referencia oficial de logging.config, consultada el 28 de julio de 2026, define el esquema de dictConfig y sus errores de configuración.