Logging¶

O elenco de jogadores¶

A configuração de logs do Python é composta por quatro partes:

• Loggers
• Manipuladores
• Filtros
• Formatadores

Nomeando loggers¶

A chamada logging.getLogger() obtém (cria, se necessário) uma instância de um logger. A instância do logger é identificada por um nome. Esse nome é usado para identificar o logger para propósitos de configuração.

Por convenção, o nome do logger é __name__, o nome do módulo python que contém o logger. Isso permite que você filtre e manipule chamadas de log para cada módulo em específico. Contudo, se você tiver alguma outra forma de organizar as suas mensagens de log, você pode fornecer qualquer nome separado por pontos para identificar o seu logger:

# Get an instance of a specific named logger
logger = logging.getLogger('project.interesting.stuff')

Os caminhos com pontos do nome de um logger definem a hierarquia. O logger project.interesting é considerado como o pai do logger project.interesting.stuff; o logger project é o pai do logger project.interesting.

Por que a hierarquia é importante? Bem, porque os loggers podem ser configurados para propagar as chamadas de log de seus pais. Desta forma, você pode definir um conjunto único de handlers na raiz de uma árvore de loggers, e capturar todas as chamadas de log dentro da subárvore de loggers. Se um handler é definido no namespace project ele irá obter todas as mensagens de log emitidas nos loggers project.interesting e project.interesting.stuff.

A propagação pode ser controlada para cada logger em especifico. Se você não quiser que um logger em particular propague para os seus pais, você pode desativar esse comportamento.

Fazendo chamadas de log¶

Cada instância de um logger contém um método de entrada para cada um dos leveis padrão de log:

• logger.debug()
• logger.info()
• logger.warning()
• logger.error()
• logger.critical()

Existem ainda outras duas chamadas de log disponíveis:

• logger.log(): Emite manualmente uma mensagem de log com um level de log em específico.
• logger.exception(): Cria uma mensagem de log usando o level ERROR envolvendo a stack frame, ou estrutura de pilha em português, da exceção atual.

Exemplos¶

A documentação completa para o formato dictConfig é a melhor fonte de informação sobre configuração de dicionários de log. Contudo, para te dar uma ideia das possibilidades, aqui vão vários exemplos.

Primeiro, aqui vai uma configuração simples que grava tudo que vier do logger django para um arquivo local:

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,
        },
    },
}

Se você usar esse exemplo, certifique-se de alterar o caminho 'filename' para um local com permissões de escrita pelo usuário que estiver rodando a aplicação Django.

Segundo, aqui vai um exemplo de como fazer o sistema de logs fazer prints de logs do Django no console. Isso pode ser útil durante o desenvolvimento local.

Por padrão, essa configuração só envia mensagens do level INFO ou maior para o console (a mesma coisa vale para a configuração padrão de logs do Django, sendo a única exceção que a configuração padrão só exibe registros de logs quando DEBUG=True).

import os

LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'handlers': {
        'console': {
            'class': 'logging.StreamHandler',
        },
    },
    'loggers': {
        'django': {
            'handlers': ['console'],
            'level': os.getenv('DJANGO_LOG_LEVEL', 'INFO'),
        },
    },
}

Finalmente, aqui vai um exemplo de uma configuração bastante complexa de log:

LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'formatters': {
        'verbose': {
            'format': '%(levelname)s %(asctime)s %(module)s %(process)d %(thread)d %(message)s'
        },
        'simple': {
            'format': '%(levelname)s %(message)s'
        },
    },
    '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']
        }
    }
}

Essa configuração de log faz o seguinte:

• Identifica a configuração como sendo da ‘versão 1 do formato dictConfig’. Atualmente, essa é a única versão disponível.

• Define dois formatters:

  • simple, que só exibe o nome do level de log (por exemplo DEBUG) e a mensagem de log.

    A string format é uma string normal de formatação Python descrevendo os detalhes que devem ser exibidos em cada linha de log. A lista completa de detalhes que podem ser exibidos pode ser encontrada em Formatter Objects.

  • verbose, que exibe o nome do level de log, a mensagem de log, e também o tempo, o processo, a thread e o módulo que gerou a mensagem de log.

• Define dois filters:

  • project.logging.SpecialFilter, utilizando o alias special. Se esse filtro necessitar de argumentos adicionais, eles podem ser fornecidos como chaves adicionais no dicionário de configuração do filter. Nesse caso, o argumento foo será dado para o valor de bar na instanciação de SpecialFilter.
  • django.utils.log.RequireDebugTrue, que transmite registros quando DEBUG é True.

• Define dois handlers:

  • console, a StreamHandler, which prints any INFO (or higher) message to sys.stderr. This handler uses the simple output format.
  • mail_admins, an AdminEmailHandler, which emails any ERROR (or higher) message to the site ADMINS. This handler uses the special filter.

• Configura três loggers:

  • django, que transmite todas as mensagens para o handler console.
  • django.request, que transmite todas as mensagens do tipo ERROR para o handler mail_admins. Adicionalmente, esse logger é marcado para não propagar mensagens. Isso significa que as mensagens de log gravadas em django.request não serão manipuladas pelo logger django.
  • myproject.custom, que transmite todas as mensagens do level INFO ou maior e que também transmite o filtro special para dois handlers – o console, e o mail_admins. Isso significa que todas as mensagens de level INFO (ou maiores) serão exibidas no console; mensagens ERROR e CRITICAL também serão emitidas via email.

Configurações customizadas de log¶

Se você não quer usar o formato dictConfig do Python para configurar o seu logger, você pode especificar o seu próprio esquema de configuração.

A configuração LOGGING_CONFIG define o callable que será usado para configurar os loggers do Django. Por padrão, ele aponta para a função logging.config.dictConfig() do Python. Contudo, se você quiser usar um processo diferente de configuração, você pode usar qualquer outro callable que recebe um único argumento. O conteúdo de LOGGING será fornecido como sendo o valor do argumento onde o log será configurado.

Desabilitando a configuração de log¶

Se você não quser configurar qualquer tipo de log (ou se você deseja configurar o log manualmente usando sua própria abordagem), você pode definir LOGGING_CONFIG para None. Isso irá desabilitar o processo de configuração para configuração de log padrão do Django. Segue um exemplo de uma configuração que desabilita a configuração de logs do Django e então configura o log manualemente:

LOGGING_CONFIG = None

import logging.config
logging.config.dictConfig(...)

Configurar LOGGING_CONFIG como None significa tão somente que o processo de configuração automática está desabilitado, não os logs em si. Se você desabilitar o processo de configuração, o Django ainda fará chamadas de logs, recorrendo a qualquer comportamento padrão de log que for definido.

Loggers¶

O Django fornece vários loggers embutidos.

'handlers': {
    'null': {
        'class': 'logging.NullHandler',
    },
},
'loggers': {
    'django.security.DisallowedHost': {
        'handlers': ['null'],
        'propagate': False,
    },
},

Manipuladores¶

O Django fornece um handler de log adicional para os já fornecidos pelo módulo de log do Python.

class AdminEmailHandler(include_html=False, email_backend=None)[código fonte]¶

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.

O argumento include_html de AdminEmailHandler é usado para controlar se o email de traceback inclui um anexo HTML contendo todo o conteúdo da página Web de debug que seria reproduzida se DEBUG fosse True. Para ativar esse valor em sua configuração, inclua ela na definição do handler para django.utils.log.AdminEmailHandler, confome segue:

'handlers': {
    'mail_admins': {
        'level': 'ERROR',
        'class': 'django.utils.log.AdminEmailHandler',
        'include_html': True,
    }
},

Note que a versão HTML do email contém um traceback completo, com nomes e valores de variáveis locais em cada level da pilha, além dos valores da sua configuração do Django. Essa informação é potencialmente muito sensível, e você pode não querer enviá-la por email. Considere usar algo como Sentry para obter o melhor dos dois mundos – a rica informação dos tracebacks completos e mais a segurança de não enviar informações por email. Você pode também explicitamente designar certas informações sensíveis para serem filtradas para fora dos relatórios de erro – saiba mais em Filtrando relatórios de erro.

Utilizando o argumento email_backend de AdminEmailHandler, o email backend que está sendo usado pelo handler pode ser sobrescrito, conforme segue:

'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.

send_mail(subject, message, *args, **kwargs)[código fonte]¶

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)[código fonte]¶

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

E então adicioná-la na sua configuração de log:

'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[código fonte]¶

Esse filtro irá passar adiante registros de logs somente quando settings.DEBUG for False.

Esse filtro é usado conforme a seguir na configuração default LOGGING para garantir que a classe AdminEmailHandler somente envie emails de erro para os administradores quando DEBUG é 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[código fonte]¶

Esse filtro é similar a RequireDebugFalse, exceto pelo fato de que os registros são passados adiante somente quando DEBUG é True.