From 42839982d8a66e400884e363927c6a9d22da0e0a Mon Sep 17 00:00:00 2001 From: Pranav Sharma Date: Mon, 31 Aug 2026 22:40:21 +0000 Subject: [PATCH 1/4] Mark opentelemetry-propagator-gcp as deprecated --- MIGRATION.md | 93 +++++++++++++++++++++++-- README.md | 11 +-- opentelemetry-propagator-gcp/README.rst | 9 +++ 3 files changed, 101 insertions(+), 12 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index 8de25982..cf6c6e0f 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -1,14 +1,14 @@ # Migration Guide -This guide provides instructions on how to migrate from the custom exporters in this repository to the standard OpenTelemetry OTLP exporters. +This guide provides instructions on how to migrate from the custom exporters and propagators in this repository to the standard OpenTelemetry OTLP exporters and W3C Trace Context propagator. ## Overview -Google Cloud supports native OTLP (OpenTelemetry Protocol) ingestion for Cloud Trace, Cloud Monitoring, and Cloud Logging via the [Telemetry API](https://docs.cloud.google.com/stackdriver/docs/reference/telemetry/overview). This allows you to use standard OpenTelemetry OTLP exporters for sending telemetry data to Google Cloud. +Google Cloud supports native OTLP (OpenTelemetry Protocol) ingestion for Cloud Trace, Cloud Monitoring, and Cloud Logging via the [Telemetry API](https://docs.cloud.google.com/stackdriver/docs/reference/telemetry/overview). This allows you to use standard OpenTelemetry OTLP exporters for sending telemetry data to Google Cloud. In addition, Google Cloud infrastructure natively supports standard W3C Trace Context headers (`traceparent` and `tracestate`), allowing you to use standard OpenTelemetry context propagation without proprietary headers. ## Deprecation Notice -All exporters in this repository (`opentelemetry-exporter-gcp-trace`, `opentelemetry-exporter-gcp-monitoring`, and `opentelemetry-exporter-gcp-logging`) are deprecated. Please migrate to standard OTLP exporters using standard OpenTelemetry libraries. +All exporters and propagators in this repository (`opentelemetry-exporter-gcp-trace`, `opentelemetry-exporter-gcp-monitoring`, `opentelemetry-exporter-gcp-logging`, and `opentelemetry-propagator-gcp`) are deprecated. Please migrate to standard OTLP exporters and standard W3C Trace Context propagation using standard OpenTelemetry libraries. --- @@ -25,7 +25,7 @@ pip install opentelemetry-resourcedetector-gcp ### Usage & Configuration * **Manual SDK Setup (In Code):** When manually setting up the SDK in Python (e.g., instantiating `TracerProvider()`, `MeterProvider()`, or `LoggerProvider()`), the GCP resource detector is **automatically discovered and applied** simply by installing `opentelemetry-resourcedetector-gcp`. No additional code changes or environment variables are required. -* **Autoconfiguration / Zero-Code Instrumentation:** When using OpenTelemetry autoconfiguration (`opentelemetry-sdk-extension-autoconfigure` or `opentelemetry-instrument`), enable the GCP resource detector via the `OTEL_EXPERIMENTAL_RESOURCE_DETECTORS` environment variable: +* **Auto-Instrumentation / Zero-Code:** When using OpenTelemetry auto-instrumentation (`opentelemetry-instrument`), enable the GCP resource detector via the `OTEL_EXPERIMENTAL_RESOURCE_DETECTORS` environment variable: ```bash export OTEL_EXPERIMENTAL_RESOURCE_DETECTORS="gcp" @@ -479,3 +479,88 @@ logger_provider.add_log_record_processor( * **Log Names & Resources:** The OTLP endpoint maps log names from resource attributes (e.g. `gcp.log_name` or defaults to `projects//logs/otel`). * **Query Impact:** If your existing Cloud Logging log queries filter by specific `logName` values (such as python logger names mapped by `CloudLoggingExporter`), you may need to update your Cloud Logging query filters to match the OTLP log names and attributes. * **GCP Monitored Resource Association:** Installing `opentelemetry-resourcedetector-gcp` ensures log records contain appropriate GCP resource attributes, allowing Cloud Logging to associate logs with standard monitored resources (GCE instances, GKE pods, Cloud Run services, etc.). + +--- + +## Migrate from X-Cloud-Trace-Context Propagator to W3C Trace Context Propagator + +Google Cloud infrastructure now natively supports standard W3C Trace Context headers (`traceparent` and `tracestate`). The `opentelemetry-propagator-gcp` package is deprecated and will be archived after October 30th, 2026. You should migrate to standard OpenTelemetry W3C Trace Context propagation. + +### Why Migrate? + +* **Standardization:** W3C Trace Context is the industry standard for distributed tracing context propagation and is natively supported across cloud providers, libraries, and frameworks. +* **Native GCP Support:** Google Cloud services (such as Cloud Run, Cloud Functions, App Engine, Google Kubernetes Engine, Cloud Trace, and Google Cloud Load Balancers) natively support W3C Trace Context headers without requiring proprietary headers. +* **Built-in OpenTelemetry Support:** W3C Trace Context propagation is built into the core `opentelemetry-api` package and is enabled by default in OpenTelemetry Python. + +--- + +### Migration Steps + +#### 1. Remove Legacy Dependency + +Remove the `opentelemetry-propagator-gcp` dependency from your project (`requirements.txt`, `pyproject.toml`, etc.): + +```bash +pip uninstall opentelemetry-propagator-gcp +``` + +The standard W3C Trace Context propagator is included automatically with `opentelemetry-api`. + +#### 2. Update Configuration (Auto-Instrumentation / CLI) + +When using OpenTelemetry auto-instrumentation (`opentelemetry-instrument`), W3C Trace Context (`tracecontext`) and Baggage (`baggage`) are used by default (`OTEL_PROPAGATORS="tracecontext,baggage"`). + +If you explicitly configured `OTEL_PROPAGATORS` to include `gcp_trace`, update it to remove it: + +```bash +# Environment Variables +OTEL_PROPAGATORS="tracecontext,baggage" +``` + +If you use the `opentelemetry-instrument` CLI for auto-instrumentation, remove the `--propagator gcp_trace` flag: + +```bash +# Before +opentelemetry-instrument --propagator gcp_trace python main.py + +# After (uses default W3C Trace Context and Baggage propagators) +opentelemetry-instrument python main.py +``` + +#### 3. Update Manual Configuration in Code + +If you manually registered `CloudTraceFormatPropagator` in your application code, replace it with the standard OpenTelemetry `TraceContextTextMapPropagator` (and optionally `W3CBaggagePropagator`): + +##### Before (Legacy GCP Propagator) + +```python +from opentelemetry.propagate import set_global_textmap +from opentelemetry.propagators.cloud_trace_propagator import ( + CloudTraceFormatPropagator, +) + +# Sets the X-Cloud-Trace-Context header propagator +set_global_textmap(CloudTraceFormatPropagator()) +``` + +##### After (Standard W3C Trace Context Propagator) + +```python +from opentelemetry.baggage.propagation import W3CBaggagePropagator +from opentelemetry.propagate import set_global_textmap +from opentelemetry.propagators.composite import CompositePropagator +from opentelemetry.trace.propagation.tracecontext import ( + TraceContextTextMapPropagator, +) + +# Set standard W3C Trace Context and Baggage propagators +set_global_textmap( + CompositePropagator([ + TraceContextTextMapPropagator(), + W3CBaggagePropagator(), + ]) +) +``` + +> [!NOTE] +> When using `opentelemetry-instrument` (or relying on default `opentelemetry-api` propagation), standard W3C propagation is enabled automatically by default without requiring manual code setup. diff --git a/README.md b/README.md index 76ccd82a..03820b43 100644 --- a/README.md +++ b/README.md @@ -3,20 +3,15 @@ [![Documentation Status](https://readthedocs.org/projects/google-cloud-opentelemetry/badge/?version=latest)](https://google-cloud-opentelemetry.readthedocs.io/en/latest/?badge=latest) +> [!WARNING] +> **DEPRECATION NOTICE**: This repository and all of its contents are deprecated and will be archived on October 30th, 2026. Please refer to the [Migration Guide](MIGRATION.md) for detailed instructions on migrating your application to standard OpenTelemetry OTLP exporters and W3C Trace Context propagation. + This repo provides OpenTelemetry Python exporters, propagators, and resource detectors for Google Cloud Platform. To get started with instrumentation in Google Cloud, see [Generate traces and metrics with Python](https://cloud.google.com/stackdriver/docs/instrumentation/setup/python). -## ⚠️ Deprecation Notice - -**All custom Google Cloud exporters in this repository (`opentelemetry-exporter-gcp-trace`, `opentelemetry-exporter-gcp-monitoring`, and `opentelemetry-exporter-gcp-logging`) are deprecated.** - -Google Cloud supports native OpenTelemetry Protocol (OTLP) ingestion for Cloud Trace, Cloud Monitoring, and Cloud Logging via the [Telemetry API](https://docs.cloud.google.com/stackdriver/docs/reference/telemetry/overview). - -Please refer to the [Migration Guide](MIGRATION.md) for detailed instructions on migrating your application to standard OpenTelemetry OTLP exporters. - ## Google Cloud Resource Detector The OpenTelemetry Google Cloud Resource Detector (`opentelemetry-resourcedetector-gcp`) has moved to the [opentelemetry-python-contrib](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/resource/opentelemetry-resourcedetector-gcp) repository: diff --git a/opentelemetry-propagator-gcp/README.rst b/opentelemetry-propagator-gcp/README.rst index fed74e65..f1a2cd10 100644 --- a/opentelemetry-propagator-gcp/README.rst +++ b/opentelemetry-propagator-gcp/README.rst @@ -8,6 +8,15 @@ OpenTelemetry Google Cloud Propagator :target: https://google-cloud-opentelemetry.readthedocs.io/en/latest/?badge=latest :alt: Documentation Status + +.. admonition:: Warning - Deprecated + :class: warning + + This package is deprecated and will be archived after October 30th, 2026. + Google Cloud infrastructure now natively supports standard W3C Trace Context + headers. Please use standard W3C Trace Context propagation instead. + See the `Migration Guide `_ for details. + This library provides support for propagating trace context in the Google Cloud ``X-Cloud-Trace-Context`` format. From 4706382234948104ca4c66b73fc493f8f5f883bf Mon Sep 17 00:00:00 2001 From: Pranav Sharma Date: Mon, 31 Aug 2026 22:42:34 +0000 Subject: [PATCH 2/4] Remove deprecation notice from MIGRATION.md Deprecation notice in a migration guide seemed out of place. --- MIGRATION.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index cf6c6e0f..9bbde52e 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -6,10 +6,6 @@ This guide provides instructions on how to migrate from the custom exporters and Google Cloud supports native OTLP (OpenTelemetry Protocol) ingestion for Cloud Trace, Cloud Monitoring, and Cloud Logging via the [Telemetry API](https://docs.cloud.google.com/stackdriver/docs/reference/telemetry/overview). This allows you to use standard OpenTelemetry OTLP exporters for sending telemetry data to Google Cloud. In addition, Google Cloud infrastructure natively supports standard W3C Trace Context headers (`traceparent` and `tracestate`), allowing you to use standard OpenTelemetry context propagation without proprietary headers. -## Deprecation Notice - -All exporters and propagators in this repository (`opentelemetry-exporter-gcp-trace`, `opentelemetry-exporter-gcp-monitoring`, `opentelemetry-exporter-gcp-logging`, and `opentelemetry-propagator-gcp`) are deprecated. Please migrate to standard OTLP exporters and standard W3C Trace Context propagation using standard OpenTelemetry libraries. - --- ## Resource Detection (Recommended for All Signals) From b56fd67b2115eb7746948de3746395c0bde23d97 Mon Sep 17 00:00:00 2001 From: Pranav Sharma Date: Tue, 1 Sep 2026 20:59:55 +0000 Subject: [PATCH 3/4] Update Migration instructions to rely on the default behavior --- MIGRATION.md | 33 ++++++++------------------------- 1 file changed, 8 insertions(+), 25 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index 9bbde52e..34ea3e9f 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -506,13 +506,6 @@ The standard W3C Trace Context propagator is included automatically with `opente When using OpenTelemetry auto-instrumentation (`opentelemetry-instrument`), W3C Trace Context (`tracecontext`) and Baggage (`baggage`) are used by default (`OTEL_PROPAGATORS="tracecontext,baggage"`). -If you explicitly configured `OTEL_PROPAGATORS` to include `gcp_trace`, update it to remove it: - -```bash -# Environment Variables -OTEL_PROPAGATORS="tracecontext,baggage" -``` - If you use the `opentelemetry-instrument` CLI for auto-instrumentation, remove the `--propagator gcp_trace` flag: ```bash @@ -523,9 +516,11 @@ opentelemetry-instrument --propagator gcp_trace python main.py opentelemetry-instrument python main.py ``` -#### 3. Update Manual Configuration in Code +#### 3. Remove Manual Configuration in Code -If you manually registered `CloudTraceFormatPropagator` in your application code, replace it with the standard OpenTelemetry `TraceContextTextMapPropagator` (and optionally `W3CBaggagePropagator`): +If you manually registered `CloudTraceFormatPropagator` or `CloudTraceOneWayPropagator` in your application code, simply remove the propagator import and `set_global_textmap` registration. + +OpenTelemetry automatically uses standard W3C Trace Context propagation by default—no manual `set_global_textmap` call is necessary. ##### Before (Legacy GCP Propagator) @@ -539,24 +534,12 @@ from opentelemetry.propagators.cloud_trace_propagator import ( set_global_textmap(CloudTraceFormatPropagator()) ``` -##### After (Standard W3C Trace Context Propagator) +##### After ```python -from opentelemetry.baggage.propagation import W3CBaggagePropagator -from opentelemetry.propagate import set_global_textmap -from opentelemetry.propagators.composite import CompositePropagator -from opentelemetry.trace.propagation.tracecontext import ( - TraceContextTextMapPropagator, -) - -# Set standard W3C Trace Context and Baggage propagators -set_global_textmap( - CompositePropagator([ - TraceContextTextMapPropagator(), - W3CBaggagePropagator(), - ]) -) +# Simply remove the GCP propagator import and set_global_textmap call. +# OpenTelemetry automatically defaults to standard W3C Trace Context propagation. ``` > [!NOTE] -> When using `opentelemetry-instrument` (or relying on default `opentelemetry-api` propagation), standard W3C propagation is enabled automatically by default without requiring manual code setup. +> Standard W3C Trace Context propagation is built into `opentelemetry-api` and enabled by default. You do not need to call `set_global_textmap` unless you are configuring non-default custom propagators. From cdb608477adf05a974761cd7967a7259599a272a Mon Sep 17 00:00:00 2001 From: Pranav Sharma Date: Tue, 1 Sep 2026 17:25:30 -0400 Subject: [PATCH 4/4] Update MIGRATION.md Co-authored-by: Aaron Abbott --- MIGRATION.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/MIGRATION.md b/MIGRATION.md index 34ea3e9f..d764cf17 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -504,7 +504,7 @@ The standard W3C Trace Context propagator is included automatically with `opente #### 2. Update Configuration (Auto-Instrumentation / CLI) -When using OpenTelemetry auto-instrumentation (`opentelemetry-instrument`), W3C Trace Context (`tracecontext`) and Baggage (`baggage`) are used by default (`OTEL_PROPAGATORS="tracecontext,baggage"`). +Unless overriden with `set_global_textmap()`, W3C Trace Context (`tracecontext`) and Baggage (`baggage`) are used by default (`OTEL_PROPAGATORS="tracecontext,baggage"`) in OpenTelemetry Python, regardless of if you're using auto-instrumentation or manual. If you use the `opentelemetry-instrument` CLI for auto-instrumentation, remove the `--propagator gcp_trace` flag: