X-Amzn-Trace-Id
The HTTP X-Amzn-Trace-Id unofficial request and response header carries the AWS X-Ray trace identifier, enabling distributed tracing as requests flow through load balancers, API gateways, and backend services on AWS.
Usage
AWS services inject the X-Amzn-Trace-Id header to track requests as they flow through distributed systems. Application Load Balancers (ALB), API Gateway, and other AWS services generate or propagate this header automatically. The trace ID follows a request from the edge through backend services, enabling end-to-end latency analysis and error correlation.
The header value contains a Root segment identifying
the entire trace. Additional segments like
Parent and Sampled appear when AWS X-Ray
instrumentation is active. Segments are separated by
semicolons, as in Root=...;Parent=...;Sampled=1.
The Root value encodes
a version number, a timestamp, and a unique identifier
separated by hyphens. The Parent value references
the immediate upstream span. The Sampled flag
controls whether X-Ray records the trace data.
An Application Load Balancer receiving a trace
header with an existing Root inserts a Self
segment before forwarding, marking its own hop in
an already-started trace. A
Lineage segment appears in certain configurations to
track trace propagation depth. Services behind
CloudFront distributions often include this header
alongside X-Amz-Cf-Id for complete
request tracing across CDN and origin infrastructure.
The header serves a role comparable to the X-Cloud-Trace-Context header used by Google Cloud for distributed tracing, and relates conceptually to X-Request-Id for general request identification. ALBs also add X-Forwarded-For alongside the trace header to preserve the original client IP.
Values
Root
The Root segment is always present and follows
the format
Root=1-[8-hex-timestamp]-[24-hex-unique-id]. The
leading 1 is the format version. The hex timestamp
represents the Unix epoch time when the trace started.
The 24-character hexadecimal string is a globally
unique identifier.
Parent
The Parent segment contains a 16-character
hexadecimal span identifier referencing the
immediate upstream service in the trace chain. This
value appears when X-Ray-instrumented services
propagate the trace.
Sampled
The Sampled segment is 0 or 1, indicating
whether X-Ray collects detailed trace data for this
request. A value of 0 means the trace is not
recorded. A value of 1 means the trace is actively
sampled and stored. Instrumented clients send
Sampled=? to ask the first X-Ray-aware hop to make
the sampling decision.
Self
The Self segment follows the same format as Root.
AWS documents the segment for Application Load
Balancers: when an incoming request already carries
a Root field, the load balancer inserts Self
and forwards the request, so the segment marks a
forwarding hop rather than the trace origin.
Lineage
The Lineage segment appears in some traced
requests, for example Lineage=25:a87bd80c:1. AWS
documents the segment as internal metadata appended
by X-Ray and advises against using the value
directly. The field semantics are unpublished.
Example
A simple trace ID from an Application Load Balancer
or API Gateway includes the Root segment with a
version, timestamp, and unique identifier.
X-Amzn-Trace-Id: Root=1-699c68b7-6328e823661ca179d803faed
When X-Ray instrumentation is active, the header
includes Parent and Sampled segments alongside
the root. The Parent value identifies the upstream
span, and Sampled=0 indicates this trace is not
being recorded.
X-Amzn-Trace-Id: Root=1-6948674b-037f6986563dbf74040038ad;Parent=3ac2f14f529dbc1a;Sampled=0;Lineage=1:c55dac1d:0
A load balancer forwarding an already-traced
request emits both Self and Root segments.
X-Amzn-Trace-Id: Self=1-69456e5f-5e18bc5165d5f9c67069e3e3;Root=1-69456e5f-43a55f186b8b1a5f4deaef8b
A typical AWS-hosted response includes the trace ID alongside other AWS-specific HTTP headers for complete request correlation.
X-Amzn-Trace-Id: Root=1-69706a25-61f9fc9a4dc36f1737cfff87;Parent=4315d27ab3cdf789;Sampled=0
X-Amz-Cf-Id: rEZ41zHijmTaPJrLdiavv7oU8giHtH8HQXvabc2QPAly_Btvu5C2Dw==
Content-Type: text/html