# documentação Django 4.0.8.dev20220803071047

# Logging

Ver também

- How to configure and use logging
- Django logging overview

Django’s logging module extends Python’s builtin `logging`.

Logging is configured as part of the general Django `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.

### Default logging conditions

The full set of default logging conditions are:

Quando `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` é `False`:

- The `django` logger sends messages in the `django` hierarchy (except `django.server`) with `ERROR` or `CRITICAL` level to `AdminEmailHandler`.

Independently of the value of `DEBUG`:

- The django.server logger sends messages at the `INFO` level or higher to the console.

All loggers except django.server 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:

    {
        '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 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. 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`. 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` 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`, 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.

#### `django.db.backends.schema`

Loga as consultas SQL que são executadas durante mudanças de esquema no banco de dados pelo migrations framework. Note que ele não irá logar as consultas executadas pela classe `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.

### Manipuladores

Django provides one log handler in addition to `those provided by the Python logging module`.

class `AdminEmailHandler`(include_html=False, email_backend=None, reporter_class=None)

  This handler sends an email to the site `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`; 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` 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 when using the `AdminEmailHandler`.

  By setting the `email_backend` argument of `AdminEmailHandler`, the email backend 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` 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` 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` (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` configuration to ensure that the `AdminEmailHandler` only sends error emails to admins when `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`, exceto pelo fato de que os registros são passados adiante somente quando `DEBUG` é `True`.