traceparent Decoder — W3C Trace Context

What Is the 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

Key Features

traceparent Examples, Decoded

00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01

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

00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00

Valid header · sampled bit clear

00-00000000000000000000000000000000-00f067aa0ba902b7-01

Invalid — all-zero trace-id

00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01

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

How to Use the traceparent Decoder

1. 1

   Paste the traceparent header

   Drop in the raw header value — for example 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01. Decoding happens as you type; there is no button to press.

2. 2

   Read the four fields apart

   Version, trace-id, parent-id and trace-flags are split into their own rows, each with a copy button, so you can lift just the trace ID into a query without hand-selecting 32 characters.

3. 3

   Check the flags bit by bit

   The trace-flags byte is expanded into all eight bits with their masks, so sampled and the Level 2 random-trace-id flag are visible individually rather than hidden inside a two-character value.

4. 4

   Convert to your backend's format

   Datadog, AWS X-Ray and both B3 forms are generated underneath, including the lower-64-bit decimal trace ID that Datadog expects and the higher-64-bit tag that travels alongside it.

5. 5

   Add tracestate and share the result

   Paste a tracestate header to list its members with per-member validation and a count against the 32-member limit, then use Copy link to capture the exact state in a URL you can drop into a ticket.

Common traceparent Mistakes

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

What You Can Do with the traceparent Decoder

Work out why a trace has no spans

Paste the incoming header and read the sampled bit. If it is clear, the trace was never going to be recorded and the answer lies with the caller, not with your instrumentation — a distinction that saves a great deal of time spent auditing your own sampler configuration.

Find a trace that your backend cannot

When a trace ID copied from application logs returns nothing in Datadog, the format is usually the culprit. Convert it here to see the lower-64-bit decimal identifier the API expects, along with the higher-64-bit tag that has to accompany it.

Verify headers your gateway injects

Proxies and service meshes generate trace context on the way in. Paste what actually arrived to confirm the length, lowercase hexadecimal and non-zero identifiers before assuming the fault is downstream.

Reproduce a production trace by hand

Take a header from a real request and replay it against a staging endpoint to follow the same trace through. Build the request with the curl command builder and paste the header straight into it.

Explain trace context to a team

The field anatomy and trace-flags tables on this page are static reference material you can point at, and the preset chips demonstrate each failure mode without anyone having to break a service to produce one.

How the W3C Trace Context Validator Works

The four-field grammar

version "-" trace-id "-" parent-id "-" trace-flags, all lowercase hexadecimal. Version is 2 digits, trace-id 32, parent-id 16 and trace-flags 2 — 52 hex digits plus 3 dashes, 55 characters exactly for version 00. Uppercase hexadecimal makes the header invalid even though the value looks correct, and both an all-zero trace-id and an all-zero parent-id are explicitly invalid rather than empty.

trace-flags is a bit field

Bit 0 (mask 0x01) is sampled: set means the caller may have recorded trace data. Bit 1 (mask 0x02), introduced in Level 2, is random-trace-id: when set, at least the right-most 7 bytes of the trace-id must have been chosen randomly with uniform distribution, which lets downstream systems sample or shard on them. Bits 2 to 7 are reserved and must be ignored on receipt and cleared on outbound requests. Because reserved bits can be present, the field must be tested with a bitwise AND — an equality check against 0x01 misreports a sampled trace that also carries a reserved bit.

Forward compatibility with future versions

Version is 00 today and ff is forbidden, but a parser that rejects everything else is wrong. The specification asks receivers to attempt parsing when the version is higher and the header is at least as long as the known format, reading the fields they recognise and tolerating extra trailing data, rather than restarting the trace. This decoder follows that rule: a future version parses successfully and is flagged as a warning rather than an error.

tracestate limits that bite in production

At most 32 list-members — a hard grammatical bound, so a longer list makes the header invalid and receivers discard it. Each key is at most 256 characters and begins with a lowercase letter or digit; since Level 2 the @ is an ordinary key character rather than a tenant separator. Each value is 1 to 256 printable ASCII characters, never a comma or an equals sign. Duplicate keys are invalid, and empty list-members are explicitly allowed — a trailing comma left behind when an intermediary removes an entry is still a valid header. Separately, vendors should propagate at least 512 characters of the combined header; when they have to trim to stay inside that budget, entries longer than 128 characters should go first, which is why a verbose vendor's data disappears before a terse one's.

Trace Context Best Practices

Test flags with a bitwise AND

Write flags & 0x01 rather than flags == 0x01. Six of the eight bits are reserved for future use, and an equality check will start misreporting sampled traces the moment any of them appears in the wild.

Treat an all-zero ID as a broken pipeline

It is not an empty value to be tolerated. Reject the header, and go and find the component that failed to initialise its tracer or is injecting a placeholder.

Look upstream when the sampled bit is clear

Parent-based samplers propagate the caller's decision. If traces are missing, identify which service is sending you a parent span with sampling off before auditing your own configuration.

Keep tracestate short

The 32-member ceiling is a hard grammatical bound — exceed it and the header is invalid. Separately, only 512 characters of the combined header are guaranteed to propagate, and trimming drops entries over 128 characters first. Anything that must survive a long call chain does not belong in tracestate.

Never log a trace ID as a JavaScript number

A 128-bit trace ID and even a 64-bit Datadog identifier both exceed Number.MAX_SAFE_INTEGER. Keep them as strings, and convert with BigInt when you have to do arithmetic, or you will silently corrupt the last digits.

traceparent Decoder FAQ