traceparent-Dekodierer — W3C Trace Context

Was ist der traceparent-Header?

# 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

Wichtige Funktionen

traceparent-Beispiele, dekodiert

00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01

version 00 · trace-id 4bf92f3577b34da6a3ce929d0e0e4736 · parent-id 00f067aa0ba902b7 · trace-flags 01 (sampled)

00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00

Gültiger Header · sampled-Bit nicht gesetzt

00-00000000000000000000000000000000-00f067aa0ba902b7-01

Ungültig — trace-id besteht nur aus Nullen

00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01

x-datadog-trace-id 11803532876627986230 · _dd.p.tid 4bf92f3577b34da6

So verwenden Sie den traceparent-Dekodierer

1. 1

   traceparent-Header einfügen

   Fügen Sie den rohen Header-Wert ein — zum Beispiel 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01. Dekodiert wird beim Tippen; es gibt keinen Button zu drücken.

2. 2

   Die vier Felder getrennt lesen

   Version, trace-id, parent-id und trace-flags stehen in eigenen Zeilen, jede mit Kopieren-Button, sodass Sie nur die Trace-ID in eine Query übernehmen können, ohne 32 Zeichen von Hand zu markieren.

3. 3

   Die Flags Bit für Bit prüfen

   Das trace-flags-Byte wird in alle acht Bits samt Masken aufgeklappt, sodass sampled und das random-trace-id-Flag aus Level 2 einzeln sichtbar sind statt in einem zweistelligen Wert versteckt.

4. 4

   In das Format Ihres Backends umrechnen

   Darunter entstehen Datadog, AWS X-Ray und beide B3-Varianten, einschließlich der dezimalen Trace-ID aus den unteren 64 Bit, die Datadog erwartet, und des Tags mit den oberen 64 Bit, das sie begleitet.

5. 5

   tracestate ergänzen und Ergebnis teilen

   Fügen Sie einen tracestate-Header ein, um seine Mitglieder mit Einzelvalidierung und Zählung gegen das 32er-Limit zu sehen, und halten Sie den exakten Zustand mit „Link kopieren“ in einer URL fest, die Sie in ein Ticket schreiben können.

Häufige Fehler bei traceparent

if (traceFlags === 0x01) { record(); }

if (traceFlags & 0x01) { record(); }

x-datadog-trace-id: 100985939111033328018442752961257817910

x-datadog-trace-id: 11803532876627986230
x-datadog-tags: _dd.p.tid=4bf92f3577b34da6

if (version !== '00') throw new Error('bad traceparent');

if (version !== '00' && header.length >= 55) { /* parse the known prefix */ }

traceparent: 00-4BF92F3577B34DA6A3CE929D0E0E4736-00F067AA0BA902B7-01

traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01

Was Sie mit dem traceparent-Dekodierer machen können

Herausfinden, warum ein Trace keine Spans hat

Fügen Sie den eingehenden Header ein und lesen Sie das sampled-Bit. Ist es nicht gesetzt, wäre der Trace ohnehin nie aufgezeichnet worden, und die Antwort liegt beim Aufrufer, nicht bei Ihrer Instrumentierung — eine Unterscheidung, die viel Zeit beim Prüfen der eigenen Sampler-Konfiguration spart.

Einen Trace finden, den Ihr Backend nicht findet

Wenn eine aus den Anwendungslogs kopierte Trace-ID in Datadog nichts liefert, liegt es meist am Format. Rechnen Sie sie hier um und sehen Sie den dezimalen Bezeichner aus den unteren 64 Bit, den die API erwartet, samt dem Tag mit den oberen 64 Bit, das ihn begleiten muss.

Header prüfen, die Ihr Gateway einsetzt

Proxys und Service Meshes erzeugen Trace-Kontext beim Eintritt. Fügen Sie ein, was tatsächlich angekommen ist, und bestätigen Sie Länge, kleingeschriebenes Hexadezimal und Bezeichner ungleich null, bevor Sie den Fehler weiter unten vermuten.

Einen Produktions-Trace von Hand reproduzieren

Nehmen Sie einen Header aus einer echten Anfrage und spielen Sie ihn gegen einen Staging-Endpunkt, um demselben Trace zu folgen. Bauen Sie die Anfrage mit dem curl-Command-Builder und fügen Sie den Header direkt ein.

Trace Context im Team erklären

Die Tabellen zum Feldaufbau und zu den trace-flags auf dieser Seite sind statisches Referenzmaterial, auf das Sie zeigen können, und die Beispiel-Chips führen jeden Fehlerfall vor, ohne dass jemand einen Dienst kaputtmachen muss.

So funktioniert der W3C-Trace-Context-Validator

Die Grammatik der vier Felder

version "-" trace-id "-" parent-id "-" trace-flags, durchgehend kleingeschriebenes Hexadezimal. Version hat 2 Ziffern, trace-id 32, parent-id 16 und trace-flags 2 — 52 Hex-Ziffern plus 3 Bindestriche, bei Version 00 also exakt 55 Zeichen. Großgeschriebenes Hexadezimal macht den Header ungültig, obwohl der Wert richtig aussieht, und sowohl eine trace-id als auch eine parent-id aus lauter Nullen sind ausdrücklich ungültig und nicht etwa leer.

trace-flags ist ein Bitfeld

Bit 0 (Maske 0x01) ist sampled: gesetzt heißt, der Aufrufer hat möglicherweise Trace-Daten aufgezeichnet. Bit 1 (Maske 0x02), eingeführt in Level 2, ist random-trace-id: Ist es gesetzt, müssen mindestens die rechten 7 Bytes der trace-id gleichverteilt zufällig gewählt worden sein, worauf nachgelagerte Systeme sampeln oder sharden dürfen. Die Bits 2 bis 7 sind reserviert, müssen beim Empfang ignoriert und bei ausgehenden Anfragen gelöscht werden. Weil reservierte Bits auftreten können, muss das Feld mit einem bitweisen UND geprüft werden — ein Gleichheitstest gegen 0x01 meldet einen gesampelten Trace falsch, der zusätzlich ein reserviertes Bit trägt.

Vorwärtskompatibilität mit künftigen Versionen

Version ist heute 00 und ff ist verboten, aber ein Parser, der alles andere ablehnt, liegt falsch. Die Spezifikation verlangt von Empfängern, bei höherer Version einen Parse-Versuch zu unternehmen, sofern der Header mindestens so lang ist wie das bekannte Format: die erkannten Felder lesen und zusätzliche Daten am Ende tolerieren, statt den Trace neu zu starten. Dieser Dekodierer hält sich daran — eine künftige Version wird erfolgreich geparst und als Warnung statt als Fehler markiert.

tracestate-Limits, die in Produktion zubeißen

Höchstens 32 Listenmitglieder — eine harte grammatikalische Grenze: Ist die Liste länger, ist der Header ungültig und Empfänger verwerfen ihn. Jeder Schlüssel ist höchstens 256 Zeichen lang und beginnt mit einem Kleinbuchstaben oder einer Ziffer; seit Level 2 ist das @ ein gewöhnliches Schlüsselzeichen und kein Mandantentrenner mehr. Jeder Wert besteht aus 1 bis 256 druckbaren ASCII-Zeichen, niemals mit Komma oder Gleichheitszeichen. Doppelte Schlüssel sind ungültig, leere Listenmitglieder dagegen ausdrücklich erlaubt — ein nachgestelltes Komma, das ein Zwischensystem beim Entfernen eines Eintrags hinterlässt, ergibt weiterhin einen gültigen Header. Davon getrennt gilt: Hersteller sollten mindestens 512 Zeichen des zusammengesetzten Headers weitergeben; wer kürzen muss, um in dieses Budget zu passen, sollte zuerst Einträge über 128 Zeichen streichen — deshalb verschwinden die Daten eines geschwätzigen Herstellers vor denen eines knappen.

Best Practices für Trace Context

Flags mit einem bitweisen UND prüfen

Schreiben Sie flags & 0x01 statt flags == 0x01. Sechs der acht Bits sind für künftige Verwendung reserviert, und ein Gleichheitstest meldet gesampelte Traces falsch, sobald eines davon in freier Wildbahn auftaucht.

Eine ID aus lauter Nullen als kaputte Pipeline behandeln

Das ist kein leerer Wert, den man tolerieren sollte. Lehnen Sie den Header ab und suchen Sie die Komponente, die ihren Tracer nicht initialisiert hat oder einen Platzhalter einsetzt.

Nach oben schauen, wenn das sampled-Bit nicht gesetzt ist

Parent-based Sampler geben die Entscheidung des Aufrufers weiter. Fehlen Traces, klären Sie zuerst, welcher Dienst Ihnen einen Parent-Span mit abgeschaltetem Sampling schickt, bevor Sie Ihre eigene Konfiguration durchgehen.

tracestate kurz halten

Die Obergrenze von 32 Mitgliedern ist eine harte grammatikalische Grenze — wird sie überschritten, ist der Header ungültig. Davon getrennt: Nur 512 Zeichen des zusammengesetzten Headers propagieren garantiert, und beim Kürzen fallen Einträge über 128 Zeichen zuerst weg. Was eine lange Aufrufkette überleben muss, gehört nicht in tracestate.

Eine Trace-ID nie als JavaScript-Zahl protokollieren

Eine 128-Bit-Trace-ID und selbst ein 64-Bit-Datadog-Bezeichner übersteigen beide Number.MAX_SAFE_INTEGER. Halten Sie sie als Strings und rechnen Sie mit BigInt, wenn es sein muss, sonst beschädigen Sie stillschweigend die letzten Stellen.

FAQ zum traceparent-Dekodierer