Skip to content

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.

Sem rastreamento Roda no navegador Grátis
Tudo é decodificado localmente no seu navegador — os cabeçalhos que você cola nunca saem deste dispositivo. Abra o painel Network e veja-o permanecer em silêncio, ou fique totalmente offline.
Teste um exemplo
Detalhamento dos campos
Version
00
Trace ID
4bf92f3577b34da6a3ce929d0e0e4736
Parent ID (span ID)
00f067aa0ba902b7
Trace flags
01
trace-flags, bit a bit
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.

Outros formatos de propagação
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.

Membros do tracestate 2/32
# Chave Valor Status
1 rojo 00f067aa0ba902b7 OK
2 congo t61rcWkgMzE OK

Formato traceparent: anatomia dos campos

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

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.

Larguras dos campos, valores inválidos, semântica dos bits de flag e limites do tracestate desta página foram conferidos contra o texto publicado da especificação, e não contra resumos de terceiros. — Equipe de Engenharia da Go Tools · Jul 22, 2026

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. 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. 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. 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. 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. 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.

✗ Incorreto
if (traceFlags === 0x01) { record(); }
✓ Correto
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.

✗ Incorreto
x-datadog-trace-id: 100985939111033328018442752961257817910
✓ Correto
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.

✗ Incorreto
if (version !== '00') throw new Error('bad traceparent');
✓ Correto
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.

✗ Incorreto
traceparent: 00-4BF92F3577B34DA6A3CE929D0E0E4736-00F067AA0BA902B7-01
✓ Correto
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 único cabeçalho HTTP que leva um rastreamento distribuído através das fronteiras entre serviços, padronizado pelo W3C para que ferramentas de fornecedores diferentes consigam acompanhar a mesma requisição. Ele guarda quatro campos separados por hífen — version, trace-id, parent-id e trace-flags — e, na versão atual, tem sempre exatamente 55 caracteres. Todo sistema de tracing relevante hoje fala esse formato, e é isso que torna uma requisição rastreável de um proxy de borda até meia dúzia de serviços sem que cada salto precise concordar com um fornecedor. A gramática completa está definida na recomendação W3C Trace Context.
O que significa traceparent com trace-flags 00?
Significa que quem chamou decidiu explicitamente que este trace não deve ser registrado. O bit sampled é o bit 0 do byte trace-flags; quando ele está limpo, um sampler upstream avaliou a requisição e optou por não registrá-la. Esse é o valor mais mal lido do cabeçalho, porque parece uma falha e na verdade é uma decisão. Se faltam spans, a pergunta útil não é o que está quebrado no seu serviço, mas qual serviço upstream está lhe enviando um span pai com a amostragem desligada — um sampler baseado no pai propaga essa escolha para tudo que vem depois.
Qual a diferença entre trace-flags 01, 02 e 03?
trace-flags é um campo de oito bits, então esses valores são combinações e não uma enumeração. 01 seta só o bit 0: o trace é amostrado. 02 seta só o bit 1: a flag random-trace-id do Level 2, que afirma que pelo menos os sete bytes mais à direita do trace ID foram gerados com aleatoriedade uniforme — sistemas downstream podem então amostrar ou fazer sharding sobre esses bytes com segurança. 03 seta os dois. Como é um campo de bits, você precisa testá-lo com um AND bit a bit; comparar o byte inteiro com 01 vai reportar errado qualquer trace que carregue também um bit reservado, e são justamente os bits reservados que as versões futuras vão começar a usar.
Por que meu trace ID está todo zerado?
Porque o tracing nunca foi inicializado, e não porque o trace existe mas está sem dados. A especificação lista um trace-id todo zerado como valor inválido e manda os receptores ignorarem o cabeçalho inteiro, então nada downstream vai se ligar a ele. Na prática isso vem de um SDK que não subiu, de um cabeçalho montado à mão ou de um middleware inserindo um valor de fachada quando não havia contexto real. O parent-id todo zerado, 0000000000000000, é inválido pelo mesmo motivo.
Como converter um trace ID do W3C para um trace ID do Datadog?
Pegue os 64 bits inferiores — os 16 dígitos hexadecimais da direita — e represente-os como string decimal; é isso que vai em x-datadog-trace-id. Os 64 bits superiores continuam em hexadecimal e viajam à parte na tag _dd.p.tid. O parent-id converte para decimal inteiro. Inverter isso, ou converter os 128 bits todos em um único número decimal, produz um identificador que não casa com nada na UI, e é por isso que o assunto se repete nos issue trackers dos tracers. Esta página faz a separação para você; se quiser explorar a aritmética hexadecimal por trás disso em valores arbitrários, o conversor de bases numéricas cobre conversão de base em geral, enquanto esta página fica específica para identificadores de trace.
Um traceparent contém um timestamp?
Não — e isso confunde bastante gente, porque alguns outros identificadores de trace contêm. Um trace-id do W3C são 16 bytes opacos, sem tempo embutido. Já um trace ID do AWS X-Ray é 1-{8 hex}-{24 hex}, em que os oito primeiros dígitos hexadecimais são o instante de criação em segundos de época; converter entre os dois formatos reorganiza os bytes, mas não inventa um timestamp que nunca existiu. Se você precisa de identificadores que realmente ordenam por tempo, é para isso que servem UUIDv7 e ULID.
O cabeçalho que eu colo aqui é enviado para algum lugar?
Não. Cada campo é interpretado localmente no seu navegador, com manipulação de strings e aritmética BigInt — não há chamada a servidor, não há log do que você digita e nada fica retido. Isso importa mais aqui do que na maioria das ferramentas, porque um traceparent tirado de uma requisição de produção identifica tráfego real no seu backend de observabilidade. Você não precisa acreditar na nossa palavra: abra as ferramentas de desenvolvedor do navegador e veja o painel Network permanecer em silêncio enquanto você digita, ou desconecte-se totalmente da rede e continue decodificando. A ausência de qualquer requisição externa também é garantida por um teste de contrato automatizado que roda a cada build, então isso não regride em silêncio.
Este decodificador funciona offline?
Sim. A página é estática e o decodificador são alguns kilobytes de JavaScript sem dependências, então, uma vez carregado, você pode ficar offline — ou ligar o modo avião antes de colar qualquer coisa — e ele continua funcionando exatamente igual. Se você lida com cabeçalhos de um ambiente sensível, essa é a sequência que vale a pena usar: carregue a página, desconecte, depois cole. O botão de copiar link codifica o estado no fragmento da URL, depois do caractere #, e fragmentos também nunca são transmitidos a um servidor.

Ferramentas relacionadas

Ver todas as ferramentas →