Distributed Tracing

Mede quanto tempo cada etapa de uma requisição levou, atravessando serviços: cada serviço abre spans filhos do traceparent que recebeu, exporta via OTLP para o Jaeger, e o trace montado mostra exatamente onde o tempo foi gasto. Enquanto o correlation ID só agrupa logs, o trace aponta o gargalo — “320 ms no total, 300 ms no modelo de fraude”. Use quando a latência ou o erro atravessam três ou mais serviços.

passos: 6
arquivos: 9
testes: 0
tecnologias: 6

Infraestrutura realTypeScriptBunElysiaOpenTelemetryJaegerDocker

Cenário Relações Comparar

Baixar cartão

Cenário

Um PIX passa pelo gateway, pelo antifraude (que chama um modelo de risco) e pelo serviço de contas (que debita). Com o modelo degradado para 300 ms, o trace mostra a requisição inteira em ~320 ms e aponta fraud.model.score como o span com mais tempo próprio. Um PIX acima do saldo termina com o span accounts.debit em ERROR e a exceção registrada. Um PIX marcado como não amostrado pelo cliente não deixa span em nenhum dos três serviços.

Planta

Sequência

9/9

9 passos — reproduza para seguir o fluxo

chamada
resposta ou assíncrono
falha
passo
toque num participante para focar
Outras plantas de sequência

Como funciona

6 passos

Trace da requisição ponta a ponta.

Esconde cada passo: lembre antes de tocar para revelar.

Vocabulário compartilhado

fetch+6

service.name+3

@elysiajs/opentelemetry+3

--preload+1

SigNoz — Observabilidade OpenTelemetry-nativa

SERVER+1

Distributed Tracing

traceparent+1

Distributed Tracing

traceFetch+1

Distributed Tracing

ParentBasedSampler+1

Distributed Tracing

01
Cada serviço é um processo com o SDK do OpenTelemetry pré-carregado (--preload) e o próprio service.name
02
@elysiajs/opentelemetry abre o span SERVER de cada requisição como filho do traceparent recebido; record abre um span filho por etapa com atributos
03
O fetch do Bun não é instrumentado: traceFetch injeta o traceparent em toda chamada de saída
04
Uma exceção dentro de record marca o span como ERROR e grava o evento da exceção
05
ParentBasedSampler respeita a decisão de quem chamou: amostrado segue amostrado em todos os serviços, e não amostrado não vira meio trace
06
selfTimeMs desconta dos spans o tempo dos filhos; bottleneck aponta o span que de fato segurou a requisição

Trade-offs

O que se ganha, o que se paga

4 vantagenscada ganho tem um preço4 custos

Vantagens

Tempo por etapa e gargalo apontado, entre serviços
Erro localizado no span que falhou, com a exceção
Amostragem parent-based evita traces pela metade
Atributos padronizados permitem buscar por conta ou modelo

Custos

SDK, exportador e backend de traces para operar
Todo serviço precisa propagar o traceparent, ou o trace quebra
Com amostragem baixa, o trace do incidente pode não ter sido guardado
Overhead de CPU e rede por span; span de sub-milissegundo não compensa

apps/observability/distributed-tracing

9 arquivos

src/

instrumentation.tsSDK por processo: service.name, exportador OTLP e amostragem parent-based
api_gateway.tsRaiz do trace: spans CLIENT para fraude e contas, com propagação
api_fraud.tsAntifraude com o span do modelo e latência ajustável em runtime
api_accounts.tsDébito com atributos de banco de dados e span em ERROR sem saldo
trace_http.tsfetch com traceparent e log com trace_id
trace_analysis.tsLeitura do trace no Jaeger, self time e gargalo
services_spawn.tsSobe os três processos e envia PIX com traceparent do cliente
config_tracing.tsConfiguração validada do ambiente
demo.tsdemoÁrvore de spans com self time, modelo degradado, erro e requisição não amostrada