distributed-tracing

Observabilidade — Distributed Tracing

Quando usar

LLM carrega esta skill ao instrumentar tracing distribuído ou stitching de spans. Trigger phrases:

• "distributed tracing", "traces", "spans"
• "propagar contexto entre serviços", "trace cross-service"
• "W3C TraceContext", "traceparent header"
• "trace_id span_id parent_span_id"
• "ligar lambda batch job ao trace"
• "stitching de eventos"

Regras absolutas

• trace_id é compartilhado entre todos os spans de um único request distribuído. NÃO mude por hop.
• span_id é único por span — gere novo a cada startSpan(). 16 hex chars (8 bytes).
• parent_span_id aponta para span pai — null no root span. Define a árvore.
• W3C TraceContext é o padrão — header HTTP traceparent: 00-{trace_id}-{span_id}-{flags}. Adote sempre. B3 é fallback para legacy.
• Propague ANTES de fazer call cross-service — extrair contexto do request inbound, propagar no request outbound. Sem isso, trace quebra.
• Stitching ≠ apenas RPC — também batch jobs, queue messages, lambda invocations, S3 uploads. Carregue traceparent em metadata da queue, env var do lambda, header da Step Function.
• Sample decision propaga — bit 01 em flags de traceparent significa "sample=true". Decisão tomada no head propaga downstream.
• Não invente trace_id — sempre derive do contexto inbound ou gere via SDK (não crypto.randomUUID()).
• Spans devem ter kind — SERVER (handler de inbound), CLIENT (call outbound), PRODUCER/CONSUMER (queue), INTERNAL (subspan dentro do mesmo process).

Patterns canônicos

Pattern: extrair contexto inbound + propagar outbound (Node)

// PT-BR: handler HTTP — extrai traceparent do request inbound, propaga em call outbound
import { trace, context, propagation } from '@opentelemetry/api'

const tracer = trace.getTracer('orders-service')

export async function placeOrder(req: Request) {
  // PT-BR: 1 — extrair contexto inbound do header traceparent
  const inboundContext = propagation.extract(context.active(), req.headers)

  return tracer.startActiveSpan(
    'place_order',
    { kind: SpanKind.SERVER },
    inboundContext,
    async (span) => {
      span.setAttribute('user.id', req.user.id)

      // PT-BR: 2 — fazer call outbound — propagation injeta traceparent automaticamente
      //         se você usar fetch/grpc instrumentados (ver skill opentelemetry-standard)
      const outboundHeaders: Record<string, string> = {}
      propagation.inject(context.active(), outboundHeaders)

      const inventoryRes = await fetch('http://inventory/check', {
        headers: outboundHeaders,  // PT-BR: traceparent injetado aqui
        body: JSON.stringify({ items: req.items })
      })

      span.end()
      return inventoryRes.json()
    }
  )
}