--- title: "Logging" version: 4.2 locale: pt-br source: https://docs.djangoproject.com/pt-br/4.2/ref/logging/ canonical: https://djangodocs.dev/pt-br/4.2/ref/logging/ --- # Logging > **See also** > > - [How to configure and use logging](/pt-br/4.2/howto/logging/#logging-how-to) > - [Django logging overview](/pt-br/4.2/topics/logging/#logging-explanation) Django’s logging module extends Python’s builtin [`logging`](https://docs.python.org/3/library/logging.html#module-logging). Logging is configured as part of the general Django [`django.setup()`](/pt-br/4.2/ref/applications/#django.setup) function, so it’s always available unless explicitly disabled. ## A configuração default de log do Django By default, Django uses Python’s [logging.config.dictConfig format](https://docs.python.org/3/library/logging.config.html#logging-config-dictschema). ### Default logging conditions The full set of default logging conditions are: Quando [`DEBUG`](/pt-br/4.2/ref/settings/#std-setting-DEBUG) é `True`: - The `django` logger sends messages in the `django` hierarchy (except `django.server`) at the `INFO` level or higher to the console. Quando [`DEBUG`](/pt-br/4.2/ref/settings/#std-setting-DEBUG) é `False`: - The `django` logger sends messages in the `django` hierarchy (except `django.server`) with `ERROR` or `CRITICAL` level to [`AdminEmailHandler`](#django.utils.log.AdminEmailHandler). Independently of the value of [`DEBUG`](/pt-br/4.2/ref/settings/#std-setting-DEBUG): - The [django.server](#django-server-logger) logger sends messages at the `INFO` level or higher to the console. All loggers except [django.server](#django-server-logger) propagate logging to their parents, up to the root `django` logger. The `console` and `mail_admins` handlers are attached to the root logger to provide the behavior described above. Python’s own defaults send records of level `WARNING` and higher to the console. ### Default logging definition Django’s default logging configuration inherits Python’s defaults. It’s available as `django.utils.log.DEFAULT_LOGGING` and defined in [django/utils/log.py](https://github.com/django/django/blob/stable/4.2.x/django/utils/log.py): ``` { "version": 1, "disable_existing_loggers": False, "filters": { "require_debug_false": { "()": "django.utils.log.RequireDebugFalse", }, "require_debug_true": { "()": "django.utils.log.RequireDebugTrue", }, }, "formatters": { "django.server": { "()": "django.utils.log.ServerFormatter", "format": "[{server_time}] {message}", "style": "{", } }, "handlers": { "console": { "level": "INFO", "filters": ["require_debug_true"], "class": "logging.StreamHandler", }, "django.server": { "level": "INFO", "class": "logging.StreamHandler", "formatter": "django.server", }, "mail_admins": { "level": "ERROR", "filters": ["require_debug_false"], "class": "django.utils.log.AdminEmailHandler", }, }, "loggers": { "django": { "handlers": ["console", "mail_admins"], "level": "INFO", }, "django.server": { "handlers": ["django.server"], "level": "INFO", "propagate": False, }, }, } ``` See [Configuring logging](/pt-br/4.2/topics/logging/#configuring-logging) on how to complement or replace this default logging configuration. ## Django logging extensions Django provides a number of utilities to handle the particular requirements of logging in a web server environment. ### Loggers O Django fornece vários loggers embutidos. #### `django` The parent logger for messages in the `django` [named logger hierarchy](/pt-br/4.2/howto/logging/#naming-loggers-hierarchy). Django does not post messages using this name. Instead, it uses one of the loggers below. #### `django.request` Log messages related to the handling of requests. 5XX responses are raised as `ERROR` messages; 4XX responses are raised as `WARNING` messages. Requests that are logged to the `django.security` logger aren’t logged to `django.request`. Mensagens para esse logger possuem o seguinte contexto adicional: - `status_code`: o código da resposta HTTP associado a requisição. - `request`: O objeto da requisição que gerou a mensagem de log. #### `django.server` Mensagens de log relacionadas com a manipulação de requisições recebidas pelo comando [`runserver`](/pt-br/4.2/ref/django-admin/#django-admin-runserver). Respostas HTTP 5XX são logadas como mensagens do tipo `ERROR`, respostas HTTP 4XX são logadas como mensagens do tipo `WARNING`, e todo o resto é logado como `INFO`. Mensagens para esse logger possuem o seguinte contexto adicional: - `status_code`: o código da resposta HTTP associado a requisição. - `request`: The request object (a [`socket.socket`](https://docs.python.org/3/library/socket.html#socket.socket)) that generated the logging message. #### `django.template` Mensagens de log relacionadas a renderização de templates. - Variáveis de contexto esquecidas são logadas como mensagens do tipo `DEBUG`. #### `django.db.backends` Mensagens relacionadas a interação de código com o banco de dados. Por exemplo, cada comando SQL executado por uma requisição é logada no level `DEBUG` para esse logger. Mensagens para esse logger possuem o seguinte contexto adicional: - `duration`: O tempo tomado para executar o comando SQL. - `sql`: O comando SQL que foi executado. - `params`: Os parâmetros que foram usados na chamada SQL. - `alias`: The alias of the database used in the SQL call. Por questões de performance, o log de SQL só é ativado quando `settings.DEBUG` é configurado como `True`, independentemente do level de log ou dos handlers que estão instalados. This logging does not include framework-level initialization (e.g. `SET TIMEZONE`). Turn on query logging in your database if you wish to view all database queries. > **Changed in Django 4.2** > > Support for logging transaction management queries (`BEGIN`, `COMMIT`, > and `ROLLBACK`) was added. #### `django.contrib.auth` > **New in Django 4.2.16** Log messages related to [django.contrib.auth](/pt-br/4.2/ref/contrib/auth/), particularly `ERROR` messages are generated when a [`PasswordResetForm`](/pt-br/4.2/topics/auth/default/#django.contrib.auth.forms.PasswordResetForm) is successfully submitted but the password reset email cannot be delivered due to a mail sending exception. #### `django.security.*` Os loggers de segurança irão receber mensagens em qualquer ocorrência de [`SuspiciousOperation`](/pt-br/4.2/ref/exceptions/#django.core.exceptions.SuspiciousOperation) e outros erros relacionados a segurança. Existe um sub-logger para cada subtipo de erro de segurança, incluindo todos do tipo `SuspiciousOperation`s. O level de log depende de onde a exceção for manipulada. A maioria das ocorrências serão logadas como um aviso. enquanto que qualquer `SuspiciousOperation`s que alcançar o handler WSGI será logada como um erro. Por exemplo, quando um cabeçalho HTTP `Host` é incluído em uma requisição de um cliente que não for encontrado em [`ALLOWED_HOSTS`](/pt-br/4.2/ref/settings/#std-setting-ALLOWED_HOSTS), Django irá retornar uma resposta 400, e uma mensagem de erro será logada para o logger `django.security.DisallowedHost`. Esses eventos de log irão alcançar o logger `django` por padrão, que irá enviar emails de eventos de erro para os administradores quando `DEBUG=False`. Requisições resultando em uma resposta 400 devido a uma `SuspiciousOperation` não serão logadas no logger `django.request`, mas somente para o logger `django.security`. To silence a particular type of `SuspiciousOperation`, you can override that specific logger following this example: ``` LOGGING = { # ... "handlers": { "null": { "class": "logging.NullHandler", }, }, "loggers": { "django.security.DisallowedHost": { "handlers": ["null"], "propagate": False, }, }, # ... } ``` Outros loggers `django.security` não baseados em `SuspiciousOperation` são: - `django.security.csrf`: Para [falhas CSRF](/pt-br/4.2/howto/csrf/#csrf-rejected-requests). #### `django.db.backends.schema` Loga as consultas SQL que são executadas durante mudanças de esquema no banco de dados pelo [migrations framework](/pt-br/4.2/topics/migrations/). Note que ele não irá logar as consultas executadas pela classe [`RunPython`](/pt-br/4.2/ref/migration-operations/#django.db.migrations.operations.RunPython). As mensagens para esse logger possuem `params` e `sql` em seu contexto extra (mas ao contrário de `django.db.backends`, não possui `duration`). Os valores tem o mesmo significado como explicado em [django.db.backends](#django-db-logger). ### Manipuladores Django provides one log handler in addition to [`those provided by the Python logging module`](https://docs.python.org/3/library/logging.handlers.html#module-logging.handlers). #### `class AdminEmailHandler(include_html=False, email_backend=None, reporter_class=None)` This handler sends an email to the site [`ADMINS`](/pt-br/4.2/ref/settings/#std-setting-ADMINS) for each log message it receives. Se o registro de log contém um atributo `request`, todos os detalhes da requisição serão incluídos no email. O assunto do email irá incluir a fase “internal IP” se o endereço IP do cliente foi informado em [`INTERNAL_IPS`](/pt-br/4.2/ref/settings/#std-setting-INTERNAL_IPS); Caso contrário, ele irá incluir o “EXTERNAL IP”. Se o registro de log contiver infromações de rastreamento de pilha, o rastreamento de pilha será incluído no email. The `include_html` argument of `AdminEmailHandler` is used to control whether the traceback email includes an HTML attachment containing the full content of the debug web page that would have been produced if [`DEBUG`](/pt-br/4.2/ref/settings/#std-setting-DEBUG) were `True`. To set this value in your configuration, include it in the handler definition for `django.utils.log.AdminEmailHandler`, like this: ``` "handlers": { "mail_admins": { "level": "ERROR", "class": "django.utils.log.AdminEmailHandler", "include_html": True, }, } ``` Be aware of the [security implications of logging](/pt-br/4.2/topics/logging/#logging-security-implications) when using the `AdminEmailHandler`. By setting the `email_backend` argument of `AdminEmailHandler`, the [email backend](/pt-br/4.2/topics/email/#topic-email-backends) that is being used by the handler can be overridden, like this: ``` "handlers": { "mail_admins": { "level": "ERROR", "class": "django.utils.log.AdminEmailHandler", "email_backend": "django.core.mail.backends.filebased.EmailBackend", }, } ``` Por padrão, uma instância do backend de email especificado em [`EMAIL_BACKEND`](/pt-br/4.2/ref/settings/#std-setting-EMAIL_BACKEND) será usado. The `reporter_class` argument of `AdminEmailHandler` allows providing an `django.views.debug.ExceptionReporter` subclass to customize the traceback text sent in the email body. You provide a string import path to the class you wish to use, like this: ``` "handlers": { "mail_admins": { "level": "ERROR", "class": "django.utils.log.AdminEmailHandler", "include_html": True, "reporter_class": "somepackage.error_reporter.CustomErrorReporter", }, } ``` #### `send_mail(subject, message, *args, **kwargs)` Envia emails para os usuários administradores. Para customizar esse comportamento, você pode fazer uma subclasse de [`AdminEmailHandler`](#django.utils.log.AdminEmailHandler) e sobrescrever esse método. ### Filtros Django provides some log filters in addition to those provided by the Python logging module. #### `class CallbackFilter(callback)` Esse filter aceita uma função de callback (que deve aceitar um único argumento, o registro a ser logado), e chama essa função para cada registro que passa pelo filter. A manipulação desse registro não será continuada caso a função de callback retorne False. Por exemplo, para filtrar para fora exceções do tipo [`UnreadablePostError`](/pt-br/4.2/ref/exceptions/#django.http.UnreadablePostError) (levantadas quando o usuário cancela um upload) de emails destinadoas a administradores, você teria que criar uma função de filtro: ``` from django.http import UnreadablePostError def skip_unreadable_post(record): if record.exc_info: exc_type, exc_value = record.exc_info[:2] if isinstance(exc_value, UnreadablePostError): return False return True ``` and then add it to your logging config: ``` LOGGING = { # ... "filters": { "skip_unreadable_posts": { "()": "django.utils.log.CallbackFilter", "callback": skip_unreadable_post, }, }, "handlers": { "mail_admins": { "level": "ERROR", "filters": ["skip_unreadable_posts"], "class": "django.utils.log.AdminEmailHandler", }, }, # ... } ``` #### `class RequireDebugFalse` Esse filtro irá passar adiante registros de logs somente quando settings.DEBUG for False. This filter is used as follows in the default [`LOGGING`](/pt-br/4.2/ref/settings/#std-setting-LOGGING) configuration to ensure that the [`AdminEmailHandler`](#django.utils.log.AdminEmailHandler) only sends error emails to admins when [`DEBUG`](/pt-br/4.2/ref/settings/#std-setting-DEBUG) is `False`: ``` LOGGING = { # ... "filters": { "require_debug_false": { "()": "django.utils.log.RequireDebugFalse", }, }, "handlers": { "mail_admins": { "level": "ERROR", "filters": ["require_debug_false"], "class": "django.utils.log.AdminEmailHandler", }, }, # ... } ``` #### `class RequireDebugTrue` Esse filtro é similar a [`RequireDebugFalse`](#django.utils.log.RequireDebugFalse), exceto pelo fato de que os registros são passados adiante somente quando [`DEBUG`](/pt-br/4.2/ref/settings/#std-setting-DEBUG) é `True`.