Correlation Tracing

Um identificador único nasce na borda e viaja no header x-correlation-id por todos os serviços; cada hop ganha o próprio requestId e todo log leva os dois. Com isso a trilha completa de uma operação é reconstruída filtrando os logs por um único id. Use quando uma operação atravessa dois a cinco serviços e o debug precisa seguir o caminho inteiro.

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

Infraestrutura realTypeScriptBunElysiaPostgreSQLDocker

Cenário Relações Comparar

Baixar cartão

Cenário

Um banco digital recebe PIX por um gateway, liquida no serviço de pagamento e avisa o recebedor no serviço de notificação — três processos Elysia separados, falando por HTTP. Um PIX sem header recebe id do gateway; um PIX de alto valor ganha um aviso a mais na mesma trilha; um PIX com id enviado pelo app tem o id propagado, nunca trocado.

Como funciona

6 passos

Um ID atravessa toda a requisição.

Esconde cada passo: lembre antes de tocar para revelar.

Vocabulário compartilhado

x-correlation-id+3

AsyncLocalStorage+1

Correlation ID

correlationFetch+1

Correlation ID

correlationLog+1

Correlation ID

01
Geração só na bordaO gateway gera um UUID v7 quando o cliente não manda x-correlation-id; serviço interno sem o header responde 400
02
requestId por hopCada serviço gera o seu — aponta qual chamada da cadeia falhou, enquanto o correlation id identifica a operação inteira
03
Contexto no processoAsyncLocalStorage guarda correlation id, request id e serviço durante a requisição, sem passar parâmetro por toda função
04
PropagaçãocorrelationFetch repassa o header em toda chamada de saída; a resposta ecoa o id ao cliente
05
Log estruturadocorrelationLog escreve uma linha JSON em stdout e grava o mesmo registro em trace_logs; falha nessa gravação nunca derruba o PIX
06
ReconstruçãoConsulta por correlation_id em ordem de tempo mostra os passos dos três processos

apps/patterns/correlation-tracing

10 arquivos

sql/

01_schema.sqlschemaTabela trace_logs com payload JSONB e índice por correlation id

src/

middleware_correlation.tsMiddleware Elysia, AsyncLocalStorage, correlationLog e correlationFetch
db_trace.tsPool Bun.sql, gravação tolerante a falha e leitura da trilha
api_gateway.tsBorda (porta 7100): gera o id e chama o pagamento
api_payment.tsPagamento (porta 7101): liquida e chama a notificação
api_notification.tsNotificação (porta 7102): fim da cadeia
config_trace.tsLê e valida o ambiente no boot
middleware_correlation.test.tstesteIntegração com os 3 serviços e PostgreSQL reais
demo.tsdemoSobe os 3 processos, envia 3 PIX e imprime cada trilha