Django proporciona una configuración de registro por defecto que funciona (configuración de registro por defecto), que se puede extender fácilmente.
Para enviar un mensaje de registro desde tu código, coloca una llamada de registro en él.
No te dejes tentar a utilizar llamadas de registro en settings.py.
La forma en que Django configura el registro como parte de la función setup() significa que las llamadas de registro colocadas en settings.py pueden no funcionar como se espera, porque el registro no estará configurado en ese punto. Para explorar el registro, utiliza una función de vista tal como se sugiere en el ejemplo a continuación.
Primero, importa la biblioteca de registro de Python y luego obtén una instancia del logger con logging.getLogger(). Proporciona al método getLogger() un nombre para identificarlo y los registros que emite. Una buena opción es utilizar __name__ (ver Utiliza nombres de loggers a continuación para más información) lo que proporcionará el nombre del módulo Python actual como una ruta punteada:
import logging
logger = logging.getLogger(__name__)
Es una buena convención realizar esta declaración a nivel de módulo.
Y luego en una función, por ejemplo en una vista, envía un registro al logger:
def some_view(request):
...
if some_risky_state:
logger.warning("Platform is running at risk")
Cuando se ejecuta este código, un LogRecord que contiene ese mensaje será enviado al registrador. Si estás utilizando la configuración de registro por defecto de Django, el mensaje aparecerá en la consola.
El nivel de advertencia WARNING utilizado en el ejemplo anterior es uno de varios niveles de severidad de registro: DEBUG, INFO, WARNING, ERROR, CRITICAL. Por lo tanto, otro ejemplo podría ser:
logger.critical("Payment system is not responding")
Importante
Registros con un nivel inferior a WARNING no aparecerán en la consola por defecto. Cambiar este comportamiento requiere una configuración adicional.
Aunque la configuración de registro de Django funciona por defecto, puedes controlar exactamente cómo se envían tus registros a diferentes destinos - archivos de registro, servicios externos, correo electrónico y así sucesivamente - con una configuración adicional.
Puedes configurar:
mappings del logger, para determinar qué registros se envían a cuáles manipuladores
Los handlers, para determinar qué hacen con los registros que reciben.
los filtros, para proporcionar control adicional sobre la transferencia de registros y modificar incluso registros en su lugar.
los formateadores, para convertir objetos LogRecord a una cadena o otra forma para consumo por seres humanos u otro sistema.
Hay varias formas de configurar el registro. En Django, la configuración más comúnmente utilizada es la LOGGING. La configuración utiliza el formato dictConfig y extiende la configuración de registro por defecto: definición de configuración de registro por defecto.
Consulte configurando el registro para una explicación de cómo se combinan sus ajustes personalizados con los valores predeterminados de Django.
Consulte la documentación del módulo de registro de Python <python:logging.config> para detalles sobre otras formas de configurar el registro. Para simplificar, esta documentación solo considerará la configuración a través de la configuración LOGGING.
Al configurar el registro, tiene sentido:
LOGGING¶En su archivo settings.py:
LOGGING = {
"version": 1, # the dictConfig format version
"disable_existing_loggers": False, # retain the default loggers
}
Mantener y extender la configuración de registro por defecto casi siempre tiene sentido, estableciendo disable_existing_loggers en False.
Este ejemplo configura un solo manejador llamado file, que utiliza el FileHandler de Python para guardar registros del nivel DEBUG y superior en el archivo general.log (en la raíz del proyecto):
LOGGING = {
# ...
"handlers": {
"file": {
"class": "logging.FileHandler",
"filename": "general.log",
},
},
}
Las clases de manejadores diferentes toman opciones de configuración diferentes. Para obtener más información sobre las clases de manejadores disponibles, consulte el AdminEmailHandler proporcionado por Django y las diversas clases de manejadores <logging.handlers> proporcionadas por Python.
Los niveles de registro también se pueden establecer en los manejadores (por defecto, aceptan mensajes de registro de todos los niveles). Utilizando el ejemplo anterior, agregar:
{
"class": "logging.FileHandler",
"filename": "general.log",
"level": "DEBUG",
}
definiría una configuración de manejador que solo acepte registros del nivel DEBUG y superior.
Para enviar registros a este manejador, configura un mapeo de registradores para utilizarlo por ejemplo:
LOGGING = {
# ...
"loggers": {
"": {
"level": "DEBUG",
"handlers": ["file"],
},
},
}
El nombre del mapeo determina qué registros de registro procesará. Esta configuración ('') es sin nombre. Esto significa que procesará registros de todos los registradores (consulte Utiliza nombres de loggers a continuación sobre cómo utilizar el nombre del mapeo para determinar los registradores para los cuales procesará registros).
Lo enviará mensajes de niveles DEBUG y superior al manejador llamado file.
Los loggers pueden enviar mensajes a múltiples manejadores, por lo que la relación entre los loggers y los manejadores es muchos-a-muchos.
Si ejecutas:
logger.debug("Attempting to connect to API")
en tu código, encontrarás ese mensaje en el archivo general.log en la raíz del proyecto.
Por defecto, la salida final de los registros contiene solo la parte de mensaje de cada registro de log. Utiliza un formateador si deseas incluir datos adicionales. Primero define tus formateadores - este ejemplo define formateadores llamados verbose y simple:
LOGGING = {
# ...
"formatters": {
"verbose": {
"format": "{name} {levelname} {asctime} {module} {process:d} {thread:d} {message}",
"style": "{",
},
"simple": {
"format": "{levelname} {message}",
"style": "{",
},
},
}
La palabra clave style permite especificar { para str.format() o $ para string.Template de formato; el valor por defecto es $.
Consulte atributos del registro de log para los atributos LogRecord que puedes incluir.
Para aplicar un formateador a un manejador, agrega una entrada formatter al diccionario del manejador haciendo referencia al formateador por nombre, por ejemplo:
"handlers": {
"file": {
"class": "logging.FileHandler",
"filename": "general.log",
"formatter": "verbose",
},
}
La configuración de registro sin nombre '' captura registros de cualquier aplicación Python. Una configuración de registro con nombre capturará solo registros de los loggers con nombres que coincidan.
El namespace de una instancia de logger se define utilizando getLogger(). Por ejemplo en views.py de my_app:
logger = logging.getLogger(__name__)
creará un logger en el namespace my_app.views. __name__ permite organizar mensajes de registro según su origen dentro de las aplicaciones de tu proyecto automáticamente. También garantiza que no experimentarás colisiones de nombres.
Una mapeación de loggers llamada my_app.views capturará registros de este logger:
LOGGING = {
# ...
"loggers": {
"my_app.views": {...},
},
}
Una mapeación de loggers llamada my_app será más permissive, capturando registros de los loggers en cualquier lugar del namespace my_app (incluyendo my_app.views, my_app.utils, y así sucesivamente):
LOGGING = {
# ...
"loggers": {
"my_app": {...},
},
}
También puedes definir el namespace de los loggers explícitamente:
logger = logging.getLogger("project.payment")
y configurar las mapeaciones de loggers en consecuencia.
El nombre de los loggers es hierárquico. my_app es el padre de my_app.views, que a su vez es el padre de my_app.views.private. A menos que se especifique lo contrario, las mapeaciones de loggers propagarán los registros que procesan a sus padres - un registro de un logger en el namespace my_app.views.private será gestionado por una mapeación para tanto my_app como my_app.views.
Para gestionar este comportamiento, establece la clave de propagación en las mapeaciones que definas:
LOGGING = {
# ...
"loggers": {
"my_app": {
# ...
},
"my_app.views": {
# ...
},
"my_app.views.private": {
# ...
"propagate": False,
},
},
}
propagate se establece en True. En este ejemplo, los logs de my_app.views.private no serán gestionados por el padre, pero los logs de my_app.views sí.
El registro es más útil cuando contiene la mayor cantidad de información posible, pero no la información que no necesitas - y cuánta necesidad tienes depende de lo que estás haciendo. Cuando estás depurando, necesitas un nivel de información que sería excesivo y poco útil si tuviera que manejarlo en producción.
Puedes configurar el registro para proporcionarte el nivel de detalle que necesitas cuando lo necesites. En lugar de cambiar manualmente la configuración para lograr esto, una mejor forma es aplicar la configuración automáticamente según el entorno.
Por ejemplo, podrías establecer una variable de entorno DJANGO_LOG_LEVEL adecuadamente en tus entornos de desarrollo y staging, y aprovecharla en un mapeo de registrador así:
"level": os.getenv("DJANGO_LOG_LEVEL", "WARNING")
- de modo que a menos que el entorno especifique un nivel de registro más bajo, esta configuración solo enviará registros de severidad WARNING y superior a su manejador.
Otras opciones en la configuración (como la opción level o formatter del manejador) se pueden gestionar de manera similar.
may 31, 2026