Decodificatore traceparent — W3C Trace Context
Basta contare cifre hex. Decodificatore traceparent online e gratuito — gira nel browser, niente upload. Trace ID, span ID, 8 bit trace-flags, tracestate, Datadog/X-Ray/B3.
- Version
00- Trace ID
4bf92f3577b34da6a3ce929d0e0e4736- Parent ID (span ID)
00f067aa0ba902b7- Trace flags
01
| Bit | Maschera | Nome | Stato |
|---|---|---|---|
| 0 | 0x01 | sampled | 1 |
| 1 | 0x02 | random-trace-id | 0 |
| 2 | 0x04 | riservato | 0 |
| 3 | 0x08 | riservato | 0 |
| 4 | 0x10 | riservato | 0 |
| 5 | 0x20 | riservato | 0 |
| 6 | 0x40 | riservato | 0 |
| 7 | 0x80 | riservato | 0 |
Leggili con un AND bit a bit. Confrontare l'intero byte con 01 segnala male qualsiasi traccia che porti anche un bit riservato.
- x-datadog-trace-id
11803532876627986230- x-datadog-tags: _dd.p.tid
4bf92f3577b34da6- x-datadog-parent-id
67667974448284343- Trace ID AWS X-Ray
1-4bf92f35-77b34da6a3ce929d0e0e4736- b3 (single header)
4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-1- X-B3-TraceId
4bf92f3577b34da6a3ce929d0e0e4736- X-B3-SpanId
00f067aa0ba902b7- X-B3-Sampled
1
Datadog trasporta i 64 bit bassi del trace ID come stringa decimale e i 64 alti in esadecimale in un tag. Passare l'intero valore a 128 bit come decimale è il motivo classico per cui un trace ID preso dai log non trova nulla nell'interfaccia.
Un ID X-Ray incorpora un timestamp a 32 bit; un trace ID W3C non porta alcun timestamp. La data qui sotto ha senso solo se l'identificatore è nato davvero in X-Ray.
| # | Chiave | Valore | Stato |
|---|---|---|---|
| 1 | rojo | 00f067aa0ba902b7 | OK |
| 2 | congo | t61rcWkgMzE | OK |
Formato traceparent: anatomia dei campi
| Campo | Cifre hex | Byte | Significato | Valore non valido |
|---|---|---|---|---|
| version | 2 | 1 | Versione del formato. Oggi sempre 00; ff è vietato. | ff |
| trace-id | 32 | 16 | Identifica l'intera traccia da un capo all'altro. | Tutti zeri |
| parent-id | 16 | 8 | Identifica lo span chiamante, non la richiesta. | Tutti zeri |
| trace-flags | 2 | 1 | Un campo a 8 bit — leggilo bit per bit, mai come booleano. | — |
Valori di trace-flags: 00, 01, 02 e 03 spiegati
| Hex | Binario | sampled | random-trace-id | Significato |
|---|---|---|---|---|
| 00 | 00000000 | 0 | 0 | Chi sta a monte ha scelto di non campionare — guarda il chiamante, non il tuo servizio. |
| 01 | 00000001 | 1 | 0 | Registrata normalmente. È ciò che vedi quasi sempre. |
| 02 | 00000010 | 0 | 1 | Trace ID casuale dichiarato, ma non campionata. |
| 03 | 00000011 | 1 | 1 | Registrata, e il trace ID è dichiarato uniformemente casuale. |
bit 0 — Il chiamante ha registrato questa traccia. Azzerato significa che ha scelto deliberatamente di non farlo.
bit 1 — Level 2: i 7 byte più a destra del trace ID sono uniformemente casuali.
bit 2-7 — Riservato. Va ignorato e azzerato nelle richieste in uscita.
Costruito direttamente sulla raccomandazione W3C Trace Context e sulla candidate recommendation di Level 2, con il parser coperto da test unitari per ogni forma valida e non valida citata dalla specifica.
Che cos'è l'header traceparent?
traceparent è l'header HTTP che porta una traccia distribuita da un servizio al successivo. Prima della standardizzazione ogni fornitore di tracing propagava il contesto in un header proprio, così una richiesta che attraversava sistemi diversi perdeva la propria identità al confine. La specifica W3C Trace Context ha risolto la cosa con un formato unico e volutamente minuto: version-trace-id-parent-id-trace-flags, quattro campi esadecimali uniti da trattini, 55 caratteri in tutto nella versione attuale.
Ogni campo fa una cosa sola. Il version oggi è sempre 00, e ff è vietato del tutto. Il trace-id è di 16 byte e identifica l'intera richiesta da un capo all'altro: resta costante a ogni hop. Il parent-id è di 8 byte e identifica lo span di chi ha chiamato, quindi, a differenza del trace-id, cambia a ogni hop. Il byte trace-flags è dove vive quasi tutta la confusione: sembra un booleano perché 01 è di gran lunga il valore più comune, ma sono otto bit. Il bit 0 è sampled. Il bit 1, aggiunto in Trace Context Level 2, è random-trace-id e afferma che i sette byte più a destra del trace ID sono uniformemente casuali, così i sistemi a valle possono campionare o fare sharding su di essi. I sei bit rimanenti sono riservati, ed è precisamente per questo che il campo va letto con un AND bit a bit anziché confrontato per uguaglianza.
Un header gemello, tracestate, trasporta accanto a esso coppie chiave-valore specifiche del fornitore, con un tetto di 32 membri. Quel limite spiega un sintomo sconcertante: dati del fornitore presenti al bordo e spariti qualche hop più avanti, perché gli intermediari hanno iniziato a scartare voci una volta che la lista ha superato il limite. L'header è diventato davvero universale quando OpenTelemetry lo ha adottato, e questa pagina decodifica tutto — campi, bit, membri di tracestate e gli identificatori equivalenti degli altri formati di propagazione — senza inviare nulla da nessuna parte.
# 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 Caratteristiche principali
Ogni campo separato e copiabile
Version, trace-id, parent-id e trace-flags hanno ciascuno la propria riga e il proprio pulsante di copia, così portare un trace ID di 32 caratteri in una query richiede un clic invece di una selezione col mouse.
trace-flags letti come otto bit
Il byte dei flag viene espanso in tutte e otto le posizioni con le maschere esadecimali. Il bit 0 è sampled, il bit 1 è il flag random-trace-id di Level 2, e i bit riservati vengono mostrati anziché scartati in silenzio.
Conversione verso Datadog, X-Ray e B3
I 64 bit bassi come trace ID decimale per Datadog, i 64 alti come tag che lo accompagna, la forma X-Ray 1-{8}-{24} e i layout B3 sia a header singolo sia multiplo — tutto calcolato con BigInt, così niente va in overflow.
Diagnosi, non solo verdetti
Un trace ID tutto a zeri viene spiegato come tracing mai inizializzato; un bit sampled azzerato viene spiegato come decisione presa a monte. Capire quale dei due hai davanti è di solito l'intera sessione di debug.
tracestate con il tetto di 32 membri
I membri sono elencati con validazione di chiave e valore uno per uno e un conteggio progressivo rispetto al limite della specifica — il limite che spiega perché i dati del fornitore svaniscono pochi hop più a valle.
Niente esce dal tuo browser
L'analisi è fatta di semplici operazioni su stringhe e aritmetica BigInt, senza dipendenze e senza chiamate di rete, verificata da un test di contratto automatico a ogni build. Copia link usa il frammento dell'URL, che non viene mai trasmesso.
Esempi di traceparent, decodificati
L'esempio della specifica stessa, decodificato
00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
version 00 · trace-id 4bf92f3577b34da6a3ce929d0e0e4736 · parent-id 00f067aa0ba902b7 · trace-flags 01 (sampled)
Quattro campi separati da trattino, 55 caratteri in tutto per la versione 00. Il trace-id identifica l'intera richiesta mentre attraversa ogni servizio; il parent-id — spesso chiamato span ID — identifica solo chi ti ha chiamato adesso, ed è per questo che cambia a ogni hop mentre il trace-id resta lo stesso. Lo 01 finale è un byte intero, non un booleano: il bit 0 è impostato, quindi il chiamante ha registrato questa traccia.
trace-flags 00 — il chiamante ha deciso di non registrare
00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00
Header valido · bit sampled azzerato
Questo header è perfettamente valido, ed è proprio questo il punto. Un bit sampled azzerato è un'istruzione che arriva da monte, non un difetto del tuo servizio: chi ti ha chiamato ha valutato il proprio sampler e ha scelto di non registrare. Cercare gli span mancanti nella tua configurazione, qui, costa ore. La domanda giusta è quale servizio ti sta chiamando, inviando uno span padre e decidendo di non campionare la traccia.
Un trace ID tutto a zeri significa che il tracing non è mai partito
00-00000000000000000000000000000000-00f067aa0ba902b7-01
Non valido — trace-id tutto a zeri
La specifica dichiara non valido un trace-id tutto a zeri e impone di ignorare l'intero traceparent. Vale la pena sapere che cosa segnala nella pratica: non "una traccia che non ha ancora dati", ma un SDK mai inizializzato oppure un middleware che inietta un header segnaposto. La stessa regola vale per un parent-id tutto a zeri.
Lo stesso trace ID nel formato di Datadog
00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
x-datadog-trace-id 11803532876627986230 · _dd.p.tid 4bf92f3577b34da6
Datadog trasporta i 64 bit bassi di un trace ID a 128 bit come stringa decimale, e i 64 bit alti in esadecimale in un tag separato. Passa l'intero valore a 128 bit come decimale e ottieni un numero che non corrisponde a nulla — ed è esattamente per questo che la conversione ricompare di continuo negli issue tracker dei tracer. Qui la metà bassa è a3ce929d0e0e4736, e 64 bit superano ciò che un number JavaScript può contenere, quindi questa pagina fa i conti con BigInt.
Come usare il decodificatore traceparent
- 1
Incolla l'header traceparent
Inserisci il valore grezzo dell'header — per esempio 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01. La decodifica avviene mentre scrivi; non c'è nessun pulsante da premere.
- 2
Leggi i quattro campi separati
Version, trace-id, parent-id e trace-flags vengono divisi in righe proprie, ciascuna con un pulsante di copia, così puoi prelevare solo il trace ID per una query senza selezionare a mano 32 caratteri.
- 3
Controlla i flag bit per bit
Il byte trace-flags viene espanso in tutti e otto i bit con le rispettive maschere, così sampled e il flag random-trace-id di Level 2 sono visibili singolarmente invece di restare nascosti in un valore di due caratteri.
- 4
Converti nel formato del tuo backend
Datadog, AWS X-Ray ed entrambe le forme di B3 vengono generati qui sotto, compresi il trace ID decimale dei 64 bit bassi che Datadog si aspetta e il tag dei 64 bit alti che lo accompagna.
- 5
Aggiungi tracestate e condividi il risultato
Incolla un header tracestate per elencarne i membri con validazione singola e un conteggio rispetto al limite di 32 membri, poi usa Copia link per catturare lo stato esatto in un URL da inserire in un ticket.
Errori comuni con traceparent
Confrontare l'intero byte dei flag con 01
Così si tratta un campo a otto bit come un'enumerazione. Una traccia campionata che porta anche il flag random-trace-id di Level 2 ha flags 03, e il confronto di uguaglianza la segnala come non campionata.
if (traceFlags === 0x01) { record(); } if (traceFlags & 0x01) { record(); } Convertire tutti i 128 bit in un unico numero decimale
Datadog si aspetta i 64 bit bassi in decimale e i 64 alti in esadecimale in un tag separato. Passare il valore intero come un solo numero decimale produce un identificatore che non corrisponde a nulla.
x-datadog-trace-id: 100985939111033328018442752961257817910
x-datadog-trace-id: 11803532876627986230 x-datadog-tags: _dd.p.tid=4bf92f3577b34da6
Rifiutare qualsiasi versione diversa da 00
La specifica chiede ai parser di leggere ciò che riconoscono di una versione più alta e di tollerare campi in coda. Rifiutare a priori fa ripartire la traccia e rompe il collegamento al confine.
if (version !== '00') throw new Error('bad traceparent'); if (version !== '00' && header.length >= 55) { /* parse the known prefix */ } Emettere esadecimale maiuscolo
La grammatica ammette solo il minuscolo. Un trace ID in maiuscolo porta il valore giusto e viene comunque rifiutato da un destinatario conforme, il che lo rende un bug particolarmente frustrante da individuare a occhio.
traceparent: 00-4BF92F3577B34DA6A3CE929D0E0E4736-00F067AA0BA902B7-01
traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
Che cosa puoi fare con il decodificatore traceparent
- Capire perché una traccia non ha span
- Incolla l'header in ingresso e leggi il bit sampled. Se è azzerato, la traccia non sarebbe mai stata registrata e la risposta sta dal chiamante, non nella tua strumentazione — una distinzione che fa risparmiare parecchio tempo speso a controllare la configurazione del tuo sampler.
- Trovare una traccia che il tuo backend non trova
- Quando un trace ID copiato dai log applicativi non restituisce nulla in Datadog, di solito il colpevole è il formato. Convertilo qui per vedere l'identificatore decimale dei 64 bit bassi che l'API si aspetta, insieme al tag dei 64 bit alti che deve accompagnarlo.
- Verificare gli header iniettati dal gateway
- Proxy e service mesh generano contesto di traccia in ingresso. Incolla ciò che è arrivato davvero per confermare lunghezza, esadecimale minuscolo e identificatori non nulli prima di dare la colpa a chi sta a valle.
- Riprodurre a mano una traccia di produzione
- Prendi un header da una richiesta reale e rigiocalo contro un endpoint di staging per seguire la stessa traccia. Costruisci la richiesta con il generatore di comandi curl e incollaci dentro l'header così com'è.
- Spiegare il trace context a un team
- Le tabelle sull'anatomia dei campi e sui trace-flags di questa pagina sono materiale di riferimento statico da mostrare, e i chip preimpostati dimostrano ogni modalità di errore senza che nessuno debba rompere un servizio per produrla.
Come funziona il validatore W3C Trace Context
- La grammatica a quattro campi
- version "-" trace-id "-" parent-id "-" trace-flags, tutto in esadecimale minuscolo. Version è di 2 cifre, trace-id di 32, parent-id di 16 e trace-flags di 2 — 52 cifre esadecimali più 3 trattini, esattamente 55 caratteri per la versione 00. L'esadecimale maiuscolo rende l'header non valido anche se il valore sembra corretto, e sia un trace-id tutto a zeri sia un parent-id tutto a zeri sono esplicitamente non validi, non vuoti.
- trace-flags è un campo di bit
- Il bit 0 (maschera 0x01) è sampled: impostato significa che il chiamante può aver registrato dati di traccia. Il bit 1 (maschera 0x02), introdotto in Level 2, è random-trace-id: quando è impostato, almeno i 7 byte più a destra del trace-id devono essere stati scelti a caso con distribuzione uniforme, il che permette ai sistemi a valle di campionare o fare sharding su di essi. I bit da 2 a 7 sono riservati e vanno ignorati in ricezione e azzerati nelle richieste in uscita. Poiché i bit riservati possono essere presenti, il campo va testato con un AND bit a bit — un confronto di uguaglianza con 0x01 segnala male una traccia campionata che porta anche un bit riservato.
- Compatibilità con le versioni future
- Version oggi è 00 e ff è vietato, ma un parser che rifiuta tutto il resto sbaglia. La specifica chiede ai destinatari di provare ad analizzare quando la versione è più alta e l'header è almeno lungo quanto il formato noto, leggendo i campi riconosciuti e tollerando dati extra in coda, invece di far ripartire la traccia. Questo decodificatore segue la regola: una versione futura viene analizzata correttamente e segnalata come avviso, non come errore.
- Limiti di tracestate che mordono in produzione
- Al massimo 32 list-member: è un vincolo grammaticale rigido, quindi una lista più lunga rende l'header non valido e i destinatari lo scartano. Ogni chiave è al massimo di 256 caratteri e inizia con una lettera minuscola o una cifra; dal Level 2 la @ è un normale carattere di chiave e non più un separatore di tenant. Ogni valore è di 1-256 caratteri ASCII stampabili, mai con una virgola o un segno di uguale. Le chiavi duplicate non sono valide, mentre i list-member vuoti sono esplicitamente ammessi: la virgola finale lasciata da un intermediario che ha rimosso una voce forma ancora un header valido. A parte questo, i fornitori dovrebbero propagare almeno 512 caratteri dell'header combinato; quando devono sfoltire per rientrare in quel budget, le voci più lunghe di 128 caratteri vanno via per prime — ed è per questo che i dati di un fornitore prolisso spariscono prima di quelli di uno conciso.
Buone pratiche di Trace Context
- Testa i flag con un AND bit a bit
- Scrivi flags & 0x01 invece di flags == 0x01. Sei degli otto bit sono riservati a usi futuri, e un confronto di uguaglianza inizierà a segnalare male le tracce campionate nel momento in cui uno di essi comparirà davvero.
- Tratta un ID tutto a zeri come una pipeline rotta
- Non è un valore vuoto da tollerare. Rifiuta l'header e vai a cercare il componente che non è riuscito a inizializzare il tracer o che sta iniettando un segnaposto.
- Guarda a monte quando il bit sampled è azzerato
- I sampler basati sul padre propagano la decisione del chiamante. Se mancano tracce, individua quale servizio ti sta inviando uno span padre con il campionamento spento prima di controllare la tua configurazione.
- Tieni tracestate corto
- Il tetto di 32 membri è un vincolo grammaticale rigido: superarlo rende l'header non valido. A parte questo, solo 512 caratteri dell'header combinato hanno la propagazione garantita, e lo sfoltimento elimina per prime le voci oltre i 128 caratteri. Tutto ciò che deve sopravvivere a una lunga catena di chiamate non appartiene a tracestate.
- Non registrare mai un trace ID come number JavaScript
- Un trace ID a 128 bit e perfino un identificatore Datadog a 64 bit superano Number.MAX_SAFE_INTEGER. Tienili come stringhe e converti con BigInt quando devi fare aritmetica, altrimenti corromperai in silenzio le ultime cifre.
Domande frequenti sul decodificatore traceparent
Che cos'è l'header traceparent?
Che cosa significa traceparent con trace-flags 00?
Qual è la differenza fra trace-flags 01, 02 e 03?
Perché il mio trace ID è tutto a zeri?
Come converto un trace ID W3C in un trace ID Datadog?
Un traceparent contiene un timestamp?
L'header che incollo qui viene caricato da qualche parte?
Questo decodificatore funziona offline?
Strumenti correlati
Vedi tutti gli strumenti →Generatore e costruttore di comandi cURL
Web & API
Crea comandi curl nel browser — imposta metodo, intestazioni, autenticazione e corpo, ottieni subito il comando pronto da copiare. Preset per Bearer, POST JSON, upload file. Gratuito, privato, senza registrazione.
Generatore htpasswd — bcrypt, Apache MD5 (apr1) e Basic Auth
Web & API
Genera voci htpasswd con bcrypt, Apache MD5 (apr1), SHA-1 e altro. Ottieni configurazioni pronte per Apache, nginx e Docker. 100% nel browser — nessun caricamento.
Generatore di Meta Tag e Open Graph
Web & API
Genera meta tag Open Graph, Twitter Card e SEO con anteprima live per Google, Facebook e X. Gratis, nel browser, senza registrazione — copia e incolla.
Tester nginx location — perché vince quel blocco
Web & API
Scopri quale blocco location di nginx vince e perché gli altri perdono. Tester online gratuito per =, ^~, ~ e ~*, tutto dentro il browser.
Strumento di Decifratura AES — OpenSSL e CryptoJS
Strumenti di sicurezza
Decifra AES online — GCM/CBC/CTR, passphrase o chiave grezza, rileva "U2FsdGVkX1" (OpenSSL/CryptoJS). 100% nel browser, le chiavi restano sul dispositivo.
Strumento di Crittografia AES — GCM, CBC e CTR
Strumenti di sicurezza
Crittografia AES online gratuita — AES-128/192/256, GCM/CBC/CTR, passphrase (PBKDF2) o chiave grezza. Funziona al 100% nel browser; nulla viene caricato.