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 for 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 rodará em produção
• Adicionando um novo serviço, endpoint, job em background 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 acontecendo agora — use a habilidade debugging-and-error-recovery (a observabilidade é o que torna essa habilidade rápida da próxima vez)
• Profiling e otimização de lentidão medida — use a habilidade performance-optimization
• Checklists de monitoramento no dia do lançamento e gatilhos de rollback — veja a habilidade shipping-and-launch; essa habilidade cobre a instrumentação que os 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, traces 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) => {
  const suppliedId = req.headers['x-request-id'];
  req.id = typeof suppliedId === 'string' && /^[A-Za-z0-9_-]{1,64}$/.test(suppliedId)
    ? suppliedId
    : crypto.randomUUID();
  req.log = logger.child({ requestId: req.id });
  res.setHeader('x-request-id', req.id);
  next();
});

Nunca registre segredos, tokens, senhas ou PII completos. Esta é uma regra rígida da habilidade security-and-hardening — pipelines de telemetria são um caminho clássico de vazamento de dados. Permita campos por lista de permissões; não registre corpos de requisição inteiros.

4. Métricas

Para serviços orientados a requisições, instrumente RED em cada endpoint e cada dependência externa: Rate (requisições/segundo), Errors (taxa de falha), Duration (histograma de latência, não média). Para recursos (filas, pools, hosts), use USE: Utilization (Utilização), Saturation (Saturação), Errors (Erros).

…