logbrew-flask 0.1.6 ou mais recente. Ele captura spans de requisição e exceções não tratadas. O handler de logging opcional conecta os logs do Python ao trace da requisição. As métricas de duração de requisição também são opcionais.
O pacote exige Python 3.10 ou mais recente e Flask 3.1 ou mais recente.
Use na aplicação uma chave de ingestão de servidor com escopo de projeto. Não use a credencial da conta que autoriza a CLI.
<project_id>, <trace_id> e <issue_id> por IDs do LogBrew. Use um projeto de desenvolvimento para as requisições de teste. Os exemplos de shell usam Bash.
Envie a primeira requisição
1
Crie ou selecione uma chave de projeto
Entre na conta com a CLI. Depois use um projeto novo ou um projeto existente. Não execute os dois exemplos. Para um projeto novo, guarde a chave de ingestão dele em um novo arquivo que só o dono pode acessar:Para um projeto existente, pegue o ID dele em A CLI guarda a chave de ingestão com permissões apenas para o dono. Ela não exibe a chave nem o caminho do arquivo. Em produção, use o gerenciador de segredos da sua plataforma de implantação em vez desse arquivo local.Se uma requisição de criação tiver um resultado incerto, execute exatamente o mesmo comando de novo.
logbrew projects --json. Depois crie uma chave de servidor separada:2
Instale a integração publicada
Crie ou ative o ambiente virtual da aplicação e depois instale o pacote do framework. Ele também instala uma versão compatível do kit de desenvolvimento de software (SDK) principal.
3
Configure a identidade da implantação
Carregue a chave do projeto localmente sem exibi-la. Defina um serviço, um ambiente e uma versão estáveis para que todo sinal tenha um contexto de implantação útil.
init_logbrew() verifica primeiro os argumentos explícitos, depois a configuração da aplicação Flask e, por fim, estas variáveis de ambiente. Se nenhum nome de serviço estiver configurado, ele usa o nome de importação do Flask.4
Inicialize o Flask uma vez
Para uma aplicação nova, salve o exemplo como Chamadas repetidas de
app.py. Adicione o inicializador depois de criar a aplicação Flask. O handler de logging é opcional. Ele permite que os logs da aplicação compartilhem o trace e o span ativos da requisição.init_logbrew(app) retornam a mesma extensão do Flask. Elas não instalam hooks duplicados de requisição nem de exceção. O inicializador não adiciona handlers de logging. Adicione o handler uma única vez ao logger da aplicação.5
Execute uma requisição
Inicie a aplicação e chame a rota em outro terminal. Substitua A entrega roda em um worker em segundo plano e não deixa a resposta esperando.
app no comando se a sua aplicação usar outro nome de módulo.6
Confira as evidências no LogBrew
Leia exatamente o escopo do projeto e da implantação. Procure o trace da requisição de health check e o log correlacionado que o handler de logging do exemplo enviou.Use o ID de trace retornado no comando de investigação com escopo definido:Uma leitura que encontra o sinal confirma que o LogBrew o armazenou. Uma resposta
200 local só prova que o Flask tratou a requisição.Escolha os sinais de que você precisa
O inicializador começa com os traces de requisição e as exceções não tratadas ativados. As métricas de requisição e o encaminhamento dos logs do Python são escolhas separadas.
Comece com os padrões. Adicione as métricas de requisição quando precisar ver a latência. Adicione o handler de logging apenas aos loggers que ajudam numa investigação.
Por padrão, o inicializador tem um transporte HTTP próprio. Ele coloca cada evento em uma fila, e um worker em segundo plano começa a entrega assim que há um evento na fila. A entrega não deixa a resposta esperando. Falhas de transporte não quebram a resposta do Flask.
flush_on_response=True envia os eventos da fila no caminho da resposta. Com essa opção, raise_flush_errors=True lança os erros de entrega. Use as duas opções somente em um diagnóstico controlado.
Controle o conteúdo dos logs
Adicione umLogBrewLoggingHandler ao logger dono das mensagens de que você precisa. O handler não substitui os handlers de console ou de arquivo da aplicação. Ele não altera o Flask nem o módulo de logging do Python. Adicionar o mesmo handler duas vezes duplica os logs. Se a aplicação também usar o logger raiz, confira a propagação antes de anexar um segundo handler.
Um log dentro de uma requisição herda o trace e o span ativos. Um log fora de uma requisição não tem trace de requisição.
O handler envia a mensagem formatada, o nome do logger e o nível do LogBrew. Ele também envia o nome do arquivo de origem, o módulo, a função, a linha e os nomes da thread e do processo, mas não o caminho completo do arquivo. Os valores primitivos de extra={...} viram metadados. Revise esses valores antes de gerar logs em uma requisição feita por usuários.
Os logs DEBUG do Python viram info no LogBrew. WARNING vira warning, e CRITICAL vira critical. O nome e o número originais do nível do Python ficam nos metadados. Para enviar menos logs, dê ao handler um nível próprio, como LogBrewLoggingHandler(logbrew.client, level=logging.WARNING).
O console e o LogBrew podem receber o mesmo log. Por exemplo, configure o console antes de criar a aplicação Flask:
exc_info inclui o tipo e a mensagem da exceção. O texto completo da exceção só é enviado quando o handler tem include_exception_text=True. Isso é separado da captura automática de exceções, que nunca envia a mensagem da exceção. Não coloque credenciais, dados pessoais nem corpos de requisição em mensagens de log ou de exceção.
O que a integração captura
Os nomes dos spans usam o método HTTP e o modelo de rota correspondente. Por exemplo,
/orders/100 e /orders/200 compartilham GET /orders/<int:order_id>. Uma requisição sem rota correspondente usa o rótulo fixo <unmatched>. Um traceparent ausente ou inválido inicia um novo trace.
Os metadados do span contêm o método, o modelo de rota, o endpoint, o código de status e a duração. Eles não contêm o caminho concreto nem a query string.
Na versão 0.1.6 e mais recentes, o span da requisição cobre todo o dispatch do Flask. Os hooks before-request, os handlers de erro e o teardown compartilham o trace da requisição. Uma resposta em streaming encerra o span quando o corpo termina ou é fechado.
Teste a captura de exceções
Um status4xx ou 5xx aparece no span da requisição. Só o status não prova que houve uma exceção. Leia os traces e os problemas antes de diagnosticar uma falha. O LogBrew não substitui os handlers de erro do Flask nem muda o status da resposta.
Em um projeto de desenvolvimento, adicione uma rota temporária. Chame essa rota uma vez. Remova a rota antes de implantar:
500. Encontre o novo problema e a métrica da requisição:
local capture check.
Conecte o trabalho de saída à requisição
O SDK para Python tem helpers controlados pela aplicação pararequests, urllib, httpx, aiohttp, banco de dados, cache e filas. Cada helper cria um span filho no trace ativo da requisição. O SDK não altera essas bibliotecas de forma global. O pacote logbrew-flask mostra exemplos.
Dê a cada helper um nome de operação estável e um modelo de rota ou de instrução. Não coloque IDs de registros, valores de clientes, valores de bind de SQL nem payloads de mensagens nesses nomes. Adicione spans filhos só onde a dependência importa para a requisição. Um span para cada chamada pequena deixa o trace mais difícil de ler. Os helpers de HTTP de saída adicionam um cabeçalho traceparent W3C. Eles não capturam URLs completas, query strings, corpos, cookies nem cabeçalhos arbitrários. Os helpers de banco de dados, cache e fila não capturam valores de bind, resultados, valores de cache nem payloads de fila.
Privacidade e ciclo de vida do processo
A captura automática do Flask deixa de fora os caminhos concretos de requisição, as query strings, os corpos de requisição e de resposta, os cookies, os cabeçalhos arbitrários, os valores brutos detraceparent, o baggage e o tracestate.
A captura automática de exceções nunca lê nem envia str(error). Ela usa o resumo fixo Unhandled exception e marca como ocultada cada mensagem da cadeia de exceções. Os frames contêm o nome base do arquivo e uma identificação limitada do código. Eles não contêm o texto bruto do traceback, código-fonte, variáveis locais nem caminhos absolutos.
Crie a aplicação e o cliente do LogBrew dentro de cada processo worker. O carregamento padrão da aplicação por worker do Gunicorn funciona. Não use o --preload do Gunicorn com um cliente criado no processo pai. No uWSGI, use o carregamento da aplicação por worker, como --lazy-apps. O cliente Python não aceita ser reutilizado depois de um fork do processo.
Chame logbrew.client.shutdown() no hook de encerramento por worker do gerenciador de processos. Ele envia os eventos que ainda estão na fila e fecha o cliente. Não chame esse método depois de cada requisição. Depois do encerramento, o cliente rejeita novos eventos desse worker.
Uma resposta pode terminar antes que o worker envie os últimos eventos da fila. Durante uma implantação ou uma redução de escala, um encerramento controlado dá a esses eventos uma última tentativa de entrega.
Corrija falhas de configuração
Para erros de acesso da conta, de chave e de leitura, veja Solução de problemas. Para outros runtimes, veja Integração do SDK.