Decodificador traceparent — W3C Trace Context
Pare de contar dígitos hex. Decodificador traceparent grátis e online — roda no seu navegador, sem envio. Trace ID, span ID, 8 bits trace-flags, tracestate, Datadog/X-Ray/B3.
- Version
00- Trace ID
4bf92f3577b34da6a3ce929d0e0e4736- Parent ID (span ID)
00f067aa0ba902b7- Trace flags
01
| Bit | Máscara | Nome | Estado |
|---|---|---|---|
| 0 | 0x01 | sampled | 1 |
| 1 | 0x02 | random-trace-id | 0 |
| 2 | 0x04 | reservado | 0 |
| 3 | 0x08 | reservado | 0 |
| 4 | 0x10 | reservado | 0 |
| 5 | 0x20 | reservado | 0 |
| 6 | 0x40 | reservado | 0 |
| 7 | 0x80 | reservado | 0 |
Leia isto com um AND bit a bit. Comparar o byte inteiro com 01 reporta errado qualquer trace que carregue também um bit reservado.
- x-datadog-trace-id
11803532876627986230- x-datadog-tags: _dd.p.tid
4bf92f3577b34da6- x-datadog-parent-id
67667974448284343- Trace ID do AWS X-Ray
1-4bf92f35-77b34da6a3ce929d0e0e4736- b3 (single header)
4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-1- X-B3-TraceId
4bf92f3577b34da6a3ce929d0e0e4736- X-B3-SpanId
00f067aa0ba902b7- X-B3-Sampled
1
O Datadog leva os 64 bits inferiores do trace ID como string decimal e os 64 superiores em hex numa tag. Passar o valor de 128 bits inteiro como decimal é o motivo clássico de um trace ID dos seus logs não achar nada na UI.
Um ID do X-Ray embute um timestamp de 32 bits; um trace ID do W3C não carrega timestamp nenhum. A data abaixo só faz sentido se o identificador tiver mesmo nascido no X-Ray.
| # | Chave | Valor | Status |
|---|---|---|---|
| 1 | rojo | 00f067aa0ba902b7 | OK |
| 2 | congo | t61rcWkgMzE | OK |
Formato traceparent: anatomia dos campos
| Campo | Dígitos hex | Bytes | Significado | Valor inválido |
|---|---|---|---|---|
| version | 2 | 1 | Versão do formato. Sempre 00 hoje; ff é proibido. | ff |
| trace-id | 32 | 16 | Identifica o trace inteiro de ponta a ponta. | Todos zeros |
| parent-id | 16 | 8 | Identifica o span que chamou, não a requisição. | Todos zeros |
| trace-flags | 2 | 1 | Um campo de 8 bits — leia bit a bit, nunca como booleano. | — |
Valores de trace-flags: 00, 01, 02 e 03 explicados
| Hex | Binário | sampled | random-trace-id | Significado |
|---|---|---|---|---|
| 00 | 00000000 | 0 | 0 | O upstream escolheu não amostrar — olhe para quem chamou, não para o seu serviço. |
| 01 | 00000001 | 1 | 0 | Registrado normalmente. É o que você vê na maior parte do tempo. |
| 02 | 00000010 | 0 | 1 | Trace ID aleatório declarado, mas não amostrado. |
| 03 | 00000011 | 1 | 1 | Registrado, e o trace ID é declarado uniformemente aleatório. |
bit 0 — Quem chamou registrou este trace. Limpo significa que escolheu deliberadamente não registrar.
bit 1 — Level 2: os 7 bytes mais à direita do trace ID são uniformemente aleatórios.
bit 2-7 — Reservado. Deve ser ignorado e limpo nas requisições de saída.
Construído diretamente sobre a recomendação W3C Trace Context e a candidate recommendation do Level 2, com o parser coberto por testes unitários para cada forma válida e inválida que a especificação nomeia.
O que é o cabeçalho traceparent?
traceparent é o cabeçalho HTTP que leva um rastreamento distribuído de um serviço para o seguinte. Antes da padronização, cada fornecedor de tracing propagava contexto no próprio cabeçalho, então uma requisição que cruzasse sistemas perdia a identidade na fronteira. A especificação W3C Trace Context resolveu isso com um formato único e propositalmente pequeno: version-trace-id-parent-id-trace-flags, quatro campos hexadecimais unidos por hífens, 55 caracteres no total na versão atual.
Cada campo faz uma coisa só. O version é sempre 00 hoje, e ff é proibido de saída. O trace-id tem 16 bytes e identifica a requisição inteira de ponta a ponta — ele permanece constante em todos os saltos. O parent-id tem 8 bytes e identifica o span de quem chamou, então, ao contrário do trace-id, muda a cada salto. O byte trace-flags é onde mora quase toda a confusão: parece um booleano porque 01 é de longe o valor mais comum, mas são oito bits. O bit 0 é sampled. O bit 1, acrescentado no Trace Context Level 2, é random-trace-id e afirma que os sete bytes mais à direita do trace ID são uniformemente aleatórios, de modo que sistemas downstream possam amostrar ou fazer sharding sobre eles. Os seis bits restantes são reservados, e é exatamente por isso que o campo precisa ser lido com um AND bit a bit em vez de comparado por igualdade.
Um cabeçalho companheiro, tracestate, carrega ao lado dele pares chave-valor específicos de cada fornecedor, limitados a 32 membros. Esse teto explica um sintoma intrigante: dados de fornecedor que estão presentes na borda e somem alguns saltos depois, porque os intermediários começaram a descartar entradas assim que a lista passou do limite. O cabeçalho se tornou realmente universal quando o OpenTelemetry o adotou, e esta página decodifica tudo — campos, bits, membros do tracestate e os identificadores equivalentes de outros formatos de propagação — sem mandar nada para lugar nenhum.
# The header as it travels on the wire
traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
tracestate: rojo=00f067aa0ba902b7,congo=t61rcWkgMzE
# Read the four fields apart
# version 00
# trace-id 4bf92f3577b34da6a3ce929d0e0e4736 (16 bytes, whole request)
# parent-id 00f067aa0ba902b7 (8 bytes, calling span)
# trace-flags 01 (bit 0 set = sampled)
# Send one yourself
$ curl -H 'traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01' \
https://example.com/api Recursos principais
Cada campo separado e copiável
Version, trace-id, parent-id e trace-flags ganham cada um sua linha e seu botão de copiar, então levar um trace ID de 32 caracteres para uma consulta é um clique em vez de um arrasto cuidadoso.
trace-flags lidas como oito bits
O byte de flags é expandido nas oito posições com suas máscaras hexadecimais. O bit 0 é sampled, o bit 1 é a flag random-trace-id do Level 2, e os bits reservados são mostrados em vez de descartados em silêncio.
Conversão para Datadog, X-Ray e B3
Os 64 bits inferiores como trace ID decimal do Datadog, os 64 superiores como a tag que viaja junto, a forma 1-{8}-{24} do X-Ray e os dois layouts do B3, de cabeçalho único e múltiplo — tudo calculado com BigInt para nada estourar.
Diagnósticos, não só veredictos
Um trace ID todo zerado é explicado como tracing que nunca inicializou; um bit sampled limpo é explicado como decisão tomada upstream. Saber qual dos dois você está olhando costuma ser a sessão de depuração inteira.
tracestate com o teto de 32 membros
Os membros são listados com validação de chave e valor um a um e uma contagem corrente contra o limite da especificação — o limite que explica por que dados de fornecedor somem alguns saltos adiante.
Nada sai do seu navegador
A análise é manipulação de strings e aritmética BigInt, sem dependências e sem chamadas de rede, verificada por um teste de contrato automatizado a cada build. O copiar link usa o fragmento da URL, que nunca é transmitido.
Exemplos de traceparent, decodificados
O exemplo da própria especificação, decodificado
00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
version 00 · trace-id 4bf92f3577b34da6a3ce929d0e0e4736 · parent-id 00f067aa0ba902b7 · trace-flags 01 (sampled)
Quatro campos separados por hífen, 55 caracteres no total na versão 00. O trace-id identifica a requisição inteira enquanto ela atravessa todos os serviços; o parent-id — muitas vezes chamado de span ID — identifica apenas quem chamou você agora, e é por isso que ele muda a cada salto enquanto o trace-id não muda. O 01 no final é um byte inteiro, não um booleano: o bit 0 está setado, então quem chamou registrou este trace.
trace-flags 00 — quem chamou decidiu não registrar
00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00
Cabeçalho válido · bit sampled limpo
Este cabeçalho é perfeitamente válido, e é justamente esse o ponto. Um bit sampled limpo é uma instrução vinda de cima, não um defeito no seu serviço: quem chamou você avaliou o próprio sampler e escolheu não registrar. Caçar spans faltantes na sua configuração aqui custa horas. A pergunta certa é qual serviço está chamando você, enviando um span pai e decidindo não amostrar o trace.
Um trace ID todo zerado significa que o tracing nunca começou
00-00000000000000000000000000000000-00f067aa0ba902b7-01
Inválido — trace-id todo zerado
A especificação declara inválido um trace-id todo zerado e exige que o traceparent inteiro seja ignorado. Vale saber o que isso sinaliza na prática: não "um trace que ainda não tem dados", mas um SDK que nunca foi inicializado ou um middleware injetando um cabeçalho de fachada. A mesma regra vale para um parent-id todo zerado.
O mesmo trace ID no formato do Datadog
00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
x-datadog-trace-id 11803532876627986230 · _dd.p.tid 4bf92f3577b34da6
O Datadog leva os 64 bits inferiores de um trace ID de 128 bits como string decimal, e os 64 bits superiores em hexadecimal numa tag separada. Passe o valor de 128 bits inteiro como decimal e você obtém um número que não casa com nada — que é exatamente por que essa conversão reaparece sem parar nos issue trackers dos tracers. A metade inferior aqui é a3ce929d0e0e4736, e 64 bits ultrapassam o que um number do JavaScript aguenta, então esta página faz a aritmética com BigInt.
Como usar o decodificador traceparent
- 1
Cole o cabeçalho traceparent
Jogue o valor bruto do cabeçalho — por exemplo 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01. A decodificação acontece enquanto você digita; não há botão para apertar.
- 2
Leia os quatro campos separados
Version, trace-id, parent-id e trace-flags são divididos em linhas próprias, cada uma com botão de copiar, então você tira só o trace ID para uma consulta sem selecionar 32 caracteres na mão.
- 3
Confira as flags bit a bit
O byte trace-flags é expandido nos oito bits com suas máscaras, então sampled e a flag random-trace-id do Level 2 ficam visíveis individualmente em vez de escondidos dentro de um valor de dois caracteres.
- 4
Converta para o formato do seu backend
Datadog, AWS X-Ray e as duas formas do B3 são gerados logo abaixo, incluindo o trace ID decimal dos 64 bits inferiores que o Datadog espera e a tag dos 64 bits superiores que viaja junto.
- 5
Adicione o tracestate e compartilhe o resultado
Cole um cabeçalho tracestate para listar seus membros com validação individual e contagem contra o limite de 32 membros, depois use copiar link para capturar o estado exato numa URL que você pode colar num ticket.
Erros comuns com traceparent
Comparar o byte de flags inteiro com 01
Isso trata um campo de oito bits como uma enumeração. Um trace que é amostrado e também carrega a flag random-trace-id do Level 2 tem flags 03, e a comparação de igualdade o reporta como não amostrado.
if (traceFlags === 0x01) { record(); } if (traceFlags & 0x01) { record(); } Converter os 128 bits todos em um número decimal
O Datadog espera os 64 bits inferiores em decimal e os 64 superiores em hexadecimal numa tag separada. Passar o valor inteiro como um único número decimal produz um identificador que não casa com nada.
x-datadog-trace-id: 100985939111033328018442752961257817910
x-datadog-trace-id: 11803532876627986230 x-datadog-tags: _dd.p.tid=4bf92f3577b34da6
Rejeitar qualquer versão que não seja 00
A especificação pede que os parsers leiam o que reconhecem de uma versão maior e tolerem campos extras no fim. Rejeitar de cara reinicia o trace e quebra o vínculo na fronteira.
if (version !== '00') throw new Error('bad traceparent'); if (version !== '00' && header.length >= 55) { /* parse the known prefix */ } Emitir hexadecimal maiúsculo
A gramática admite apenas minúsculas. Um trace ID em maiúsculas carrega o valor certo e ainda assim é rejeitado por um receptor conforme, o que faz dele um bug particularmente frustrante de enxergar a olho nu.
traceparent: 00-4BF92F3577B34DA6A3CE929D0E0E4736-00F067AA0BA902B7-01
traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
O que dá para fazer com o decodificador traceparent
- Descobrir por que um trace não tem spans
- Cole o cabeçalho recebido e leia o bit sampled. Se ele estiver limpo, o trace nunca seria registrado e a resposta está com quem chamou, não com a sua instrumentação — uma distinção que poupa muito tempo auditando a sua própria configuração de sampler.
- Achar um trace que o seu backend não acha
- Quando um trace ID copiado dos logs da aplicação não retorna nada no Datadog, o formato costuma ser o culpado. Converta aqui para ver o identificador decimal dos 64 bits inferiores que a API espera, junto com a tag dos 64 bits superiores que precisa acompanhá-lo.
- Verificar os cabeçalhos que o seu gateway injeta
- Proxies e service meshes geram contexto de trace na entrada. Cole o que realmente chegou para conferir comprimento, hexadecimal minúsculo e identificadores não zerados antes de supor que a culpa é de quem vem depois.
- Reproduzir um trace de produção na mão
- Pegue um cabeçalho de uma requisição real e reproduza-o contra um endpoint de staging para seguir o mesmo trace. Monte a requisição com o construtor de comandos curl e cole o cabeçalho direto nele.
- Explicar trace context para um time
- As tabelas de anatomia dos campos e de trace-flags desta página são material de referência estático para você apontar, e os chips de exemplo demonstram cada modo de falha sem ninguém precisar quebrar um serviço para produzi-lo.
Como funciona o validador de W3C Trace Context
- A gramática de quatro campos
- version "-" trace-id "-" parent-id "-" trace-flags, tudo em hexadecimal minúsculo. Version tem 2 dígitos, trace-id 32, parent-id 16 e trace-flags 2 — 52 dígitos hexadecimais mais 3 hífens, exatamente 55 caracteres na versão 00. Hexadecimal maiúsculo invalida o cabeçalho mesmo que o valor pareça correto, e tanto um trace-id todo zerado quanto um parent-id todo zerado são explicitamente inválidos, não vazios.
- trace-flags é um campo de bits
- O bit 0 (máscara 0x01) é sampled: setado significa que quem chamou pode ter registrado dados do trace. O bit 1 (máscara 0x02), introduzido no Level 2, é random-trace-id: quando setado, pelo menos os 7 bytes mais à direita do trace-id precisam ter sido escolhidos aleatoriamente com distribuição uniforme, o que permite a sistemas downstream amostrar ou fazer sharding sobre eles. Os bits 2 a 7 são reservados e devem ser ignorados na recepção e limpos nas requisições de saída. Como bits reservados podem estar presentes, o campo precisa ser testado com um AND bit a bit — uma comparação de igualdade com 0x01 reporta errado um trace amostrado que também carrega um bit reservado.
- Compatibilidade com versões futuras
- Version é 00 hoje e ff é proibido, mas um parser que rejeita todo o resto está errado. A especificação pede que os receptores tentem interpretar quando a versão for maior e o cabeçalho tiver pelo menos o comprimento do formato conhecido, lendo os campos que reconhecem e tolerando dados extras no fim, em vez de reiniciar o trace. Este decodificador segue essa regra: uma versão futura é interpretada com sucesso e sinalizada como aviso, não como erro.
- Limites do tracestate que doem em produção
- No máximo 32 list-members — é um limite gramatical rígido, então uma lista mais longa torna o cabeçalho inválido e os receptores o descartam. Cada chave tem no máximo 256 caracteres e começa por letra minúscula ou dígito; desde o Level 2, o @ é um caractere de chave comum e não mais um separador de tenant. Cada valor tem de 1 a 256 caracteres ASCII imprimíveis, nunca com vírgula ou sinal de igual. Chaves duplicadas são inválidas, mas list-members vazios são explicitamente permitidos — a vírgula final deixada por um intermediário que removeu uma entrada ainda forma um cabeçalho válido. À parte disso, os fornecedores deveriam propagar pelo menos 512 caracteres do cabeçalho combinado; quando precisam podar para caber nesse orçamento, as entradas com mais de 128 caracteres devem cair primeiro — e é por isso que os dados de um fornecedor verboso somem antes dos de um conciso.
Boas práticas de Trace Context
- Teste as flags com um AND bit a bit
- Escreva flags & 0x01 em vez de flags == 0x01. Seis dos oito bits estão reservados para uso futuro, e uma comparação de igualdade vai começar a reportar traces amostrados errado assim que qualquer um deles aparecer por aí.
- Trate um ID todo zerado como pipeline quebrado
- Não é um valor vazio a ser tolerado. Rejeite o cabeçalho e vá atrás do componente que falhou em inicializar o tracer ou que está injetando um valor de fachada.
- Olhe para cima quando o bit sampled estiver limpo
- Samplers baseados no pai propagam a decisão de quem chamou. Se faltam traces, identifique qual serviço está lhe enviando um span pai com a amostragem desligada antes de auditar a sua própria configuração.
- Mantenha o tracestate curto
- O teto de 32 membros é um limite gramatical rígido — passou dele, o cabeçalho é inválido. À parte disso, apenas 512 caracteres do cabeçalho combinado têm propagação garantida, e a poda derruba primeiro as entradas com mais de 128 caracteres. Nada que precise sobreviver a uma cadeia longa de chamadas pertence ao tracestate.
- Nunca registre um trace ID como number do JavaScript
- Um trace ID de 128 bits e até um identificador Datadog de 64 bits passam do Number.MAX_SAFE_INTEGER. Guarde-os como strings e converta com BigInt quando precisar de aritmética, ou você vai corromper os últimos dígitos em silêncio.
Perguntas frequentes sobre o decodificador traceparent
O que é o cabeçalho traceparent?
O que significa traceparent com trace-flags 00?
Qual a diferença entre trace-flags 01, 02 e 03?
Por que meu trace ID está todo zerado?
Como converter um trace ID do W3C para um trace ID do Datadog?
Um traceparent contém um timestamp?
O cabeçalho que eu colo aqui é enviado para algum lugar?
Este decodificador funciona offline?
Ferramentas relacionadas
Ver todas as ferramentas →Gerador e Construtor de Comandos cURL
Web & API
Monte comandos curl no navegador — defina método, cabeçalhos, autenticação e corpo, obtenha um comando pronto para copiar instantaneamente. Presets para Bearer, POST JSON e upload. Grátis, privado, sem cadastro.
Gerador htpasswd — bcrypt, Apache MD5 (apr1) e Basic Auth
Web & API
Gere entradas htpasswd com bcrypt, Apache MD5 (apr1), SHA-1 e mais. Obtenha configuracoes prontas para Apache, nginx e Docker. 100% no seu navegador — sem upload.
Gerador de Meta Tags e Open Graph
Web & API
Gere meta tags de Open Graph, Twitter Card e SEO com prévia ao vivo do Google, Facebook e X. 100% grátis, no navegador, sem cadastro — copie e cole o código.
Testador de nginx location — por que esse bloco vence
Web & API
Qual bloco location do nginx vence — e por que os outros perderam. Testador gratuito para =, ^~, ~ e ~*, tudo no seu navegador.
Ferramenta de Descriptografia AES — OpenSSL e CryptoJS
Ferramentas de Segurança
Descriptografe AES online — GCM/CBC/CTR, frase-senha ou chave bruta, detecta automaticamente o formato "U2FsdGVkX1" do OpenSSL e CryptoJS. 100% no navegador, as chaves nunca saem da página.
Ferramenta de Criptografia AES — GCM, CBC e CTR
Ferramentas de Segurança
Criptografia AES online e gratuita — AES-128/192/256, GCM/CBC/CTR, frase-senha (PBKDF2) ou chave bruta. Roda 100% no navegador; nada é enviado a um servidor.