O módulo logging: adeus, print

Por que não usar print em produção

O print é excelente para explorar uma ideia no Playground ou depurar rápido. Para um programa que roda de verdade, ele é fraco. Todo print sai igual, sem indicar se aquilo é um detalhe de depuração ou um erro grave. Não dá para desligar os prints de depuração sem sair apagando linhas. Tudo vai para a mesma saída, sem carimbo de hora, sem o nome de quem registrou, sem para onde mandar. E, para silenciar ou redirecionar, você teria que editar o código. O logging resolve tudo isso de forma configurável.

A ideia central do logging é separar duas decisões que o print mistura. Uma é o que registrar, que fica no seu código, espalhado onde os eventos acontecem. A outra é o que ver e para onde mandar, que fica na configuração, num só lugar. Assim você instrumenta o código uma vez, com mensagens em níveis apropriados, e depois decide, sem editar nada, se quer ver só os erros em produção ou todo o detalhe de depuração enquanto investiga um problema.

Níveis e o logger nomeado

O logging tem cinco níveis de severidade, do menos ao mais grave: DEBUG, para detalhes finos de diagnóstico; INFO, para o curso normal dos eventos; WARNING, para algo inesperado que não impediu o programa; ERROR, para uma falha que atrapalhou uma operação; e CRITICAL, para um problema grave que ameaça o programa inteiro. Você registra cada mensagem no nível certo, e configura o mínimo que quer ver. Definir o nível em WARNING, por exemplo, esconde DEBUG e INFO e mostra o resto.

import logging

# Obtenha um logger nomeado por modulo, nunca o logger raiz.
logger = logging.getLogger(__name__)

def processar(valor):
    logger.debug("iniciando com valor=%s", valor)
    if valor < 0:
        logger.warning("valor negativo recebido: %s", valor)
    try:
        return 100 / valor
    except ZeroDivisionError:
        logger.error("divisao por zero para valor=%s", valor)
        return None

getLogger(__name__) dá um logger por módulo; cada evento sai no nível certo.

Handlers, formatters e exceções

Onde e como o log aparece é papel dos handlers e formatters, e essa é a parte da configuração, feita uma vez, perto do início da aplicação. Um handler define o destino: o console, um arquivo, um serviço remoto. Um formatter define o formato de cada linha: hora, nível, nome do logger e mensagem. Para começar, logging.basicConfig monta um handler de console com um formato razoável em uma linha, o suficiente para muitos programas. Aplicações maiores configuram handlers com mais cuidado, inclusive vários ao mesmo tempo.

import logging

# Configuracao feita uma vez, no ponto de entrada da aplicacao.
logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s %(levelname)s %(name)s: %(message)s",
)

logger = logging.getLogger("app.pagamentos")

def cobrar(valor):
    try:
        if valor <= 0:
            raise ValueError("valor deve ser positivo")
        logger.info("cobranca de R$ %s realizada", valor)
    except ValueError:
        # exception() registra em ERROR com o rastreamento completo.
        logger.exception("falha ao cobrar")

cobrar(0)

basicConfig define nível e formato; logger.exception grava o rastreamento inteiro.

O destaque prático é o logger.exception. Chamado dentro de um bloco except, ele registra a mensagem no nível ERROR e anexa o rastreamento completo da exceção, sem você precisar montá-lo à mão. É a forma correta de registrar uma falha: a mensagem diz o que estava acontecendo, e o rastreamento diz exatamente onde e por quê. Comparado a um print do erro, que perde o rastro e o contexto, o logging entrega um registro que uma pessoa consegue investigar horas depois, em produção, sem estar na frente do código.