X-Cloud-Trace-Context
The HTTP X-Cloud-Trace-Context header is an unofficial request and response header used by Google Cloud Platform services for distributed request tracing.
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.
Note
The W3C Traceparent header is the modern, standardized replacement for proprietary trace context headers. Google Cloud services support Traceparent alongside X-Cloud-Trace-Context, and new integrations are encouraged to adopt the W3C format.
Usage
Google Cloud Platform services such as App Engine, Cloud Run, Cloud Functions, and GKE attach the X-Cloud-Trace-Context header to requests and responses flowing through their infrastructure. The header carries a trace identifier linking the request to a trace in Google Cloud Trace (formerly Stackdriver Trace), enabling operators to follow a single request across multiple services and measure latency at each hop.
The trace identifier is assigned at the edge when the request first enters Google's infrastructure. Downstream services propagate the same identifier, building a complete trace tree. The optional span ID and sampling flag provide finer granularity for correlating specific service calls within the trace.
Values
TRACE_ID
The TRACE_ID is a 32-character hexadecimal string uniquely
identifying the trace. This value links the request to a
trace record in Google Cloud Trace. When only the trace ID
is present, the header contains this single hex string.
SPAN_ID
The SPAN_ID is a decimal number identifying a specific
span within the trace. A span represents a single operation
or service call. The span ID appears after the trace ID,
separated by a forward slash (/).
o (trace flag)
The o field is a sampling flag indicating whether
the request was traced. A value of o=1 means the
trace was sampled and recorded. A value of o=0 means
the request was not sampled. This flag appears after
a semicolon following the trace ID or span ID.
Example
A response from a Google Cloud Run service includes the trace ID as a 32-character hex string. This value maps to a trace record in Google Cloud Trace for latency analysis and request correlation.
X-Cloud-Trace-Context: 9624e399eb0cc17ae6b37405f856dd4b
A response includes the full trace context with a trace ID,
span ID, and sampling flag. The span ID
10191370959649788700 identifies a specific operation within
the trace, and o=1 confirms the trace was actively sampled.
X-Cloud-Trace-Context: adc55b5586195e96ac291820f7a12ff0/10191370959649788700;o=1
A response carries a trace ID with the sampling flag but
no span ID. The o=1 flag indicates the request was sampled
for trace recording.
X-Cloud-Trace-Context: 83620bf1fa7bcda4f70d7ed8e1eb8f99;o=1
Takeaway
The X-Cloud-Trace-Context header carries distributed tracing identifiers for Google Cloud Platform services, linking requests to traces in Google Cloud Trace. The W3C Traceparent header is the standardized replacement, and Google Cloud services support both formats.