Correlation ID

Um identificador único por operação, gerado na borda e carregado por todos os serviços que ela atravessa: vai no header x-correlation-id de cada chamada, em toda linha de log e de volta ao cliente. Filtrar o agregador de logs por ele conta a história inteira de um PIX, de três serviços e de um job em segundo plano. Use quando os logs de uma operação ficam espalhados entre serviços e não há tracing distribuído.

passos: 6
arquivos: 4
testes: 0
tecnologias: 3

Lógica puraTypeScriptBunElysia

Cenário Relações Comparar

Baixar cartão

Cenário

Três PIX entram ao mesmo tempo pelo gateway: um liquidado, um recusado por passar do limite noturno e um que já chega com o id gerado pelo app. Os logs dos três serviços se misturam no agregador. Filtrando pelo id do PIX recusado aparecem só as linhas dele — recebido no gateway, recusado em pagamentos, respondido no gateway —, cada uma com o requestId do salto em que foi escrita.

Planta

Sequência

8/8

8 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

ID único liga logs da mesma requisição.

Esconde cada passo: lembre antes de tocar para revelar.

Vocabulário compartilhado

x-correlation-id+3

requestId+2

AsyncLocalStorage+1

Correlation Tracing

correlationLog+1

Correlation Tracing

correlationFetch+1

Correlation Tracing

01
middlewareCorrelation aceita o x-correlation-id recebido ou, na borda, gera um; valor fora do formato (curto, longo, com quebra de linha) é trocado, nunca levado ao log
02
O id vai para o header da resposta antes do handler rodar, então volta ao cliente mesmo em erro
03
Id, requestId novo por salto e nome do serviço ficam no AsyncLocalStorage pela requisição inteira
04
correlationLog escreve JSON com esse contexto; correlationFetch repassa o header em toda chamada de saída
05
O worker de push roda num laço iniciado no boot, fora de qualquer requisição: correlationBind captura o contexto ao enfileirar e o reaplica no job
06
Filtrar os logs por um id reconstrói a operação; o requestId mostra em qual chamada cada linha aconteceu

Trade-offs

O que se ganha, o que se paga

4 vantagenscada ganho tem um preço4 custos

Vantagens

Custa um UUID e um header
Qualquer agregador de log filtra por ele
O cliente recebe o id para abrir chamado com ele
Id recebido é validado antes de ir ao log

Custos

Não mede latência por salto: para isso, tracing distribuído
Todo serviço e toda chamada de saída precisam propagar, ou a cadeia quebra
Job fora da requisição perde o contexto se não for ligado a ele
Id inválido vindo de um parceiro é trocado e o vínculo com o sistema dele se perde

apps/observability/correlation-id

4 arquivos

src/

correlation.tsPlugin Elysia, validação do id, contexto, log, fetch de saída e bind para jobs
services_pix.tsGateway, pagamentos e notificações com worker de push
config_correlation.tsConfiguração validada do ambiente
demo.tsdemoTrês PIX concorrentes, logs misturados e filtro por id

Executar · só Bun