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 comoapp.py. Chame logging.basicConfig() uma única vez, no ponto de entrada do programa. Obtenha um logger com nome em cada módulo.
python3 app.py. A saída vai para o erro padrão.
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.
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.
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. Useelse 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.
- 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ívelWARNINGou acima, com o motivo. - Capture
Exception, nãoBaseException.BaseExceptiontambém capturaKeyboardInterrupteSystemExit, 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 umExceptionGroup. 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 deException. 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
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
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
Escolha quais registros vão para o LogBrew
Dê ao handler um nível próprio para enviar menos registros. O console continua recebendoINFO e acima.
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.
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.
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.
