{"id":4157,"library":"opentelemetry-propagator-gcp","title":"Google Cloud Propagator for OpenTelemetry","description":"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.","status":"active","version":"1.11.0","language":"en","source_language":"en","source_url":"https://github.com/GoogleCloudPlatform/opentelemetry-operations-python/tree/main/opentelemetry-propagator-gcp","tags":["opentelemetry","gcp","google-cloud","propagation","tracing","x-cloud-trace-context"],"install":[{"cmd":"pip install opentelemetry-propagator-gcp","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Provides core OpenTelemetry tracing API interfaces required by the propagator.","package":"opentelemetry-api","optional":false}],"imports":[{"symbol":"CloudTracePropagator","correct":"from opentelemetry.propagators.gcp import CloudTracePropagator"},{"note":"Used to register the propagator globally.","symbol":"set_global_textmap_propagator","correct":"from opentelemetry import propagators"}],"quickstart":{"code":"from opentelemetry import propagators\nfrom opentelemetry.propagators.gcp import CloudTracePropagator\nfrom opentelemetry.propagators.composite import CompositePropagator\nfrom opentelemetry.trace import set_tracer_provider, get_tracer_provider\nfrom opentelemetry.sdk.trace import TracerProvider\n\n# 1. Set a TracerProvider (required for context to be active for injection)\nset_tracer_provider(TracerProvider())\n\n# 2. Register the CloudTracePropagator globally\n#    Often combined with W3CTraceContextPropagator for broader compatibility.\npropagators.set_global_textmap_propagator(\n    CompositePropagator([\n        CloudTracePropagator(),\n        # Add W3CTraceContextPropagator() here if you also need W3C Trace Context\n    ])\n)\n\n# --- Example: Extracting context from an incoming request ---\n# Simulate an incoming request with 'x-cloud-trace-context' header\nincoming_headers = {\n    \"x-cloud-trace-context\": \"105445aa78532f73a8123c72b2600000/0000000000000001;o=1\"\n}\n\n# Extract the context using the globally registered propagator\ncontext = propagators.get_global_textmap_propagator().extract(incoming_headers)\n\nprint(f\"Extracted context from incoming headers: {context}\")\n\n# --- Example: Injecting context for an outgoing request ---\noutgoing_headers = {}\n\n# Create an active span to ensure there's a trace context to inject\ntracer = get_tracer_provider().get_tracer(__name__)\nwith tracer.start_as_current_span(\"my-root-span\"):\n    # Inject the current trace context into outgoing headers\n    propagators.get_global_textmap_propagator().inject(outgoing_headers)\n\nprint(f\"Injected headers for outgoing request: {outgoing_headers}\")\n\n# Expected output for outgoing_headers will contain 'x-cloud-trace-context'","lang":"python","description":"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."},"warnings":[{"fix":"Ensure `propagators.set_global_textmap_propagator(CompositePropagator([CloudTracePropagator(), ...]))` is called early in your application's lifecycle, before any tracing occurs.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"When setting the global propagator, construct a `CompositePropagator` like: `CompositePropagator([CloudTracePropagator(), W3CTraceContextPropagator()])`.","message":"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`).","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"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.","severity":"breaking","affected_versions":"1.11.0+"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}