Trace context

This document briefly describes context, which refers to state, and to context propagation, which refers to passing state information to child operations. For distributed tracing, the trace ID and the ID of the span being processed must be passed to child operations.

Child operations create a span and set the following fields:

  • Span ID: A unique identifier for the child operation. If the same operation is executed multiple times, then there are multiple spans for that operation, each with a unique identifier.
  • Trace ID: The unique identifier of the end-to-end operation in which this particular overall operation took place. The value of this field is provided by the parent.
  • Parent span ID: The unique identifier of parent's span. The value of this field is provided by the parent. For root spans, this ID is null.

The values of the trace ID, span ID, and parent span ID fields let a distributed tracing system correctly link spans together to form a trace. For example, Cloud Trace stores spans in a repository, and it uses these ID fields to identify which spans compose a trace.

Context might include other state information that is useful for distributed tracing. For example, the World Wide Web Consortium (W3C) standard includes information about whether the parent span was sampled.

Protocols for context propagation

The following sections describe how specific request protocols propagate context.

HTTP requests

For HTTP requests, context propagation is typically accomplished through HTTP headers such as the traceparent and tracestate headers, which were standardized by W3C. Google Cloud services that support trace context propagation typically support both the traceparent and the legacy X-Cloud-Trace-Context header.

When possible, we recommend that you use the traceparent header in your applications. Your application might need to use the legacy X-Cloud-Trace-Context header or it might need to support receiving trace context in a different format.

If you have an application that only supports the X-Cloud-Trace-Context header, then we recommend that you update your application to support, and prioritize, the traceparent header. Your application can continue to use the X-Cloud-Trace-Context header as a fallback solution.

The following table summarizes some significant differences between the two headers:

Attribute traceparent
header		 X-Cloud-Trace-Context
header
Separators hyphens (-) forward slash (/) and semicolon (;)
Span ID
representation		 Hexadecimal Decimal

Legacy X-Cloud-Trace-Context header

The X-Cloud-Trace-Context header that is used by Google Cloud predates the W3C specification. For backwards compatibility, some Google Cloud services continue to accept, generate, and propagate the X-Cloud-Trace-Context header. However, it is likely that these systems also support the traceparent header.

The X-Cloud-Trace-Context header has the following format:

X-Cloud-Trace-Context: TRACE_ID/SPAN_ID;o=OPTIONS

The fields of header are defined as follows:

  • TRACE_ID is a 32-character hexadecimal value representing a 128-bit number.
  • SPAN_ID is a 64-bit decimal representation of the unsigned span ID.
  • OPTIONS supports 0 (parent not sampled) and 1 (parent was sampled).

gRPC requests

For gRPC requests, context propagation is accomplished using gRPC metadata, which is implemented on top of HTTP headers. gRPC applications might use the traceparent header or a metadata context key called grpc-trace-bin.

For components that you own, we recommend that you use the traceparent header.

Context propagation for Google Cloud services

Google Cloud services might act as initiators or intermediaries in request processing. For example, the following services are known to participate in processing requests:

Support for trace context initiation and propagation is dependent on the particular Google Cloud service. To request that a Google Cloud service add support for context propagation, use the Google Issue Tracker.

Context propagation in your applications

Some instrumentation libraries, such as OpenTelemetry, can propagate a context object that contains the data necessary for tracing. For a list of OpenTelemetry libraries that support tracing, see Language APIs & SDKs.

If you rely on an open-source library, then determine whether context propagation is available and whether configuration is required. For example, if you use OpenTelemetry to instrument a Go app, then your app should call SetTextMapPropagator, which configures the context to use the W3C traceparent format. For an instrumentation example, see Generate traces and metrics with Go.

When there isn't a suitable instrumentation library, you must ensure that your application propagates the trace context to child operations.

What's next