Investigação ponta a ponta: do log ao span que explica a falha

Você já conhece logs e traces; agora vamos usá-los como uma cadeia de evidências. Imagine um pedido que falha somente ao calcular o frete: a métrica aponta o horário, o log descreve o evento e o trace_id permite procurar a execução correspondente.

Um contrato de log define campos estáveis para toda a equipe. Comece com timestamp, level, service, event, trace_id e span_id; acrescente apenas atributos necessários ao diagnóstico. Um evento como shipping.failed é mais fácil de consultar que dezenas de mensagens livres.

O contexto ativo pertence à execução atual, não a uma variável global. Com a instrumentação OTel inicializada antes da aplicação, trace.getSpan(context.active()) recupera o span daquela operação. Guardar o último identificador em uma variável compartilhada mistura requisições concorrentes e produz correlações falsas.

No exemplo, a função logEvent usa uma lista permitida de campos e consulta o contexto no momento da emissão. Execute-a dentro de um handler instrumentado; fora de um span, os identificadores ficam ausentes. Isso é esperado em tarefas ainda não instrumentadas e não deve ser preenchido com um identificador inventado.

Para cruzar processos, a propagação precisa transportar contexto: em HTTP, normalmente traceparent; em filas, propriedades da mensagem. Se o consumidor iniciar outro trace, confira injeção no produtor e extração no consumidor antes de concluir que o backend perdeu dados. Instrumentação automática não cobre necessariamente todo cliente de mensageria.

No Loki, mantenha trace_id no conteúdo JSON, não como label indexado do stream. Filtre primeiro pelo serviço e pelo intervalo, depois extraia o JSON e busque o identificador. Configure no Grafana um campo derivado apontando para o backend de traces para reduzir o trabalho manual.

A amostragem muda o que você consegue provar. Um log com trace_id não garante que o trace foi armazenado: uma decisão de head sampling pode descartá-lo antes do Collector. Tail sampling só avalia spans que chegaram até ele; não recupera dados descartados na origem.

Feche o exercício com uma falha controlada no laboratório: provoque timeout no frete, encontre o evento shipping.failed e confira a duração do span correspondente. Registre também o caso sem trace retido e a limitação observada. Investigar bem inclui dizer o que a evidência disponível não permite concluir.

Na prática

Logger com correlação ao contexto ativo

javascript

import { context, trace } from "@opentelemetry/api";

// Pré-requisito: SDK OTel inicializado antes da aplicação.
function logEvent(event, { status, dependency } = {}) {
  const span = trace.getSpan(context.active());
  const ids = span?.spanContext();
  // Lista permitida: não aceite corpo, headers ou atributos arbitrários.
  process.stdout.write(JSON.stringify({
    timestamp: new Date().toISOString(),
    level: "error",
    service: "cloudshop-api",
    event,
    trace_id: ids?.traceId,
    span_id: ids?.spanId,
    status,
    dependency,
  }) + "\n");
}

// Chame dentro do handler instrumentado ao detectar a falha real.
logEvent("shipping.failed", { status: 504, dependency: "shipping" });

Localizar o evento correlacionado no Loki

logql

# Selecione o intervalo do incidente e substitua pelo trace_id observado.
{app="cloudshop", component="api"}
  | json
  | event = "shipping.failed"
  | trace_id = "4bf92f3577b34da6a3ce929d0e0e4736"

Por que isso importa

Correlação confiável reduz tentativas aleatórias e permite explicar qual dependência afetou uma jornada.

Erro comum

Presumir que todo trace_id encontrado em log terá um trace armazenado, ignorando a amostragem.

Dica de produção

Teste a correlação em duas requisições simultâneas e após atravessar uma fila; isso revela contexto perdido ou compartilhado.

Alerta de segurança

Não registre Authorization, cookies, payloads de pagamento nem baggage indiscriminadamente; aplique retenção e acesso mínimo aos backends.

Pergunta de entrevista

Como você investigaria logs com trace_id válido quando o backend não encontra o trace?

Investigação ponta a ponta: do log ao span que explica a falha

Objetivos desta aula

Na prática

Glossário

Conexão com o CloudShop

Quiz da aula

Minhas anotações