X-Amzn-Trace-Id

The HTTP X-Amzn-Trace-Id request and response header is an unofficial, AWS-specific header containing the AWS X-Ray trace identifier for distributed tracing across AWS services.

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.

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 and identifies the trace entry point when the responding service is the originator of the trace.

Lineage

The Lineage segment tracks trace propagation metadata in the format [depth]:[hex-identifier]:[count]. This helps AWS monitor trace depth across service boundaries.

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

Takeaway

The X-Amzn-Trace-Id header carries distributed tracing information across AWS services, enabling end-to-end request tracking through X-Ray instrumentation, load balancers, and API gateways.

See also

• X-Amz-Cf-Id
• X-Request-Id
• X-Forwarded-For
• HTTP headers