Distributed Tracing

Mede cada etapa de uma operação que atravessa vários serviços: cada processo abre spans com a SDK oficial do OpenTelemetry, o contexto viaja no header W3C traceparent e o Jaeger monta uma árvore única com a latência de cada passo. Use quando o problema é descobrir onde, na cadeia de serviços, o tempo ou o erro acontece.

passos: 6
arquivos: 10
teste: 1
tecnologias: 6

Infraestrutura realTypeScriptBunElysiaOpenTelemetryJaegerDocker

Cenário Relações Comparar

Baixar cartão

Cenário

Um banco digital processa PIX passando por gateway, serviço de pagamento e serviço de notificação — três processos Elysia com SDK próprio. O PIX aprovado mostra onde foram os milissegundos (antifraude, débito, push); o PIX acima do saldo mostra o span do débito marcado como erro e a notificação que nunca aconteceu.

Como funciona

6 passos

Spans ligam a chamada entre serviços.

Esconde cada passo: lembre antes de tocar para revelar.

Vocabulário compartilhado

01
SDK pré-carregadobun --preload ./src/instrumentation.ts sobe o NodeSDK antes do app, com service.name no Resource, BatchSpanProcessor e exportador OTLP
02
Span por requisiçãoO plugin @elysiajs/opentelemetry abre o span SERVER como filho do traceparent recebido; /health fica fora do trace
03
Span de negóciorecord() abre o span filho, fecha no fim e, se a função lançar, registra a exceção e marca ERROR
04
PropagaçãoO fetch do Bun não é auto-instrumentado — traceFetch injeta o traceparent em toda chamada de saída
05
AmostragemParentBasedSampler respeita a decisão de quem chamou; OTEL_SAMPLE_RATIO é 1 no demo e em torno de 0,1 em produção
06
Flush e correlaçãosdk.shutdown() no SIGTERM envia o último lote; cada linha de log leva trace_id e span_id

apps/patterns/distributed-tracing

10 arquivos

src/

instrumentation.tsSDK do OpenTelemetry pré-carregado: Resource, exportador, amostragem, shutdown
trace_pix.tstraceFetch (propagação) e traceLog (log com trace_id)
api_gateway.tsGateway (porta 7200): raiz do trace
api_payment.tsPagamento (porta 7201): spans de antifraude e débito
api_notification.tsNotificação (porta 7202): último salto
jaeger_pix.tsLeitura de um trace pela API de consulta do Jaeger
config_pix.tsLê e valida o ambiente no boot
api_gateway.test.tstesteIntegração contra Jaeger real: um trace, cadeia de pais, span de erro
demo.tsdemoSobe os 3 processos, envia 2 PIX e imprime as árvores