Deprecate OpenCensus shim public API

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

opencensus-shim/src/main/java/io/opentelemetry/opencensusshim/OpenCensusMetricProducer.java

@@ -21,7 +21,12 @@
  * both OpenTelemetry and OpenCensus metrics.
  *
  * <p>To use, register with {@link SdkMeterProviderBuilder#registerMetricProducer(MetricProducer)}.
+ *
+ * @deprecated OpenCensus compatibility is deprecated in the OpenTelemetry specification (see <a
+ *     href="https://github.com/open-telemetry/opentelemetry-specification/pull/5138">#5138</a>).
+ *     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 <a
+   *     href="https://github.com/open-telemetry/opentelemetry-specification/pull/5138">#5138</a>).
+   *     Expect this artifact to no longer be published after June 2027.
    */
+  @Deprecated
   public static MetricProducer create() {
     return new OpenCensusMetricProducer(Metrics.getExportComponent().getMetricProducerManager());
   }

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 <a
+ *     href="https://github.com/open-telemetry/opentelemetry-specification/pull/5138">#5138</a>).
+ *     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 <a
+   *     href="https://github.com/open-telemetry/opentelemetry-specification/pull/5138">#5138</a>).
+   *     Expect this artifact to no longer be published after June 2027.
+   */
+  @Deprecated
   @SuppressWarnings("unused") // Loaded via reflection
   public OpenTelemetryContextManager() {}
 

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 <a
+ *     href="https://github.com/open-telemetry/opentelemetry-specification/pull/5138">#5138</a>).
+ *     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 <a
+   *     href="https://github.com/open-telemetry/opentelemetry-specification/pull/5138">#5138</a>).
+   *     Expect this artifact to no longer be published after June 2027.
+   */
+  @Deprecated
   @SuppressWarnings("unused") // Loaded via reflection
   public OpenTelemetryTraceComponentImpl() {
     clock = MillisClock.getInstance();

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.
+ *
+ * <p>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;
 

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();
 

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();