Boas Práticas de Observabilidade

Crie alertas sobre sintomas, não sobre cada stack trace. Estas regras mantêm a observabilidade do Node.js acionável, acessível e correlacionada entre logs, métricas e traces.

Como Usar Esta Lista

• Aplique ao configurar um novo serviço ou migrar fornecedores de APM.
• Combine com SLOs e Orçamentos de Erro para a política de paginação.
• Revise a cardinalidade antes de exportar novas métricas personalizadas.
• Execute "game days" para verificar se os traces cobrem jornadas críticas do usuário.

A - Métricas e SLOs

• Exporte métricas RED para cada serviço HTTP. Taxa, erros (5xx), histograma de duração.
• Adicione espera de pool e profundidade de fila onde aplicável. Indicadores antecedentes antes de 5xx.
• Defina SLO com política de orçamento de erro por escrito. Não apenas no dashboard.
• Crie alertas sobre o consumo do SLO em múltiplas janelas, não em uma única linha de log. Regras de consumo rápido e lento.
• Normalize rótulos de rota (/users/:id). Nunca UUIDs em dimensões de métrica.

B - Traces e Instrumentação

• Carregue instrumentation.ts antes das importações do framework. Requisito de auto-instrumentação HTTP.
• Um caminho de instrumentação por processo. OTel SDK OU agente do fornecedor, não ambos.
• Amostre traces na produção (1-10%). Amostre erros no final ("tail-sample") se o fornecedor suportar.
• Use spans manuais em operações de negócios críticas. Pagamento, autenticação, enfileiramento.
• Propague o traceparent W3C em requisições HTTP de saída. Serviços downstream continuam o trace.

C - Logs e Correlação

• Injete trace_id em logs Pino via mixin ou ALS. Correlação log-trace em APM.
• Mantenha requestId ao lado de trace_id durante a migração. Suporte e ferramentas legadas.
• Apenas JSON estruturado; sem PII em atributos de span ou campos de log. IDs, não e-mails.
• Separe backends de telemetria de dev/staging/prod. Sem vazamento de traces de produção para contas de dev.
• Use info para o ciclo de vida; error para falhas que exigem ação. Mesmas regras da seção de logging.

D - Dashboards e Alertas

• Um dashboard de sinais de ouro por serviço. RED + pool + fila + atraso do loop.
• Runbooks vinculados às anotações de alerta. Não embutidos em cada span.
• Crie alertas sobre limiares de sintomas (p95, taxa de erro). Não apenas CPU.
• Revise a fadiga de alertas trimestralmente. Exclua alertas que nunca levaram a ação.
• Verificações de saúde excluídas do SLO ou registradas em debug. Tráfego de sondagem distorce métricas.

E - Operações e Custo

• sdk.shutdown() gracioso em SIGTERM. Descarregue spans antes do encerramento do pod.
• Use OTel Collector para exportação para fornecedor em k8s. A aplicação permanece neutra em relação ao fornecedor com OTLP.
• Documente OTEL_SERVICE_NAME por implantação. Precisão do catálogo de serviços.
• Monitore o custo de ingestão de telemetria mensalmente. Ajustes de amostragem quando o volume de spans aumenta.
• Valide a observabilidade em testes de carga antes do lançamento. Métricas e traces sob o RPS esperado.

FAQs

Relacionados

• Conceitos Básicos de Observabilidade - introdução aos três pilares
• OpenTelemetry Node SDK - configuração do SDK
• Métricas que Importam - o que exportar
• Boas Práticas de Logging - regras de logging estruturado

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, e NestJS 11.