From ac2b903c21742fbdc603bfc0cd7d32a6efe9f32e Mon Sep 17 00:00:00 2001 From: Liang Hu Date: Fri, 31 Jul 2026 11:41:20 -0400 Subject: [PATCH 1/3] Deprecate OpenCensus shim public API --- opencensus-shim/README.md | 6 ++++++ .../opencensusshim/OpenCensusMetricProducer.java | 8 ++++++++ .../opencensusshim/OpenTelemetryContextManager.java | 10 ++++++++++ .../OpenTelemetryTraceComponentImpl.java | 10 ++++++++++ .../io/opentelemetry/opencensusshim/package-info.java | 8 +++++++- .../opencensusshim/OpenCensusMetricProducerTest.java | 1 + .../opencensusshim/OpenCensusMetricsTest.java | 1 + 7 files changed, 43 insertions(+), 1 deletion(-) diff --git a/opencensus-shim/README.md b/opencensus-shim/README.md index b124e4d2c76..9e8b58a2a7d 100644 --- a/opencensus-shim/README.md +++ b/opencensus-shim/README.md @@ -1,5 +1,11 @@ # OpenTelemetry OpenCensus Shim +> [!WARNING] +> OpenCensus compatibility is deprecated in the OpenTelemetry specification, and this shim is +> deprecated accordingly. It remains available for legacy compatibility, but users should migrate +> OpenCensus instrumentation to the OpenTelemetry APIs. See the +> [OpenTelemetry specification guidance on OpenCensus compatibility](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/compatibility/opencensus.md). + The OpenCensus shim allows applications and libraries that are instrumented with OpenTelemetry, but depend on other libraries instrumented with OpenCensus, to export trace spans from both OpenTelemetry and OpenCensus with the correct diff --git a/opencensus-shim/src/main/java/io/opentelemetry/opencensusshim/OpenCensusMetricProducer.java b/opencensus-shim/src/main/java/io/opentelemetry/opencensusshim/OpenCensusMetricProducer.java index 121c61360f1..b67bf178a4a 100644 --- a/opencensus-shim/src/main/java/io/opentelemetry/opencensusshim/OpenCensusMetricProducer.java +++ b/opencensus-shim/src/main/java/io/opentelemetry/opencensusshim/OpenCensusMetricProducer.java @@ -21,7 +21,11 @@ * both OpenTelemetry and OpenCensus metrics. * *

To use, register with {@link SdkMeterProviderBuilder#registerMetricProducer(MetricProducer)}. + * + * @deprecated OpenCensus compatibility is deprecated in the OpenTelemetry specification. This shim + * is deprecated accordingly. Migrate OpenCensus instrumentation to the OpenTelemetry APIs. */ +@Deprecated public final class OpenCensusMetricProducer implements MetricProducer { private final MetricProducerManager openCensusMetricStorage; @@ -32,7 +36,11 @@ private OpenCensusMetricProducer(MetricProducerManager openCensusMetricStorage) /** * Constructs a new {@link OpenCensusMetricProducer} that reports against the given {@link * Resource}. + * + * @deprecated OpenCensus compatibility is deprecated. Migrate OpenCensus instrumentation to the + * OpenTelemetry APIs. */ + @Deprecated public static MetricProducer create() { return new OpenCensusMetricProducer(Metrics.getExportComponent().getMetricProducerManager()); } diff --git a/opencensus-shim/src/main/java/io/opentelemetry/opencensusshim/OpenTelemetryContextManager.java b/opencensus-shim/src/main/java/io/opentelemetry/opencensusshim/OpenTelemetryContextManager.java index 24d9818645c..ab9a802f492 100644 --- a/opencensus-shim/src/main/java/io/opentelemetry/opencensusshim/OpenTelemetryContextManager.java +++ b/opencensus-shim/src/main/java/io/opentelemetry/opencensusshim/OpenTelemetryContextManager.java @@ -16,12 +16,22 @@ * {@link io.opencensus.trace.unsafe.ContextManagerImpl}. It is loaded by OpenCensus via reflection * automatically in {@link io.opencensus.trace.unsafe.ContextHandleUtils} when the OpenCensus shim * library exists as a dependency. + * + * @deprecated OpenCensus compatibility is deprecated in the OpenTelemetry specification. This shim + * is deprecated accordingly. Migrate OpenCensus instrumentation to the OpenTelemetry APIs. */ +@Deprecated public final class OpenTelemetryContextManager implements ContextManager { private static final Logger LOGGER = Logger.getLogger(OpenTelemetryContextManager.class.getName()); + /** + * Creates the context manager loaded by OpenCensus through reflection. + * + * @deprecated This constructor is used by the deprecated OpenCensus compatibility shim. + */ + @Deprecated @SuppressWarnings("unused") // Loaded via reflection public OpenTelemetryContextManager() {} diff --git a/opencensus-shim/src/main/java/io/opentelemetry/opencensusshim/OpenTelemetryTraceComponentImpl.java b/opencensus-shim/src/main/java/io/opentelemetry/opencensusshim/OpenTelemetryTraceComponentImpl.java index 503220353b4..0c9f2849a3b 100644 --- a/opencensus-shim/src/main/java/io/opentelemetry/opencensusshim/OpenTelemetryTraceComponentImpl.java +++ b/opencensus-shim/src/main/java/io/opentelemetry/opencensusshim/OpenTelemetryTraceComponentImpl.java @@ -21,7 +21,11 @@ * Implementation of the {@link TraceComponent} for OpenTelemetry migration, which uses the * OpenTelemetry migration StartEndHandler. This class is loaded by reflection in {@link * io.opencensus.trace.Tracing} and overrides the OpenCensus default implementation when present. + * + * @deprecated OpenCensus compatibility is deprecated in the OpenTelemetry specification. This shim + * is deprecated accordingly. Migrate OpenCensus instrumentation to the OpenTelemetry APIs. */ +@Deprecated public final class OpenTelemetryTraceComponentImpl extends TraceComponent { private final PropagationComponent propagationComponent = new OpenTelemetryPropagationComponentImpl(); @@ -30,6 +34,12 @@ public final class OpenTelemetryTraceComponentImpl extends TraceComponent { private final TraceConfig traceConfig = makeTraceConfig(); private final Tracer tracer; + /** + * Creates the trace component loaded by OpenCensus through reflection. + * + * @deprecated This constructor is used by the deprecated OpenCensus compatibility shim. + */ + @Deprecated @SuppressWarnings("unused") // Loaded via reflection public OpenTelemetryTraceComponentImpl() { clock = MillisClock.getInstance(); diff --git a/opencensus-shim/src/main/java/io/opentelemetry/opencensusshim/package-info.java b/opencensus-shim/src/main/java/io/opentelemetry/opencensusshim/package-info.java index 36b5be41e94..9428c9c7dab 100644 --- a/opencensus-shim/src/main/java/io/opentelemetry/opencensusshim/package-info.java +++ b/opencensus-shim/src/main/java/io/opentelemetry/opencensusshim/package-info.java @@ -3,7 +3,13 @@ * SPDX-License-Identifier: Apache-2.0 */ -/** The OpenCensus to OpenTelemetry shim. */ +/** + * Legacy OpenCensus compatibility built on top of OpenTelemetry. + * + *

OpenCensus compatibility is deprecated in the OpenTelemetry specification, and this shim is + * deprecated accordingly. Use this package only for legacy compatibility while migrating OpenCensus + * instrumentation to the OpenTelemetry APIs. + */ @ParametersAreNonnullByDefault package io.opentelemetry.opencensusshim; diff --git a/opencensus-shim/src/test/java/io/opentelemetry/opencensusshim/OpenCensusMetricProducerTest.java b/opencensus-shim/src/test/java/io/opentelemetry/opencensusshim/OpenCensusMetricProducerTest.java index 67996be5e06..c4fbca32ff3 100644 --- a/opencensus-shim/src/test/java/io/opentelemetry/opencensusshim/OpenCensusMetricProducerTest.java +++ b/opencensus-shim/src/test/java/io/opentelemetry/opencensusshim/OpenCensusMetricProducerTest.java @@ -30,6 +30,7 @@ import org.awaitility.Awaitility; import org.junit.jupiter.api.Test; +@SuppressWarnings("deprecation") // testing deprecated shim API class OpenCensusMetricProducerTest { private final MetricProducer openCensusMetrics = OpenCensusMetricProducer.create(); diff --git a/opencensus-shim/src/test/java/io/opentelemetry/opencensusshim/OpenCensusMetricsTest.java b/opencensus-shim/src/test/java/io/opentelemetry/opencensusshim/OpenCensusMetricsTest.java index 4539045c435..3c0db5297b1 100644 --- a/opencensus-shim/src/test/java/io/opentelemetry/opencensusshim/OpenCensusMetricsTest.java +++ b/opencensus-shim/src/test/java/io/opentelemetry/opencensusshim/OpenCensusMetricsTest.java @@ -19,6 +19,7 @@ import org.awaitility.Awaitility; import org.junit.jupiter.api.Test; +@SuppressWarnings("deprecation") // testing deprecated shim API class OpenCensusMetricsTest { private static final StatsRecorder STATS_RECORDER = Stats.getStatsRecorder(); From dc333b88583bdc6071bd24afde547033bcdcee65 Mon Sep 17 00:00:00 2001 From: Liang Hu Date: Fri, 31 Jul 2026 17:24:45 -0400 Subject: [PATCH 2/3] Clarify OpenCensus shim retirement timeline --- .../opencensusshim/OpenCensusMetricProducer.java | 10 ++++++---- .../opencensusshim/OpenTelemetryContextManager.java | 9 ++++++--- .../OpenTelemetryTraceComponentImpl.java | 9 ++++++--- 3 files changed, 18 insertions(+), 10 deletions(-) diff --git a/opencensus-shim/src/main/java/io/opentelemetry/opencensusshim/OpenCensusMetricProducer.java b/opencensus-shim/src/main/java/io/opentelemetry/opencensusshim/OpenCensusMetricProducer.java index b67bf178a4a..ddb7b30b068 100644 --- a/opencensus-shim/src/main/java/io/opentelemetry/opencensusshim/OpenCensusMetricProducer.java +++ b/opencensus-shim/src/main/java/io/opentelemetry/opencensusshim/OpenCensusMetricProducer.java @@ -22,8 +22,9 @@ * *

To use, register with {@link SdkMeterProviderBuilder#registerMetricProducer(MetricProducer)}. * - * @deprecated OpenCensus compatibility is deprecated in the OpenTelemetry specification. This shim - * is deprecated accordingly. Migrate OpenCensus instrumentation to the OpenTelemetry APIs. + * @deprecated OpenCensus compatibility is deprecated in the OpenTelemetry specification (see #5138). + * Expect this artifact to no longer be published after June 2027. */ @Deprecated public final class OpenCensusMetricProducer implements MetricProducer { @@ -37,8 +38,9 @@ private OpenCensusMetricProducer(MetricProducerManager openCensusMetricStorage) * Constructs a new {@link OpenCensusMetricProducer} that reports against the given {@link * Resource}. * - * @deprecated OpenCensus compatibility is deprecated. Migrate OpenCensus instrumentation to the - * OpenTelemetry APIs. + * @deprecated OpenCensus compatibility is deprecated in the OpenTelemetry specification (see #5138). + * Expect this artifact to no longer be published after June 2027. */ @Deprecated public static MetricProducer create() { diff --git a/opencensus-shim/src/main/java/io/opentelemetry/opencensusshim/OpenTelemetryContextManager.java b/opencensus-shim/src/main/java/io/opentelemetry/opencensusshim/OpenTelemetryContextManager.java index ab9a802f492..65c7a9174b4 100644 --- a/opencensus-shim/src/main/java/io/opentelemetry/opencensusshim/OpenTelemetryContextManager.java +++ b/opencensus-shim/src/main/java/io/opentelemetry/opencensusshim/OpenTelemetryContextManager.java @@ -17,8 +17,9 @@ * automatically in {@link io.opencensus.trace.unsafe.ContextHandleUtils} when the OpenCensus shim * library exists as a dependency. * - * @deprecated OpenCensus compatibility is deprecated in the OpenTelemetry specification. This shim - * is deprecated accordingly. Migrate OpenCensus instrumentation to the OpenTelemetry APIs. + * @deprecated OpenCensus compatibility is deprecated in the OpenTelemetry specification (see #5138). + * Expect this artifact to no longer be published after June 2027. */ @Deprecated public final class OpenTelemetryContextManager implements ContextManager { @@ -29,7 +30,9 @@ public final class OpenTelemetryContextManager implements ContextManager { /** * Creates the context manager loaded by OpenCensus through reflection. * - * @deprecated This constructor is used by the deprecated OpenCensus compatibility shim. + * @deprecated OpenCensus compatibility is deprecated in the OpenTelemetry specification (see #5138). + * Expect this artifact to no longer be published after June 2027. */ @Deprecated @SuppressWarnings("unused") // Loaded via reflection diff --git a/opencensus-shim/src/main/java/io/opentelemetry/opencensusshim/OpenTelemetryTraceComponentImpl.java b/opencensus-shim/src/main/java/io/opentelemetry/opencensusshim/OpenTelemetryTraceComponentImpl.java index 0c9f2849a3b..4a306aa5627 100644 --- a/opencensus-shim/src/main/java/io/opentelemetry/opencensusshim/OpenTelemetryTraceComponentImpl.java +++ b/opencensus-shim/src/main/java/io/opentelemetry/opencensusshim/OpenTelemetryTraceComponentImpl.java @@ -22,8 +22,9 @@ * OpenTelemetry migration StartEndHandler. This class is loaded by reflection in {@link * io.opencensus.trace.Tracing} and overrides the OpenCensus default implementation when present. * - * @deprecated OpenCensus compatibility is deprecated in the OpenTelemetry specification. This shim - * is deprecated accordingly. Migrate OpenCensus instrumentation to the OpenTelemetry APIs. + * @deprecated OpenCensus compatibility is deprecated in the OpenTelemetry specification (see #5138). + * Expect this artifact to no longer be published after June 2027. */ @Deprecated public final class OpenTelemetryTraceComponentImpl extends TraceComponent { @@ -37,7 +38,9 @@ public final class OpenTelemetryTraceComponentImpl extends TraceComponent { /** * Creates the trace component loaded by OpenCensus through reflection. * - * @deprecated This constructor is used by the deprecated OpenCensus compatibility shim. + * @deprecated OpenCensus compatibility is deprecated in the OpenTelemetry specification (see #5138). + * Expect this artifact to no longer be published after June 2027. */ @Deprecated @SuppressWarnings("unused") // Loaded via reflection From d0f9df6060c1f8ed7bf8c0ba77e383caea81f8aa Mon Sep 17 00:00:00 2001 From: Liang Hu Date: Mon, 3 Aug 2026 18:00:41 -0400 Subject: [PATCH 3/3] docs: mark OpenCensus shim artifact deprecated --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 311bfd7a294..683f0fd7a66 100644 --- a/README.md +++ b/README.md @@ -142,7 +142,7 @@ Shims for bridging data from one observability library to another. | Component | Description | Artifact ID | Version | Javadoc | |----------------------------------------|--------------------------------------------------------------|----------------------------------|-------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| [OpenCensus Shim](./opencensus-shim) | Bridge opencensus metrics into the OpenTelemetry metrics SDK | `opentelemetry-opencensus-shim` | 1.64.0-alpha | [![Javadocs](https://www.javadoc.io/badge/io.opentelemetry/opentelemetry-opencensus-shim.svg)](https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-opencensus-shim) | +| [OpenCensus Shim](./opencensus-shim) | **DEPRECATED** Bridge opencensus metrics into the OpenTelemetry metrics SDK | `opentelemetry-opencensus-shim` | 1.64.0-alpha | [![Javadocs](https://www.javadoc.io/badge/io.opentelemetry/opentelemetry-opencensus-shim.svg)](https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-opencensus-shim) | | [OpenTracing Shim](./opentracing-shim) | **DEPRECATED** Bridge opentracing spans into the OpenTelemetry trace API | `opentelemetry-opentracing-shim` | 1.64.0 | [![Javadocs](https://www.javadoc.io/badge/io.opentelemetry/opentelemetry-opentracing-shim.svg)](https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-opentracing-shim) |