---
id: opentelemetry-propagator-gcp
version: "1.14.0"
license: Apache-2.0
license_treatment: permissive
maintenance: active
---

# opentelemetry-propagator-gcp — Google Cloud propagator for OpenTelemetry

License: permissive · Maintenance: active · Downloads: 1.6M/mo

## What it is and what it does

This package provides OpenTelemetry propagators that handle Google Cloud's X-Cloud-Trace-Context trace header format. It acts as a bridge between OpenTelemetry's standard tracing infrastructure and Google Cloud's native trace propagation, allowing trace context to flow correctly across service boundaries in Google Cloud deployments.

The package offers two propagators: CloudTraceOneWayPropagator (reads only, intended for use with CompositePropagator) and CloudTraceFormatPropagator (reads and writes X-Cloud-Trace-Context headers). It depends only on opentelemetry-api and supports Python 3.9 through 3.13, making it a lightweight addition to existing OpenTelemetry instrumentation.

Use it for:

- Instrument Python services on Google Cloud to propagate trace context in the native X-Cloud-Trace-Context format
- Integrate OpenTelemetry tracing with Google Cloud Trace for centralized observability
- Combine multiple propagators using CompositePropagator to support both standard and Google Cloud trace formats
- Enable distributed tracing across microservices deployed on Google Cloud Platform

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Propagates trace context in Google Cloud's X-Cloud-Trace-Context format for OpenTelemetry, enabling distributed tracing integration with Google Cloud services.

Yes, if you are instrumenting Python services on Google Cloud Platform with OpenTelemetry. The package is actively maintained, has no known vulnerabilities, carries a permissive license, and adds minimal install friction. It is essential for correct trace propagation in Google Cloud environments.

## Install

pip install opentelemetry-propagator-gcp
uv add opentelemetry-propagator-gcp
poetry add opentelemetry-propagator-gcp

## Installing opentelemetry-propagator-gcp

Before you install: Low friction install with a single runtime dependency (opentelemetry-api). Actively maintained with recent commits.

License in practice: Apache-2.0 permissive license allows use in most commercial and open-source projects without significant restrictions.

Quickstart:

pip install opentelemetry-propagator-gcp

from opentelemetry.propagate import set_global_textmap
from opentelemetry.propagators.cloud_trace_propagator import CloudTraceFormatPropagator

set_global_textmap(CloudTraceFormatPropagator())

Verify before relying:

- Whether CloudTraceOneWayPropagator vs CloudTraceFormatPropagator choice affects performance or sampling behavior in production
- Compatibility with non-Google Cloud environments or hybrid deployments

## Package facts

- License: Apache-2.0 (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 1.6M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

google cloud trace context propagation, opentelemetry gcp integration, x-cloud-trace-context header, distributed tracing google cloud, opentelemetry propagator, cloud trace instrumentation, gcp observability, observability, distributed-tracing, gcp

[View on SkillFed](https://skillfed.io/packages/opentelemetry-propagator-gcp) · [View on PyPI](https://pypi.org/project/opentelemetry-propagator-gcp/)