Esta página é uma tradução automática da página em inglês, que é a versão de referência. Ler a página em inglês
Relatórios de erro
Como o servidor informa sobre os próprios bugs e falhas, onde ler os relatórios em cada plataforma e como enviá-los a um rastreador de erros. As métricas dizem que algo está errado; um relatório de erro diz o que falhou, com a sua pilha de chamadas. A referência de configuração lista todas as configurações.
Três coisas acontecem com todo relatório, qualquer que seja a configuração:
- Uma linha
error reportvai para a saída de erro padrão, com a pilha (A linha de log). - O relatório é contado em um grupo de erros no banco de dados. A tela de administração mostra os grupos, e as pessoas com a permissão
manage_errorssão notificadas dos grupos novos e dos que se repetem (Grupos de erros e notificações). - Se você definir
errors_exporter, o relatório também vai para um serviço externo (Enviando relatórios para um serviço).
Nada sai do servidor a menos que você defina errors_exporter.
O que é reportado
Seção intitulada “O que é reportado”| Reportado | Não reportado (as métricas e as outras linhas de log cobrem esses casos) |
|---|---|
| Um panic em um handler HTTP, em um job ou em uma tarefa em segundo plano | Respostas 4xx (entrada inválida, autorização, limites de taxa) e o modo de manutenção |
| Um erro por trás de uma resposta 5xx da API cliente, da API administrativa, das páginas de login, do ActivityPub, do OAuth ou da mídia | Uma requisição cujo cliente desistiu |
Um job que falhou de vez (dead) |
Uma nova tentativa de job. Ela é reportada quando esgota as tentativas |
| Uma falha ao iniciar: uma configuração inválida, ou um banco de dados ou adaptador que não pode ser preparado | Uma verificação de prontidão que falhou |
| Um erro que o cliente web não tratou, enviado pelo navegador ao servidor | Falhas causadas por outros servidores: novas tentativas e desistências de entrega, assinaturas rejeitadas, buscas remotas que falharam |
| Os ruídos do próprio navegador: uma rede perdida, erros de extensões do navegador e pedaços de código que um novo deploy removeu |
Uma falha de um serviço externo (e-mail, armazenamento, pagamentos, voz) só é reportada quando faz um job falhar de vez ou uma requisição responder 5xx. Uma falha temporária aparece nas métricas my.adapter.* (Executando o servidor).
Um panic em uma tarefa em segundo plano para o processo depois de reportado, para que o servidor nunca continue rodando em estado quebrado. A sua plataforma o reinicia.
A linha de log
Seção intitulada “A linha de log”A linha tem msg = error report e level ERROR (severity é CRITICAL quando a falha para o processo).
Os seus campos, e o que a sanitização faz com eles, estão em Executando o servidor. Em resumo:
my.error.fingerprinté o mesmo para toda ocorrência do mesmo erro. Pesquise ou agrupe por ele.my.error.whereindica onde aconteceu, por exemploclient_api GET /api/v1/statuses/{id}.request_id,job_id,trace_idespan_idencontram as outras linhas da mesma requisição ou do mesmo job.- A linha de um erro de requisição tem
context.httpRequest: o método, a rota como URL (/api/v1/statuses/{id}, nunca o caminho que o cliente pediu) e o status respondido. O Error Reporting os mostra no grupo e pode filtrar por eles. messagefica por último na linha: o tipo e a mensagem do erro, uma quebra de linha e a pilha do Go.- A pilha começa onde o erro se originou, não onde foi reportado: para um erro de banco de dados, a função do servidor que executou a consulta. Erros de lugares diferentes caem, portanto, em grupos diferentes, tanto no Error Reporting quanto na tela de administração.
Nenhuma outra linha traz uma pilha.
Google Cloud (Cloud Run)
Seção intitulada “Google Cloud (Cloud Run)”O Cloud Error Reporting lê a linha sem nenhuma configuração e lista os erros no console, em Error Reporting. O serviço é gratuito; você paga apenas pelo Cloud Logging.
- Ele agrupa os erros pelo tipo e pelos frames do topo da pilha. Não consegue usar a impressão digital do servidor, então um grupo no Error Reporting pode ser diferente de um grupo na tela de administração.
- Ele mantém os grupos por 30 dias, e avisa sobre erros novos e sobre erros resolvidos que acontecem de novo, no máximo 20 notificações por hora para o projeto. Configure o canal de notificação dele no console do Google Cloud.
- Para descobrir o que aconteceu em torno de um relatório, pesquise no Cloud Logging por
jsonPayload."request_id"="<id>", ou o mesmo comtrace_id.
Com o módulo OpenTofu mycroblog-gcp, a seção observability envia os relatórios para cá por padrão (errors = "error-reporting"): ela ativa a API do Error Reporting e deixa errors_exporter em none.
O CloudWatch Logs lê a linha como JSON comum.
- Ative a detecção de anomalias de log para o grupo de logs. Ela sinaliza um padrão de linha que nunca viu antes e pode disparar um alarme no SNS. Ela lê apenas os primeiros 1.500 caracteres de uma linha, por isso
messageé o último campo. Ela não mantém um estado de resolvido. - Para contar os relatórios, crie um filtro de métrica como
{ $.msg = "error report" }. Não use como dimensão nenhum valor demy.error.fingerprint: cada valor de uma dimensão é cobrado como uma métrica própria.my.error.sourceemy.error.kindsão seguros. - Encontre o contexto com o Logs Insights:
filter `request_id` = "<id>".
Com o módulo OpenTofu mycroblog-aws, a seção observability mantém os relatórios no CloudWatch Logs por padrão (errors = "cloudwatch"), com errors_exporter em none. A detecção de anomalias de log continua sendo um passo seu.
Instalação própria
Seção intitulada “Instalação própria”Leia a linha no log do contêiner: docker compose logs my | jq -c 'select(.msg == "error report")'.
Com metrics_exporter = prometheus, o alerta MyErrorReportsIncreasing (Alertas e runbook) avisa quando os relatórios sobem de forma acentuada; o contador por trás dele é my.errors.reported.
Para notificações que não precisam de um serviço externo, use a tela de administração e os webhooks abaixo. Para um rastreador, use errors_exporter.
Grupos de erros e notificações
Seção intitulada “Grupos de erros e notificações”O servidor conta os relatórios por impressão digital no banco de dados. Ele não precisa de configuração nem de serviço extra, e grava pouco: o primeiro relatório de uma impressão digital é gravado de imediato, e os seguintes são somados em memória e gravados uma vez por minuto. Uma parada forçada do processo pode perder as contagens do último minuto; as linhas de log não se perdem desse jeito. Contagens com mais de 90 dias são excluídas todos os dias. Se o banco de dados é o que falhou, o relatório fica apenas na linha de log.
A tela de administração
Seção intitulada “A tela de administração”As pessoas cuja função tem manage_errors (a função integrada admin tem) veem “Erros” no menu de administração (/admin/errors).
- A lista mostra os grupos, por padrão os abertos, o visto mais recentemente primeiro. Filtre por estado (aberto, resolvido, silenciado, todos os estados) e por origem (o servidor, o cliente web). Cada linha mostra a primeira linha da mensagem, onde aconteceu, as contagens das últimas 24 horas e dos últimos 7 dias, quando foi visto pela última vez e o seu estado.
- A página de um grupo começa com o que você pode fazer no estado dele (“Resolver” e “Silenciar” para um grupo aberto, “Silenciar” para um resolvido, “Deixar de silenciar” para um silenciado). Ela mostra os fatos do grupo (onde, a mensagem, a primeira e a última vez e versão, a impressão digital), as contagens das últimas 24 horas e dos últimos 7 dias, a ocorrência mais recente (horário, versão, função do processo, os tipos, o ID da requisição e o ID do trace, e a pilha), as ocorrências por hora dos últimos 90 dias, da mais nova para a mais antiga, e o histórico das mudanças de estado. A impressão digital, o ID da requisição, o ID do trace e a pilha têm um botão de copiar: cole os IDs na sua busca de logs.
- “Resolver” serve para um erro que você corrigiu. Se ele acontecer de novo em outra versão do servidor, o grupo volta a abrir e notifica de novo. O mesmo erro na versão resolvida é apenas contado, então as últimas requisições da versão antiga não o reabrem.
- “Silenciar” continua contando, mas não envia notificação nem evento de webhook. “Deixar de silenciar” reabre o grupo.
As mesmas ações estão disponíveis em GET /api/v1/admin/error_groups e POST /api/v1/admin/error_groups/{id}/resolve (/mute, /unmute).
Notificações e webhooks
Seção intitulada “Notificações e webhooks”- As pessoas com
manage_errorsrecebem a notificaçãoadmin_error_grouppara um grupo de erros novo e para uma recorrência. No máximo 10 chegam por hora para o servidor inteiro; o restante da hora se agrupa em uma notificação que diz que mais erros foram reportados. Elas também podem recebê-la por e-mail (Moderação). - Os eventos de webhook
error_group.createdeerror_group.regressedtrazem os mesmos grupos, para que você possa enviá-los ao Slack, ao Discord ou a uma ferramenta de automação (Webhooks do servidor, Referência de webhooks). O webhook exigemanage_webhooks, e os eventos exigemmanage_errors. - Um grupo silenciado nunca notifica.
Erros do cliente web
Seção intitulada “Erros do cliente web”O cliente web envia os erros que as suas telas não trataram para POST /api/v1/client_errors no seu próprio servidor, então nenhum terceiro os vê e nenhuma configuração de segurança de conteúdo muda. O servidor responde 204 a tudo e descarta o que não aceita: um corpo maior que 16 KiB, uma pilha sem um arquivo do seu próprio cliente web e mais de 10 relatórios por minuto de um mesmo endereço IP. O mesmo erro é enviado uma vez por visualização de página, e no máximo 20 por visualização de página.
Um relatório enviado sem uma sessão iniciada é contado e registrado, mas não notifica ninguém por si só, então um script anônimo não consegue encher a sua caixa de entrada. O grupo notifica quando o navegador de uma pessoa com sessão iniciada também o reporta.
As pilhas são as da build minificada e não são traduzidas de volta para o código-fonte, então leia primeiro a rota e a mensagem. A versão é a do servidor que serviu a página. Uma página que abriu offline, ou depois de 3 segundos sem resposta, vem da cópia do navegador, que indica a versão de quando o navegador armazenou o cliente web: uma versão mais antiga com o mesmo cliente web.
Medições de UX
Seção intitulada “Medições de UX”O cliente web envia amostras da rapidez com que responde para POST /api/v1/client_measurements no seu próprio servidor, do mesmo modo que os seus erros: quanto tempo uma tela leva para aparecer (LCP) e para responder a um toque (INP) em cada rota, os seus frames longos, cada navegação por tipo, cada ação pelo seu ID (post.reply), e a latência de ida e volta, o jitter e a perda de pacotes das chamadas de voz. Uma amostra nomeia apenas a rota, o tipo, a ação ou o transporte da chamada; não traz conta, endereço nem URL. O servidor responde 204 a tudo e aceita no máximo 10 requisições por minuto de um mesmo endereço IP.
O servidor conta as amostras por hora no banco de dados, gravando uma vez por minuto, e as exclui após 30 dias. GET /api/v1/admin/ux_measurements (manage_errors) soma as últimas 24 horas, ou hours até 720, com o percentil 75 de cada nome; as métricas my.ux.duration e my.ux.call.packet_loss exportam as mesmas amostras (Métricas). Cada tipo mantém os seus primeiros 200 nomes em um processo; os seguintes contam como other.
Vem desativado por padrão; a configuração da instância ux_measurement o ativa, e enquanto estiver desativado o servidor não coleta nenhuma amostra (Configurações da instância). Quando ativado, apenas uma parte das sessões do navegador envia amostras, 10 % a menos que ux_measurement_share defina outro valor, e cada sessão é sorteada uma vez quando o cliente web inicia.
As pessoas cuja função tem manage_errors veem “Medições de UX” no menu de administração (/admin/ux-measurements). Escolha as últimas 24 horas, 7 dias ou 30 dias; cada métrica com amostras tem uma tabela dos seus nomes com as respectivas amostras e o percentil 75 e, para LCP e INP, a parcela de amostras boas e a de ruins (dentro de 2,5 s e acima de 4 s para LCP, dentro de 200 ms e acima de 500 ms para INP), com o percentil 75 acima do limite de bom destacado. “Medir o cliente web”, abaixo das tabelas, é a configuração ux_measurement, que só as pessoas cuja função também tem manage_settings alteram ali, com o seu próprio “Salvar”.
Enviando relatórios para um serviço
Seção intitulada “Enviando relatórios para um serviço”Defina errors_exporter para enviar também cada relatório a um rastreador de erros. A linha de log e os grupos no banco de dados continuam ativos. Um relatório é enviado uma única vez e nunca tentado de novo, e nada espera pelo serviço.
| Valor | Envia para |
|---|---|
none (padrão) |
Lugar nenhum |
sentry |
Qualquer serviço compatível com Sentry em errors_sentry_dsn |
otlp |
Um coletor ou backend do OpenTelemetry, como registros de log |
errors_environment (padrão production) nomeia a implantação em cada relatório, como staging.
Os dois exportadores enviam os mesmos campos sanitizados da linha de log, com a impressão digital e os IDs de trace e de span, e nada sobre o host: nenhum nome de host, endereço IP, usuário, corpo de requisição, cabeçalho ou cookie.
O servidor limita o que envia para que o serviço não seja inundado:
- A mesma impressão digital sai no máximo uma vez por minuto por processo, e todos os relatórios no máximo 60 por minuto. O restante fica no log e nos grupos.
- Até 1.000 relatórios esperam para ser enviados. Um relatório que encontra a fila cheia é descartado. Quando o servidor para, ele aguarda até 2 segundos para a fila esvaziar.
- Quando o serviço responde
429ou pede para desacelerar (Retry-After,X-Sentry-Rate-Limits), o servidor para de enviar por esse tempo. - O servidor nunca segue um redirecionamento do serviço, para que a chave do DSN e o relatório não vão para nenhum outro lugar: um redirecionamento conta como
failed. Use o DSN que o serviço mostra, que aponta para a própria entrada dele.
Acompanhe o contador my.errors.exported: my.outcome é success, dropped (acima de um limite, a fila estava cheia ou o serviço pediu para desacelerar) ou failed (o serviço não pôde ser alcançado ou recusou o relatório) (Executando o servidor).
Sentry, GlitchTip e Datadog
Seção intitulada “Sentry, GlitchTip e Datadog”MY_ERRORS_EXPORTER=sentryMY_ERRORS_SENTRY_DSN_FILE=/run/secrets/sentry_dsn # or MY_ERRORS_SENTRY_DSN; the DSN is a secretCom os módulos OpenTofu, deixe os erros da seção observability por conta das configurações, e o módulo cria o segredo do DSN para você preencher, que a saída secrets_to_fill lista:
observability = { errors = "settings" } settings = { errors_exporter = "sentry" } secrets = ["errors_sentry_dsn"]O servidor fala o protocolo do Sentry por conta própria, então nenhum SDK do Sentry está envolvido e nenhuma variável de ambiente SENTRY_* é lida. Ele define a impressão digital, para que o serviço agrupe por ela, e as tags service (my), my.role, my.error.where e error.fingerprint. A release é a versão do servidor e o ambiente é errors_environment.
- Sentry (hospedado ou instalado por você): copie o DSN das chaves de cliente do projeto.
- GlitchTip: copie o DSN do projeto. Ele é de código aberto e roda em um servidor pequeno. Verifique quais regras de alerta a sua versão oferece para problemas novos e recorrentes.
- Datadog Error Tracking: use o DSN do Sentry do seu site do Datadog,
https://<DD_API_KEY>@sentry-intake.<DD_SITE>/1. O Datadog exige a tagservice, que o servidor sempre define. O Datadog guarda esses eventos como logs e os agrupa no Error Tracking. Se, em vez disso, você enviar a linha de log ao Datadog por um agente ou um encaminhador (Error Tracking for Logs), a pilha fica emmessage; mapeie-a paraerror.stackcom um pipeline de logs, senão o Datadog não a vê como pilha. O exportadorsentrynão precisa desse mapeamento.
Backends OTLP
Seção intitulada “Backends OTLP”MY_ERRORS_EXPORTER=otlpOTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318 # or OTEL_EXPORTER_OTLP_LOGS_ENDPOINTOTEL_EXPORTER_OTLP_HEADERS=authorization=Bearer%20...Cada relatório é um registro de log do OpenTelemetry chamado exception, com severidade ERROR (FATAL quando para o processo), exception.type, exception.message, exception.stacktrace, my.error.fingerprint, my.error.where, my.error.source, my.error.kind e os IDs de trace e de span. Ele vai por OTLP/HTTP (protobuf, gzip) com o mesmo recurso das métricas e dos traces.
Se o backend transforma esses registros em erros agrupados depende do backend: alguns montam as visões de erro só a partir dos dados de trace, e o Datadog precisa de error.stack. Para Sentry, GlitchTip e Datadog, use sentry. Use otlp quando quiser os registros junto dos seus outros logs.
O que a sanitização faz e o que não garante
Seção intitulada “O que a sanitização faz e o que não garante”A sanitização roda uma vez, quando o relatório é criado, então a linha de log, o banco de dados e todos os exportadores recebem apenas o texto sanitizado.
- Na mensagem, URLs, endereços de e-mail, identificadores
@user@host, endereços IP, UUIDs e ULIDs, e números de 10 dígitos ou mais são substituídos por<url>,<email>,<acct>,<ip>,<id>e<n>, e a mensagem é cortada em 1 KiB. - Na pilha, os valores dos argumentos das funções são substituídos por
(...)e a pilha é cortada em 16 KiB. As posições dos arquivos permanecem, relativas à árvore do código-fonte, para que os caminhos da máquina de build não apareçam. - Nenhum relatório tem corpo de requisição, cabeçalho, query, cookie, ID de conta, nome de usuário, endereço IP ou User-Agent.
A sanitização compara padrões, então não garante que uma mensagem não contenha dados pessoais. Um nome, um texto livre ou um número com menos de 10 dígitos que uma mensagem de erro cite podem permanecer. O campo error das linhas comuns http request e job não é sanitizado dessa forma. Trate os logs e o rastreador de erros como lugares que podem conter fragmentos de conteúdo de usuários, e dê a eles o mesmo controle de acesso e a mesma retenção que ao restante dos seus logs. Quando você define errors_exporter, a localização, a retenção e as regras de acesso desse serviço passam a valer para os relatórios.
Para LLMs e agentes de programação:llms.txt,llms-full.txt, llms-small.txt