Pular para o conteúdo principal
O LogBrew é uma plataforma de observabilidade para desenvolvedores e agentes de programação, com um plano gratuito generoso e sem cartão de crédito. Este guia cobre o logging em Python com o módulo padrão logging, os 5 níveis de log do Python, o tratamento de erros em Python e os tipos de erro mais comuns do Python. As últimas seções enviam os mesmos logs e crashes para o LogBrew com o logbrew-sdk 0.1.29. Cada exemplo rodou no Python 3.13, e cada bloco de saída mostra a saída real. Para um app Flask, use Logging no Flask. Esse guia adiciona traces de requisição à mesma configuração de logging.

Escreva seu primeiro log em Python

Salve este arquivo como app.py. Chame logging.basicConfig() uma única vez, no ponto de entrada do programa. Obtenha um logger com nome em cada módulo.
Execute python3 app.py. A saída vai para o erro padrão.
O registro debug não aparece, porque o nível é INFO. logger.exception() registra no nível ERROR e adiciona o traceback. Chame esse método só dentro de um bloco except. Passe os valores como argumentos, como em "payment retry %d of %d", 2, 3. O Python monta a mensagem só quando um handler aceita o registro. O modelo da mensagem continua igual a cada nova tentativa, então você pode pesquisar por ele.

Níveis de log do Python

Um logger envia um registro só quando o nível do registro é igual ou maior que o nível do logger. Um handler pode definir um segundo nível, mais alto. O logger raiz começa em WARNING. Um logger novo tem o nível NOTSET (0) e usa o nível do logger pai. Use INFO em produção e DEBUG só em desenvolvimento ou para um diagnóstico curto.
A primeira linha mostra os registros de debug de um módulo. A segunda linha remove o ruído de uma biblioteca.

Loggers, handlers e formatters

  • Um logger recebe a chamada. Use logging.getLogger(__name__) para que o nome do logger siga o caminho do módulo.
  • Um handler envia os registros para um destino, como o console, um arquivo ou o LogBrew.
  • Um formatter transforma um registro em texto.
Uma biblioteca não deve configurar o logging. Ela só adiciona um logging.NullHandler() ao próprio logger. A aplicação configura os handlers e os níveis uma única vez. Para uma configuração grande, use logging.config.dictConfig().

Tratamento de erros em Python

Capture a exceção mais específica que você consegue tratar. Use else para o código que só roda em caso de sucesso. Use finally para o código que sempre roda. Use raise ... from error para manter a causa original. Salve este arquivo como orders.py.
A saída mostra as duas exceções da cadeia de exceções.
Siga estas regras para cada exceção.
  • Registre uma exceção uma única vez, onde você a trata. Não registre e relance a exceção em cada camada, porque cada camada adiciona um registro duplicado.
  • Não escreva except Exception: pass. Se você ignorar um erro, registre o erro no nível WARNING ou acima, com o motivo.
  • Capture Exception, não BaseException. BaseException também captura KeyboardInterrupt e SystemExit, que param o programa de propósito.
  • Defina suas próprias classes de exceção para os erros que quem chama o código precisa tratar, como faz OrderError.

Informe mais de um erro

O Python 3.11 e versões mais recentes podem lançar um ExceptionGroup. Use esse recurso quando uma verificação encontrar mais de um erro. Trate cada tipo com except*.

Tipos de erro comuns do Python

Todos os erros nativos que um programa pode tratar herdam de Exception. Esta tabela lista os erros do Python que você vê com mais frequência e a primeira verificação para cada um. KeyboardInterrupt e SystemExit herdam de BaseException, não de Exception. Eles não são erros no seu código.

Envie logs do Python para o LogBrew

LogBrewLoggingHandler é um handler de logging padrão. Ele envia ao LogBrew cada registro que aceita. O handler do console continua igual.
1

Crie uma chave de projeto

Entre na conta com a CLI. Crie um projeto e guarde a chave de ingestão dele em um arquivo que só o dono pode acessar.
A CLI não mostra a chave. Em produção, use o gerenciador de segredos da sua plataforma.
2

Instale o SDK

Ative o ambiente virtual da aplicação. Depois instale o pacote. Ele exige Python 3.10 ou mais recente.
3

Defina a chave e a identidade da implantação

O cliente adiciona o serviço, o ambiente e a versão a cada sinal.
4

Adicione o handler

Salve este arquivo como worker.py. Chame logging.basicConfig() antes de criar o cliente. O cliente adiciona um handler ao logger raiz, e basicConfig() não faz nada quando o logger raiz já tem um handler.
HttpTransport() envia os sinais em segundo plano, 1 segundo depois do primeiro sinal ou ao chegar a 50 sinais. client.shutdown() envia os sinais restantes e fecha o cliente.
5

Execute o programa

A saída do console não muda. O LogBrew recebe 1 log para cada registro. Este é o primeiro sinal, sem o contexto de execução compartilhado.
Os valores primitivos de extra={...} viram metadados. O segundo sinal tem exceptionName KeyError e exceptionMessage 'seats'. Para enviar o texto completo do traceback, crie o handler com include_exception_text=True.
6

Leia os logs de volta

Uma leitura com resultados mostra que o LogBrew armazenou os logs. Para ler a partir de CI ou de um agente de programação, use uma chave de leitura do projeto. Veja Verificar a configuração.

Escolha quais registros vão para o LogBrew

Dê ao handler um nível próprio para enviar menos registros. O console continua recebendo INFO e acima.
Os níveis do Python viram níveis do LogBrew. O nome e o número originais do nível ficam nos metadados.

Informe crashes do Python como problemas

install_process_error_capture(client) informa exceções não capturadas em scripts, workers, código de inicialização e threads. Cada crash vira 1 problema com o tipo de exceção, a mensagem, os frames da pilha e as causas encadeadas. O Python continua mostrando o traceback e encerra como antes. Salve este arquivo como startup.py e execute-o.
O LogBrew recebe um problema com o título FileNotFoundError, o nível critical e o mecanismo python.excepthook. Os frames dele contêm o nome do arquivo, a linha e a função, mas não o caminho completo. Um crash em uma thread tem o nível error. Antes de o Python encerrar, o SDK espera no máximo 2 segundos pela entrega.
O problema inclui a mensagem da exceção. Não coloque credenciais nem dados pessoais em mensagens de exceção ou de log. Veja Controlar dados capturados.

Solução de problemas

Para apps web, veja Logging no Flask. Para escolher um formato de log, veja Logging estruturado. Para outros runtimes, veja Integração do SDK.