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) | 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..ddb7b30b068 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,12 @@ * both OpenTelemetry and OpenCensus metrics. * *

To use, register with {@link SdkMeterProviderBuilder#registerMetricProducer(MetricProducer)}. + * + * @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 { private final MetricProducerManager openCensusMetricStorage; @@ -32,7 +37,12 @@ private OpenCensusMetricProducer(MetricProducerManager openCensusMetricStorage) /** * Constructs a new {@link OpenCensusMetricProducer} that reports against the given {@link * Resource}. + * + * @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() { 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..65c7a9174b4 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,25 @@ * {@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 (see #5138). + * Expect this artifact to no longer be published after June 2027. */ +@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 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 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..4a306aa5627 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,12 @@ * 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 (see #5138). + * Expect this artifact to no longer be published after June 2027. */ +@Deprecated public final class OpenTelemetryTraceComponentImpl extends TraceComponent { private final PropagationComponent propagationComponent = new OpenTelemetryPropagationComponentImpl(); @@ -30,6 +35,14 @@ 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 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 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();