Ver también
Los programadores de Python a menudo utilizan print() en su código como una herramienta de depuración rápida y conveniente. Utilizar el marco de registro es solo un poco más esfuerzo que eso, pero es mucho más elegante y flexible. Además de ser útil para la depuración, el registro también puede proporcionarte información más - y mejor estructurada - sobre el estado y la salud de tu aplicación.
Django utiliza y extiende el módulo de registro interno logging de Python para realizar la depuración del sistema. Este módulo se discute en detalle en la documentación propia de Python; esta sección proporciona una visión general rápida.
Una configuración de registro de Python consta de cuatro partes:
Un registrador es el punto de entrada en el sistema de registro. Cada registrador es un contenedor con nombre a través del cual se pueden escribir mensajes para su procesamiento.
Un registrador está configurado para tener un nivel de registro. Este nivel de registro describe la severidad de los mensajes que el registrador manejará. Python define los siguientes niveles de registro:
DEBUG: Información de bajo nivel del sistema para fines de depuración
INFO: Información general del sistema
WARNING: Información que describe un problema menor que ha ocurrido.
ERROR: Información que describe un problema importante que ha ocurrido.
CRITICAL: Información que describe un problema crítico que ha ocurrido.
Cada mensaje escrito en el logger es un Registro de Log. Cada registro de log también tiene un nivel de log que indica la gravedad del mensaje específico. Un registro de log puede contener metadata útil que describe el evento que se está registrando. Esto puede incluir detalles como una pila de trazas o un código de error.
Cuando se le da un mensaje al logger, el nivel de log del mensaje se compara con el nivel de log del logger en sí mismo. Si el nivel de log del mensaje cumple o supera el nivel de log del logger, el mensaje someterá a procesamiento adicional. Si no lo hace, el mensaje será ignorado.
Una vez que un logger ha determinado que un mensaje necesita ser procesado, se le pasa a un manejador.
El manejador es el motor que determina qué sucede con cada mensaje en un logger. Describe un comportamiento de registro particular, como escribir un mensaje en la pantalla, en un archivo o en una conexión de red.
Like los registradores, los manejadores también tienen un nivel de registro. Si el nivel de registro de un registro de registro no cumple o supera el nivel del manejador, el manejador ignorará el mensaje.
Un registrador puede tener múltiples manejadores, y cada manejador puede tener un diferente nivel de registro. De esta manera, es posible proporcionar diferentes formas de notificación dependiendo de la importancia de un mensaje. Por ejemplo, podrías instalar un manejador que envíe ERROR y CRITICAL mensajes a un servicio de paginación, mientras que un segundo manejador registra todos los mensajes (incluidos ERROR y CRITICAL mensajes) en un archivo para su análisis posterior.
Un filtro se utiliza para proporcionar control adicional sobre qué registros de registro se pasan del registrador al manejador.
Por defecto, cualquier mensaje de registro que cumpla con los requisitos de nivel de registro será tratado. Sin embargo, instalando un filtro, puedes colocar criterios adicionales en el proceso de registro. Por ejemplo, podrías instalar un filtro que solo permita mensajes ERROR desde una fuente particular para ser emitidos.
Los filtros también se pueden utilizar para modificar el registro de registro antes de su emisión. Por ejemplo, podrías escribir un filtro que degrade los registros de ERROR a registros WARNING si se cumplen ciertos criterios.
Los filtros se pueden instalar en registradores o en manejadores; se pueden utilizar múltiples filtros en una cadena para realizar acciones de filtrado múltiples.
Finalmente, un registro de registro necesita ser renderizado como texto. Los formateadores describen el formato exacto de ese texto. Un formateador suele consistir en una cadena de formato Python que contiene atributos del registro de registro; sin embargo, también puedes escribir formateadores personalizados para implementar comportamiento de formateo específico.
El sistema de registro maneja información potencialmente sensible. Por ejemplo, el registro de la aplicación puede contener información sobre una solicitud web o un seguimiento de pila, mientras que algunos de los datos que recopilas en tus propios registradores también pueden tener implicaciones de seguridad. Necesitas estar seguro de saber:
qué información se recopila
dónde se almacenará posteriormente
cómo se transferirá
quién podría tener acceso a ella.
Para ayudar a controlar la recopilación de información sensible, puedes designar explícitamente cierta información sensible para que sea filtrada de los informes de errores – lee más sobre cómo hacerlo en filtrar informes de error.
El manejo de correo electrónico administrativo integrado (AdminEmailHandler) merece una mención en el contexto de la seguridad. Si su opción include_html está habilitada, el mensaje de correo electrónico que envía contendrá un seguimiento completo, con nombres y valores de variables locales en cada nivel de la pila, más los valores de tus configuraciones Django (en otras palabras, el mismo nivel de detalle que se expone en una página web cuando DEBUG está True).
En general no se considera una buena idea enviar información potencialmente sensible por correo electrónico. Considera en su lugar utilizar uno de los muchos servicios terceros a los cuales se pueden enviar logs detallados para obtener el mejor de ambos mundos – la rica información de seguimientos completos, gestión clara de quién está notificado y tiene acceso a la información, etc.
La traducción de los textos es la siguiente:
Para configurar el registro, utilizas la configuración LOGGING para definir un diccionario de configuraciones de registro. Estas configuraciones describen los registradores, manipuladores, filtros y formateadores que deseas en tu configuración de registro, así como los niveles de registro y otras propiedades que deseas que esos componentes tengan.
Por defecto, la configuración LOGGING se combina con la configuración de registro por defecto de Django utilizando el siguiente esquema.
Si la clave disable_existing_loggers en el diccionario de configuración LOGGING está establecida en True (lo que es el valor por defecto de dictConfig si la clave no existe), entonces todos los registradores de la configuración por defecto se deshabilitarán. Los registradores deshabilitados no son lo mismo que eliminados; el registrador seguirá existiendo, pero silenciosamente descartará cualquier mensaje registrado en él, sin propagar incluso entradas a un registrador padre. Por tanto, debes ser muy cuidadoso utilizando 'disable_existing_loggers': True; probablemente no es lo que deseas. En su lugar, puedes establecer disable_existing_loggers en False y redefine algunos o todos los registradores por defecto; o puedes establecer LOGGING_CONFIG en None y manejar la configuración de registro tú mismo <disabling-logging-configuration>`.
El registro se configura como parte de la función general Django setup(). Por lo tanto, puedes estar seguro de que los registradores siempre están listos para uso en tu código del proyecto.
La documentación completa sobre el formato dictConfig es la mejor fuente de información sobre las configuraciones de registro como diccionarios. Sin embargo, para darte una idea de lo que es posible, aquí hay varios ejemplos.
Para empezar, aquí está una pequeña configuración que te permitirá enviar todos los mensajes de registro a la consola:
settings.py¶import os
LOGGING = {
"version": 1,
"disable_existing_loggers": False,
"handlers": {
"console": {
"class": "logging.StreamHandler",
},
},
"root": {
"handlers": ["console"],
"level": "WARNING",
},
}
Esta configura el registrador padre root para enviar mensajes con el nivel WARNING y superior al manipulador de consola. Al ajustar el nivel a INFO o DEBUG puedes mostrar más mensajes. Esto puede ser útil durante el desarrollo.
A continuación, podemos agregar un registro más detallado. Aquí hay un ejemplo de cómo hacer que el sistema de registro imprima más mensajes del registrador django llamado:
settings.py¶import os
LOGGING = {
"version": 1,
"disable_existing_loggers": False,
"handlers": {
"console": {
"class": "logging.StreamHandler",
},
},
"root": {
"handlers": ["console"],
"level": "WARNING",
},
"loggers": {
"django": {
"handlers": ["console"],
"level": os.getenv("DJANGO_LOG_LEVEL", "INFO"),
"propagate": False,
},
},
}
Por defecto, esta configuración envía mensajes del registrador django con nivel INFO o superior a la consola. Este es el mismo nivel que la configuración de registro por defecto de Django, excepto que la configuración por defecto solo muestra registros de nivel INFO cuando DEBUG=True. Django no registra muchos mensajes de nivel INFO. Con esta configuración, sin embargo, puedes establecer la variable de entorno DJANGO_LOG_LEVEL=DEBUG para ver todos los registros de depuración de Django que son muy verbosos ya que incluyen todas las consultas a la base de datos.
No necesitas escribir en la consola. Aquí tienes una configuración que escribe todo el registro del django logger nombrado a un archivo local:
settings.py¶LOGGING = {
"version": 1,
"disable_existing_loggers": False,
"handlers": {
"file": {
"level": "DEBUG",
"class": "logging.FileHandler",
"filename": "/path/to/django/debug.log",
},
},
"loggers": {
"django": {
"handlers": ["file"],
"level": "DEBUG",
"propagate": True,
},
},
}
Si utilizas este ejemplo, asegúrate de cambiar el 'filename' camino a una ubicación que sea writable por el usuario que está ejecutando la aplicación Django.
Finalmente, aquí tienes un ejemplo de una configuración de registro bastante compleja:
settings.py¶LOGGING = {
"version": 1,
"disable_existing_loggers": False,
"formatters": {
"verbose": {
"format": "{levelname} {asctime} {module} {process:d} {thread:d} {message}",
"style": "{",
},
"simple": {
"format": "{levelname} {message}",
"style": "{",
},
},
"filters": {
"special": {
"()": "project.logging.SpecialFilter",
"foo": "bar",
},
"require_debug_true": {
"()": "django.utils.log.RequireDebugTrue",
},
},
"handlers": {
"console": {
"level": "INFO",
"filters": ["require_debug_true"],
"class": "logging.StreamHandler",
"formatter": "simple",
},
"mail_admins": {
"level": "ERROR",
"class": "django.utils.log.AdminEmailHandler",
"filters": ["special"],
},
},
"loggers": {
"django": {
"handlers": ["console"],
"propagate": True,
},
"django.request": {
"handlers": ["mail_admins"],
"level": "ERROR",
"propagate": False,
},
"myproject.custom": {
"handlers": ["console", "mail_admins"],
"level": "INFO",
"filters": ["special"],
},
},
}
Esta configuración de registro hace las siguientes cosas:
Identifica la configuración como siendo en formato “dictConfig versión 1”. En la actualidad, ésta es la única versión de formato dictConfig.
Define dos formateadores:
simple, que imprime el nombre del nivel de registro (por ejemplo, DEBUG) y el mensaje de registro.
La cadena format es una cadena de formato Python normal que describe los detalles que se deben imprimir en cada línea de registro. La lista completa de detalles que se pueden imprimir se puede encontrar en Formatter Objects.
verbose, que imprime el nombre del nivel de registro, el mensaje de registro, más el tiempo, proceso, hilo y módulo que generan el mensaje de registro.
Define dos filtros:
project.logging.SpecialFilter, utilizando el alias special. Si este filtro requiere argumentos adicionales, pueden proporcionarse como claves adicionales en el diccionario de configuración del filtro. En este caso, el argumento foo tendrá un valor de bar cuando se instancie SpecialFilter.
django.utils.log.RequireDebugTrue, que pasa los registros cuando DEBUG es True.
Define dos manejores:
console, un StreamHandler, que imprime cualquier mensaje de INFO (o superior) en sys.stderr. Este manejador utiliza el formato de salida simple.
mail_admins, un AdminEmailHandler, que envía cualquier mensaje de ERROR (o superior) al sitio ADMINS. Este manejador utiliza el filtro special.
Configura tres registradores:
django, que pasa todos los mensajes al manejador console.
django.request, que pasa todos los mensajes de ERROR al manejador mail_admins. Además, este registrador está marcado para no propagar mensajes. Esto significa que los mensajes de registro escritos en django.request no serán gestionados por el registrador django.
myproject.custom, que pasa todos los mensajes de INFO o superior que también pasan el filtro special a dos manejores – el console, y mail_admins. Esto significa que todos los mensajes de nivel INFO (o superior) se imprimirán en la consola; los mensajes de ERROR y CRITICAL también se enviarán por correo electrónico.
Si no deseas utilizar el formato de configuración de Python para configurar tu logger, puedes especificar tu propio esquema de configuración.
La configuración LOGGING_CONFIG define la función invocable que se usará para configurar los loggers de Django. Por defecto, apunta a la función logging.config.dictConfig() de Python. Sin embargo, si deseas utilizar un proceso de configuración diferente, puedes usar cualquier otra función invocable que tome un argumento único. El contenido de LOGGING se proporcionará como valor del argumento cuando se configure el registro.
Si no deseas configurar el registro en absoluto (o quieres configurarlo manualmente utilizando tu propio enfoque), puedes establecer LOGGING_CONFIG en None. Esto deshabilitará el proceso de configuración para la <ref target=»default-logging-configuration»>configuración de registro por defecto de Django</ref>.
Establecer LOGGING_CONFIG en None solo significa que se ha deshabilitado el proceso de configuración automática, no el registro en sí. Si desactivas el proceso de configuración, Django seguirá haciendo llamadas al registro, cayendo en lo que sea la configuración de registro por defecto definida.
Aquí tienes un ejemplo que deshabilita la configuración del registro de Django y luego configura manualmente el registro:
settings.py¶LOGGING_CONFIG = None
import logging.config
logging.config.dictConfig(...)
Ten en cuenta que el proceso de configuración automática solo llama a LOGGING_CONFIG una vez que se hayan cargado completamente las configuraciones. En contraste, configurar manualmente el registro en tu archivo de configuración cargará tu configuración de registro inmediatamente. Como tal, tu configuración de registro debe aparecer después de cualquier configuración sobre la cual dependa.
may 31, 2026