For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /pt/docs/web/setup-observability.md (or send Accept: text/markdown).
Configurar a observabilidade
Monitorização de erros, analítica de produto e alertas de falha — tudo opcional.
Encontre informações úteis quando uma ação falha
Observabilidade significa ver o que seu aplicativo fez. Comece com o terminal executando seu servidor Web: repita uma ação com falha e leia o primeiro erro e qualquer ID de correlação, um rótulo que vincula mensagens da mesma solicitação. Compartilhe o comando, horário e erro higienizado ao pedir ajuda; não compartilhe arquivos .env ou tokens.
Para relatórios de erros hospedados, siga Integridade e operações para definir as configurações de monitoramento suportadas em apps/web/.env.local ou no painel do ambiente do host. Salve e reinicie o servidor. Acione uma falha de teste controlada em um ambiente de teste e confirme se ela aparece com o contexto de espaço de trabalho correto. O monitoramento configurado não prova que recebeu um evento.
ALERT_WEBHOOK_URL é um destino HTTPS opcional para alertas de falha na entrega de webhook de trabalhos e terminais. Se precisar, crie um endpoint de entrada compatível e salve seu servidor URL; caso contrário, deixe-o vazio. Peça a um agente para simular uma falha e confirmar exatamente um alerta, sem segredos no texto. Não acione trabalhos remunerados ou falhas nas contas dos clientes para este teste.
Mantém um rasto de auditoria por workspace
Os registos de auditoria capturam alterações como atualizações de configuração de fornecedor dentro de um workspace. Resolve o workspace autenticado antes de ler ou escrever esses registos e preserva esse limite ao adicionar eventos próprios do produto.
Regista a ação e os identificadores necessários para a compreender. Credenciais de fornecedor e outros valores sensíveis devem ficar fora dos payloads de auditoria e dos logs.
Captura eventos de produto
O pacote de observabilidade expõe um adaptador AnalyticsClient e valores AnalyticsEvent delimitados por workspace. Cada evento carrega um nome, uma identidade distinct, um workspaceId e propriedades opcionais.
Usa createObservability para encaminhar eventos através do teu cliente de analítica configurado. Propriedades estruturadas são higienizadas antes da entrega; mantém também texto livre sensível fora de nomes de evento e valores de propriedade.
Reporta erros com contexto seguro
O ErrorClient captura exceções com etiquetas workspaceId e contexto adicional estruturado. A camada de observabilidade partilhada higieniza exceções e contexto sensível antes de os reencaminhar para o cliente configurado.
Usa adaptadores locais para verificar eventos e exceções capturados sem chamar um fornecedor de monitorização. Testa que as etiquetas de workspace permanecem presentes e que credenciais são removidas antes de ativar um destino externo.
Siga uma solicitação em tarefas, jobs e webhooks
Os limites de entrada geram um ID de correlação corr_<uuid> que vincula a solicitação de origem ao trabalho que ela aciona. O envio de tarefas de IA carimba o ID na carga útil da tarefa e no evento ai_task_submitted, cada receptor de webhook de faturamento emite um por solicitação e o agendador emite um por trabalho despachado.
O mesmo ID utiliza as propriedades de evento job.completed e ai_task_completed, extras captureException, a carga útil do razão webhook_event e cada meta de carga útil webhook_delivery - para que ele caia dentro do corpo assinado que um assinante recebe. Ids ausentes ou malformados são tolerados: o consumidor cria um novo id em vez de rejeitar linhas mais antigas.
Alerta sobre falhas reais
Configure ALERT_WEBHOOK_URL para qualquer terminal HTTPS que aceite um formato JSON POST {texto, nome, gravidade, contexto}; um webhook de entrada no estilo Slack funciona como está. Os alertas são disparados e esquecidos com um tempo limite de cinco segundos, uma entrega com falha registra um aviso do console e o alerta faz noops enquanto a variável não está definida.
Os alertas enviados são job.failed (aviso — um manipulador de trabalho lançado ou um tipo de trabalho é desconhecido) e webhook.delivery_failed (crítico — somente quando uma entrega de saída atinge a falha do terminal após sua tentativa final; as tentativas comuns permanecem silenciosas e cada linha de entrega alerta no máximo uma vez).
Meça durações e transmita logs estruturados
serverObservability.measure cronometra uma operação assíncrona e emite um evento analítico <name>.duration transportando DurationMs - em caso de sucesso e falha, sem mascarar o erro original. A execução da tarefa ai.task.execute já está empacotada, portanto, a duração da execução da tarefa chega ao cliente de análise configurado.
serverObservability.logger grava uma linha JSON por registro no stdout com campos base de ambiente e serviço; a camada de redação compartilhada remove segredos antes que qualquer linha seja emitida.
Instalação e configuração
1. Define SENTRY_DSN para reporte de erros — as exceções são capturadas com IDs de correlação e etiquetas de workspace.
2. Define NEXT_PUBLIC_POSTHOG_KEY e NEXT_PUBLIC_POSTHOG_HOST para analítica de produto — são valores públicos de browser por design.
3. Define ALERT_WEBHOOK_URL para um endpoint compatível com Slack para alertas de falha — a app faz POST de JSON {text, name, severity, context}.
SENTRY_DSN=https://…@….ingest.sentry.io/…
NEXT_PUBLIC_POSTHOG_KEY=phc_…
NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com
ANALYTICS_PROVIDER=off # off | local | plausible | posthog
# ANALYTICS_SITE_ID=
# ANALYTICS_HOST=
ALERT_WEBHOOK_URL=https://hooks.slack.com/services/…Fluxo de implementação
A camada de observabilidade higieniza exceções e redige chaves secretas conhecidas antes de reencaminhar — mas texto livre de eventos é responsabilidade do autor, por isso mantém credenciais fora de nomes de evento e valores de propriedade.
Os adaptadores locais deixam os testes afirmar sobre eventos e exceções capturados sem chamar Sentry ou PostHog; nenhuma destas variáveis é necessária para correr localmente.
Sinais a fluir? Continua para Configurar domínios personalizados.
Verificação e resolução de problemas
Dispara uma exceção de teste e confirma que aterra no Sentry com os segredos retirados do payload, depois verifica que uma falha ligada faz POST para ALERT_WEBHOOK_URL. Se os eventos nunca chegam, verifica o par DSN/chave e que o host está alcançável a partir do servidor.
Para continuar a configuração, leia Configurar domínios personalizados.