---
title: "Logging"
version: 4.0
locale: pt-br
source: https://docs.djangoproject.com/pt-br/4.0/ref/logging/
canonical: https://djangodocs.dev/pt-br/4.0/ref/logging/
---
# Logging

> **See also**
>
> - [How to configure and use logging](/pt-br/4.0/howto/logging/#logging-how-to)
> - [Django logging overview](/pt-br/4.0/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.0/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.0/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.0/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.0/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.0.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.0/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.0/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.0/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`: O objeto da requisição que gerou a mensagem de log.

#### `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.

Nesse logger não estão incluídos initializações a level de framework (ex `SET TIMEZONE`) ou consultas relacionadas ao gerenciamento de transações (ex `BEGIN`, `COMMIT`, e `ROLLBACK`). Ative o log de consultas no seu banco de dados se você desejar ver todas as consultas de banco.

> **Changed in Django 4.0**
>
> The database `alias` was added to log messages.

#### `django.security.*`

Os loggers de segurança irão receber mensagens em qualquer ocorrência de [`SuspiciousOperation`](/pt-br/4.0/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.0/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:

```
'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.0/ref/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.0/topics/migrations/). Note que ele não irá logar as consultas executadas pela classe [`RunPython`](/pt-br/4.0/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.0/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.0/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.0/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.0/topics/logging/#logging-security-implications) when using the `AdminEmailHandler`.

By setting the `email_backend` argument of `AdminEmailHandler`, the
[email backend](/pt-br/4.0/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.0/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.0/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:

```
'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.0/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.0/ref/settings/#std-setting-DEBUG) is `False`:

```
'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.0/ref/settings/#std-setting-DEBUG) é `True`.