Observabilidade e Instrumentação

Visão Geral

Código que você não consegue observar é código que você não consegue operar. Observabilidade é a capacidade de responder "o que o sistema está fazendo e por quê?" de fora, usando a telemetria que o código emite. A instrumentação não é um complemento pós-lançamento — ela é escrita junto com o recurso, da mesma forma que os testes. Se um recurso é lançado sem telemetria, o primeiro bug reportado pelo usuário se torna arqueologia em vez de uma consulta.

Quando Usar

• Construindo qualquer recurso que será executado em produção
• Adicionando um novo serviço, endpoint, job em segundo plano ou integração externa
• Um incidente de produção demorou muito para ser diagnosticado ("não conseguimos dizer o que aconteceu")
• Configurando ou revisando regras de alerta
• Revisando um PR que adiciona I/O, retentativas, filas ou chamadas entre serviços

NÃO para:

• Diagnosticar uma falha que está acontecendo agora — use a habilidade debugging-and-error-recovery (a observabilidade é o que torna essa habilidade rápida na próxima vez)
• Profiling e otimização de lentidão medida — use a habilidade performance-optimization
• Listas de verificação de monitoramento no dia do lançamento e gatilhos de rollback — veja a habilidade shipping-and-launch; esta habilidade cobre a instrumentação que as alimenta

Processo

1. Defina "funcionando" antes de instrumentar

Telemetria sem uma pergunta é ruído. Antes de adicionar qualquer instrumentação, escreva 2–4 perguntas que um engenheiro de plantão fará sobre este recurso:

FEATURE: checkout payment retry
QUESTIONS ON-CALL WILL ASK:
1. What fraction of payments succeed on first attempt vs after retry?
2. When a payment fails permanently, why? (provider error? timeout? validation?)
3. Is the payment provider slower than usual?
→ Every signal below must help answer one of these.

Se você não consegue nomear as perguntas, você não está pronto para instrumentar — você registrará tudo e não aprenderá nada.

2. Escolha o sinal certo para cada pergunta

Regra de ouro: métricas dizem que algo está errado, rastreamentos dizem onde, logs dizem por quê.

3. Logging Estruturado

Registre eventos, não prosa. Cada linha de log é um objeto JSON com um nome de evento estável e campos legíveis por máquina:

// BAD: string interpolation — unqueryable, inconsistent
logger.info(`Payment ${id} failed for user ${userId} after ${n} retries`);

// GOOD: stable event name + structured fields
logger.warn({
  event: 'payment_failed',
  paymentId: id,
  provider: 'stripe',
  errorCode: err.code,
  attempt: n,
}, 'payment failed');

Níveis de log — use-os consistentemente:

IDs de Correlação são obrigatórios. Gere (ou aceite) um ID de requisição na fronteira do sistema e anexe-o a cada linha de log, span e chamada de saída. Sem ele, você não consegue reconstruir uma única requisição a partir de logs intercalados:

// Express: child logger per request, ID propagated downstream
app.use((req, res, next) => {
  req.id = req.headers['x-request-id'] ?? crypto.randomUUID();
  req.log = logger.child({ requestId: req.id });
  res.setHeader('x-request-id', req.id);
  next();
});

Quando vários pontos de entrada escrevem em um único log, nomeie o ponto de entrada. Um ID de correlação identifica uma execução; ele não diz qual caminho de código a iniciou. O mesmo job alcançado por um agendador, por um endpoint de repetição e por uma execução manual de CLI produz linhas intercambiáveis em um único sink, então atribuir uma linha recai sobre eliminação — leitura cruzada do histórico do agendador, da tabela de processos, de um log de deploy — e esse argumento só se sustenta enquanto esses registros externos por acaso ainda existirem. Marque o ponto de entrada onde a execução começa, ao lado do ID de correlação, e propague ambos da mesma forma:

// Um helper para cada ponto de entrada: o logger da execução carrega ambos os campos.

…