Google Cloud Propagator for OpenTelemetry

Warnings

• gotcha The `CloudTracePropagator` must be registered with the global OpenTelemetry propagator using `opentelemetry.propagators.set_global_textmap_propagator`. Failing to do so will prevent automatic context propagation for GCP trace headers.
  Fix: Ensure `propagators.set_global_textmap_propagator(CompositePropagator([CloudTracePropagator(), ...]))` is called early in your application's lifecycle, before any tracing occurs.
• gotcha By default, OpenTelemetry SDKs often use W3C Trace Context propagators. To support both W3C and Google Cloud Trace Context, you must use a `CompositePropagator` to include `CloudTracePropagator` alongside other desired propagators (e.g., `W3CTraceContextPropagator`).
  Fix: When setting the global propagator, construct a `CompositePropagator` like: `CompositePropagator([CloudTracePropagator(), W3CTraceContextPropagator()])`.
• breaking This package has strict version dependencies on `opentelemetry-api` and potentially `opentelemetry-sdk`. Mismatched versions with other OpenTelemetry packages can lead to runtime errors or unexpected behavior, especially with recent changes to logging exporters.
  Fix: Always install `opentelemetry-propagator-gcp` alongside the rest of your OpenTelemetry dependencies, ensuring all are compatible. Consult the `opentelemetry-operations-python` repository for recommended dependency versions or constraints in `pyproject.toml`.
• gotcha The `CloudTracePropagator` specifically handles the `x-cloud-trace-context` header. It does not parse or inject other Google Cloud-specific headers that might contain trace information (e.g., in gRPC metadata), nor does it support legacy X-Google-Tracing headers.
  Fix: Be aware that only `x-cloud-trace-context` is handled for HTTP propagation. For other protocols or legacy systems, custom propagators or manual context handling might be required.

Install

• pip install opentelemetry-propagator-gcp Install latest version

Imports

• CloudTracePropagator

  from opentelemetry.propagators.gcp import CloudTracePropagator

• set_global_textmap_propagator

  from opentelemetry import propagators

  Used to register the propagator globally.

Quickstart

This quickstart demonstrates how to register the `CloudTracePropagator` and then use the global `TextMapPropagator` to extract trace context from incoming headers and inject it into outgoing headers. This is crucial for maintaining trace continuity across services within and outside Google Cloud.

from opentelemetry import propagators
from opentelemetry.propagators.gcp import CloudTracePropagator
from opentelemetry.propagators.composite import CompositePropagator
from opentelemetry.trace import set_tracer_provider, get_tracer_provider
from opentelemetry.sdk.trace import TracerProvider

# 1. Set a TracerProvider (required for context to be active for injection)
set_tracer_provider(TracerProvider())

# 2. Register the CloudTracePropagator globally
#    Often combined with W3CTraceContextPropagator for broader compatibility.
propagators.set_global_textmap_propagator(
    CompositePropagator([
        CloudTracePropagator(),
        # Add W3CTraceContextPropagator() here if you also need W3C Trace Context
    ])
)

# --- Example: Extracting context from an incoming request ---
# Simulate an incoming request with 'x-cloud-trace-context' header
incoming_headers = {
    "x-cloud-trace-context": "105445aa78532f73a8123c72b2600000/0000000000000001;o=1"
}

# Extract the context using the globally registered propagator
context = propagators.get_global_textmap_propagator().extract(incoming_headers)

print(f"Extracted context from incoming headers: {context}")

# --- Example: Injecting context for an outgoing request ---
outgoing_headers = {}

# Create an active span to ensure there's a trace context to inject
tracer = get_tracer_provider().get_tracer(__name__)
with tracer.start_as_current_span("my-root-span"):
    # Inject the current trace context into outgoing headers
    propagators.get_global_textmap_propagator().inject(outgoing_headers)

print(f"Injected headers for outgoing request: {outgoing_headers}")

# Expected output for outgoing_headers will contain 'x-cloud-trace-context'