Registry / observability / opentelemetry-propagator-gcp

opentelemetry-propagator-gcp

JSON →
library1.15.0pypypi✓ verified 27d ago

The `opentelemetry-propagator-gcp` library provides a TextMapPropagator for OpenTelemetry that handles the Google Cloud Trace context header (`x-cloud-trace-context`). It allows OpenTelemetry traces to be linked with existing traces in Google Cloud, facilitating interoperability. This library is part of the `opentelemetry-operations-python` project, is actively maintained, and follows a regular release cadence, typically monthly or bi-monthly, aligned with other OpenTelemetry SDK updates.

pip install opentelemetry-propagator-gcp
INSTALL
IMPORT
SIG · OPENTELEMETRY-PROP
O
opentelemetry-propagator-gcp
observabilitypythonv1.15.0
Install
1.7s avg
Import
—
Disk
17MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v1.15.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 18.8MB
glibc
py 3.10–3.95 runs
installs and imports cleanly · install 1.7s · import 0.000s · 19MB
17MB installed
● package 17MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

CloudTracePropagator
✓ from opentelemetry.propagators.gcp import CloudTracePropagator
✗ from opentelemetry.propagators.gcp import CloudTracePropagator

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'
Debug
Known issues
gotchaThe `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.
affects: All versions
gotchaBy 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()])`.
affects: All versions
breakingThis 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`.
affects: 1.11.0+
gotchaThe `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.
affects: All versions
Upgrade
Version history
1.15.0latest on PyPI · released Aug 19, 2026
Audit
Dependencies
opentelemetry-apirequiredProvides core OpenTelemetry tracing API interfaces required by the propagator.
Agent activity
21 hits · last 30 days
node
18
OpenAI (training)
1
Resources
opentelemetry-propagator-gcp — pip install opentelemetry-propagator-gcp · libregistry