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. 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.
Some AWS services include a Self segment, generated
when the service itself is the entry point. 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.
Note
The "X-" naming convention for HTTP headers, "X" referring to "experimental", has been deprecated and needs to be transitioned to the formal naming convention for HTTP headers.
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.
Self
The Self segment follows the same format as Root.
The segment appears in the wild on API Gateway
responses but is absent from current AWS X-Ray
documentation, so its exact semantics are unconfirmed.
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
Some services generate both Self and Root
segments when the service is the trace entry point.
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