Logs & Observability
Cole um header traceparent para ver version, trace-id, parent-id e flags decodificados campo a campo, ou mude para o modo em lote ou o modo de geração.
Análise e geração acontecem inteiramente no seu navegador. Nada é enviado para um servidor ou backend de rastreamento.
Um header traceparent parece simples — quatro campos separados por hífen — até que um microsserviço registre uma requisição com trace-id todo zerado, ou um proxy reescreva silenciosamente o byte de versão para um valor que a especificação proíbe explicitamente. Este analisador de traceparent verifica o header contra a gramática real do W3C Trace Context em vez de apenas olhar para os hífens, permitindo diferenciar um header realmente quebrado de um que só parece incomum.
Use quando um trace distribuído some entre dois serviços e você precisa saber se o header em si já era válido, quando está implementando propagação manual de headers e precisa de um exemplo para testar, ou quando está revisando logs e precisa decodificar vários valores traceparent de uma vez em vez de um por um.
Feito para encontrar bugs reais de header, não só para exibir bonito um header que já era válido.
Este analisador de traceparent divide um header em version, trace-id, parent-id e trace-flags, cada um em uma cor, além de uma leitura em linguagem simples do byte de flags (se está amostrado ou não, e se algum bit reservado está ativado sem esperar).
Version ff, trace-id todo zerado e parent-id todo zerado parecem hexadecimal válido, mas o W3C Trace Context os proíbe explicitamente — este analisador de traceparent aponta cada um pelo nome, em vez de só checar tamanho e conjunto de caracteres.
Três coisas úteis de saber antes de colar um header vindo de logs de produção.
A análise roda automaticamente 300ms depois que você para de digitar — nenhum botão é necessário a menos que a análise automática seja desligada. Os três exemplos não são aleatórios: carregam um header válido, um com version ff e um com trace-id todo zerado, os três casos de borda que a especificação cita explicitamente.
O campo tracestate fica recolhido por padrão porque nem todo header carrega um — ative-o para validar os pares vendor=value contra os limites da especificação (32 membros, 256 caracteres). Se quiser revisar uma exportação de logs inteira em vez de um único header, mude para o modo em lote e cole um traceparent por linha.
Um header version 00 é totalmente validado; qualquer versão acima é decodificada, mas os campos extras são exibidos como estão, nunca interpretados. Copiar e baixar ficam desativados assim que você edita a entrada, para nunca exportar por acidente um resultado desatualizado.
Validação real do W3C Trace Context, não uma regex que só confere a posição dos hífens.
Version, trace-id, parent-id e trace-flags são analisados e identificados individualmente, com uma leitura em linguagem simples do bit de amostragem.
Rejeita version ff, trace-id todo zerado, parent-id todo zerado, tamanhos de campo errados e hexadecimal em maiúsculas — exatamente os casos que uma regex frouxa costuma deixar passar.
Cole um trecho inteiro de logs com valores traceparent e receba uma contagem de válidos/inválidos/vazios, além do campo exato que falhou em cada linha com erro.
Valida os membros key=value contra o conjunto de caracteres da especificação, o formato tenant@vendor, o limite de 256 caracteres por valor, o teto de 32 membros e a regra contra keys duplicadas.
Gera um traceparent version 00 com trace-id e parent-id aleatórios, criptograficamente seguros e garantidamente diferentes de zero, para você nunca testar por acidente com um valor de placeholder inválido.
Leia antes de assumir que um resultado verde significa que seu pipeline de rastreamento está saudável.
Dúvidas reais que aparecem ao depurar headers W3C Trace Context.
trace-flags é um único byte escrito como dois caracteres hexadecimais; o bit 0 é a flag sampled. 01 significa que quem chamou recomenda que esse trace seja registrado pelo backend de rastreamento, 00 significa o contrário — é uma recomendação passada ao longo da cadeia de chamadas, não uma garantia de que algum sistema realmente capturou o trace.
O trace-id identifica de forma única todo o trace distribuído e é compartilhado por todos os serviços pelos quais a requisição passa. O span-id (chamado de parent-id na especificação W3C) identifica um trecho específico dessa cadeia e geralmente muda a cada serviço, mesmo compartilhando o mesmo trace-id.
O traceparent carrega os quatro campos obrigatórios — version, trace-id, parent-id e trace-flags — que todo sistema compatível com o W3C precisa entender. O tracestate é opcional, com dados key=value específicos de cada fornecedor, que um sistema de rastreamento pode anexar sem exigir que outros sistemas os entendam.
A especificação W3C Trace Context reserva ff para que nunca seja confundida com um número de versão futuro — ela é explicitamente proibida não importa quão correto esteja formatado o resto do header. Este analisador a rejeita pelo nome em vez de tratá-la como uma version hexadecimal qualquer.
Um trace-id todo zerado não consegue identificar nada, então a especificação o proíbe diretamente, mesmo que "32 zeros" passe em uma checagem ingênua de formato hexadecimal. A mesma regra vale para um parent-id (span-id) todo zerado.
Primeiro analise aqui para ver exatamente qual campo está falhando e por quê. A maioria dos problemas reais vem de um proxy ou pipeline de logs que trunca o header, mistura hexadecimal em maiúsculas, ou encaminha por engano um valor de modelo como todo zero em vez de um ID realmente gerado.
Encontrou um header que este analisador avalia errado?
Analise um header traceparent, valide vários em lote, ou gere um novo header de teste — tudo no seu navegador, sem enviar nada.
Salve nos favoritos para a próxima vez que um trace sumir entre dois serviços.
Parte da categoria Developer Tools & DevOps no HeyUtils.