backcompat

Author: trask

.github/agents/knowledge/api-deprecation-policy.md

@@ -2,8 +2,23 @@
 
 ## Quick Reference
 
-- Use when: reviewing public API removals/renames, `@Deprecated` usage, stable-vs-alpha compatibility
-- Review focus: deprecate-then-remove timing, delegation direction, required Javadoc/CHANGELOG coverage
+- Use when: reviewing public API removals/renames, `@Deprecated` usage, stable-vs-alpha compatibility, or any module rename that touches user-facing config keys or emitted telemetry identity
+- Review focus: deprecate-then-remove timing, delegation direction, required Javadoc/CHANGELOG coverage, v3-preview gating for config keys and scope names
+
+## What Counts as "Public API"
+
+"API" here means **anything a user's code or configuration depends on by name**, including:
+
+- Java symbols in published artifacts (classes, methods, fields in `:library`, `:testing`,
+  `instrumentation-api*`).
+- User-facing configuration keys — `otel.instrumentation.<name>.enabled`, any
+  `otel.instrumentation.*` property, and the equivalent declarative YAML keys.
+- Outgoing telemetry identity — anything users can match on in their backend, including
+  `otel.scope.name`, span names, metric names, attribute keys, and attribute values. Users
+  build dashboards, filters, and alerts on these values, so silently renaming them is a
+  breaking change.
+
+A rename of any of these surfaces is a breaking change even if no Java symbol moved.
 
 ## When Are Breaking Changes Allowed?
 
@@ -75,6 +90,74 @@ default void configure(IgnoredTypesBuilder builder, ConfigProperties config) {
 }
 ```
 
+## Module renames: config keys and emitted scope names
+
+A module rename touches **two user-facing API surfaces** that must each be preserved by default
+and only change under `otel.instrumentation.common.v3-preview`. The mechanism differs because
+the surfaces are different: config keys can coexist as aliases, emitted scope names cannot.
+
+### 1. `InstrumentationModule` names (controls `otel.instrumentation.<name>.enabled`)
+
+The names passed to the `InstrumentationModule` constructor drive the
+`otel.instrumentation.<name>.enabled` config keys — any of them, not just the first. A rename
+silently breaks users who have the old key in their config.
+
+Keep the pre-rename name by passing it inline alongside the current name using the
+{@code "<current>|deprecated:<old>"} marker recognized by the `InstrumentationModule`
+constructor:
+
+```java
+public CxfInstrumentationModule() {
+  super("cxf", "jaxws-2.0-cxf-3.0|deprecated:jaxws-cxf-3.0", "jaxws");
+}
+```
+
+The framework (`DeprecatedInstrumentationNames.expand`) splits the marker and registers both
+names, so both `otel.instrumentation.jaxws-2.0-cxf-3.0.enabled` and
+`otel.instrumentation.jaxws-cxf-3.0.enabled` keep working (flat properties and YAML alike).
+Under `otel.instrumentation.common.v3-preview=true` the deprecated name is dropped; if the
+legacy key is explicitly set, a one-time WARNING is logged pointing at the new key.
+
+No per-module `AgentCommonConfig` branching, `isV3Preview()` checks, or bespoke logging are
+needed — one string literal is the entire change.
+
+### 2. Emitted instrumentation scope name (`INSTRUMENTATION_NAME` in `*Singletons`)
+
+The `INSTRUMENTATION_NAME` string passed to `Instrumenter.builder(...)` becomes the
+`otel.scope.name` attribute on every emitted span / metric / log. A rename silently breaks
+dashboards and filters that match on the old scope.
+
+Keep emitting the **pre-rename** scope name by default, and switch to the new one only under
+v3-preview:
+
+```java
+public class CxfSingletons {
+  private static final String INSTRUMENTATION_NAME =
+      AgentCommonConfig.get().isV3Preview()
+          ? "io.opentelemetry.jaxws-2.0-cxf-3.0"
+          // keep the pre-rename scope name so existing dashboards/filters on
+          // otel.scope.name="io.opentelemetry.jaxws-cxf-3.0" continue to work
+          : "io.opentelemetry.jaxws-cxf-3.0";
+  ...
+}
+```
+
+Note the asymmetry with the config-key case: there the list carries **both** names at once
+(aliases); here only **one** scope name is emitted at a time, and the default is the **old**
+one. Do not log a deprecation warning here — users cannot switch the scope name without
+enabling v3-preview globally (which affects every module), so a warning would push them
+toward something they are not expected to enable generally.
+
+### CHANGELOG
+
+The rename is **not** a breaking change or a deprecation in the current release: by default
+the old config keys and scope names continue to work unchanged, and the new names are only
+visible under `otel.instrumentation.common.v3-preview` — a preview flag that users are not
+generally encouraged to enable. Do not add a `⚠️ Breaking changes to non-stable APIs` or
+`🚫 Deprecations` entry for this kind of rename. If mentioned at all, it belongs in whatever
+section tracks v3-preview changes. The breaking change will be recorded when v3-preview
+becomes the default in 3.0.
+
 ## What to Flag in Review
 
 - **Breaking change without a prior deprecation**: a method/class was removed or its signature
@@ -98,3 +181,10 @@ default void configure(IgnoredTypesBuilder builder, ConfigProperties config) {
 
 - **Missing CHANGELOG entry**: a breaking change PR that does not add an
   `⚠️ Breaking changes to non-stable APIs` bullet in the `Unreleased` section of `CHANGELOG.md`.
+
+- **Module rename without backcompat**: `InstrumentationModule` constructor uses only the new
+  name, dropping the pre-rename name that drove the legacy
+  `otel.instrumentation.<old>.enabled` config key (it should be appended to the new name with
+  the {@code "|deprecated:<old>"} marker so `DeprecatedInstrumentationNames` can gate it on
+  v3-preview); and/or `*Singletons#INSTRUMENTATION_NAME` was changed unconditionally instead
+  of being gated on `AgentCommonConfig.get().isV3Preview()`.

instrumentation/jaxws/jaxws-2.0-cxf-3.0/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/jaxws/v2_0/cxf/v3_0/CxfInstrumentationModule.java

@@ -5,6 +5,7 @@
 
 package io.opentelemetry.javaagent.instrumentation.jaxws.v2_0.cxf.v3_0;
 
+import static io.opentelemetry.javaagent.extension.instrumentation.internal.DeprecatedInstrumentationNames.expandDeprecatedNames;
 import static java.util.Collections.singletonList;
 
 import com.google.auto.service.AutoService;
@@ -14,8 +15,9 @@
 
 @AutoService(InstrumentationModule.class)
 public class CxfInstrumentationModule extends InstrumentationModule {
+
   public CxfInstrumentationModule() {
-    super("cxf", "jaxws-2.0-cxf-3.0", "jaxws");
+    super("cxf", expandDeprecatedNames("jaxws-2.0-cxf-3.0|deprecated:jaxws-cxf-3.0", "jaxws"));
   }
 
   @Override

instrumentation/jaxws/jaxws-2.0-cxf-3.0/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/jaxws/v2_0/cxf/v3_0/CxfSingletons.java

@@ -7,10 +7,14 @@
 
 import io.opentelemetry.api.GlobalOpenTelemetry;
 import io.opentelemetry.instrumentation.api.instrumenter.Instrumenter;
+import io.opentelemetry.javaagent.bootstrap.internal.AgentCommonConfig;
 import io.opentelemetry.javaagent.bootstrap.internal.ExperimentalConfig;
 
 public class CxfSingletons {
-  private static final String INSTRUMENTATION_NAME = "io.opentelemetry.jaxws-2.0-cxf-3.0";
+  private static final String INSTRUMENTATION_NAME =
+      AgentCommonConfig.get().isV3Preview()
+          ? "io.opentelemetry.jaxws-2.0-cxf-3.0"
+          : "io.opentelemetry.jaxws-cxf-3.0";
 
   private static final Instrumenter<CxfRequest, Void> instrumenter;
 

instrumentation/jaxws/jaxws-2.0-metro-2.2/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/jaxws/v2_0/metro/v2_2/MetroInstrumentationModule.java

@@ -5,6 +5,7 @@
 
 package io.opentelemetry.javaagent.instrumentation.jaxws.v2_0.metro.v2_2;
 
+import static io.opentelemetry.javaagent.extension.instrumentation.internal.DeprecatedInstrumentationNames.expandDeprecatedNames;
 import static io.opentelemetry.javaagent.extension.matcher.AgentElementMatchers.hasClassesNamed;
 import static java.util.Arrays.asList;
 
@@ -16,8 +17,10 @@
 
 @AutoService(InstrumentationModule.class)
 public class MetroInstrumentationModule extends InstrumentationModule {
+
   public MetroInstrumentationModule() {
-    super("metro", "jaxws-2.0-metro-2.2", "jaxws");
+    super(
+        "metro", expandDeprecatedNames("jaxws-2.0-metro-2.2|deprecated:jaxws-metro-2.2", "jaxws"));
   }
 
   @Override

instrumentation/jaxws/jaxws-2.0-metro-2.2/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/jaxws/v2_0/metro/v2_2/MetroSingletons.java

@@ -7,10 +7,14 @@
 
 import io.opentelemetry.api.GlobalOpenTelemetry;
 import io.opentelemetry.instrumentation.api.instrumenter.Instrumenter;
+import io.opentelemetry.javaagent.bootstrap.internal.AgentCommonConfig;
 import io.opentelemetry.javaagent.bootstrap.internal.ExperimentalConfig;
 
 public class MetroSingletons {
-  private static final String INSTRUMENTATION_NAME = "io.opentelemetry.jaxws-2.0-metro-2.2";
+  private static final String INSTRUMENTATION_NAME =
+      AgentCommonConfig.get().isV3Preview()
+          ? "io.opentelemetry.jaxws-2.0-metro-2.2"
+          : "io.opentelemetry.jaxws-metro-2.2";
 
   private static final Instrumenter<MetroRequest, Void> instrumenter;
 

javaagent-extension-api/src/main/java/io/opentelemetry/javaagent/extension/instrumentation/internal/DeprecatedInstrumentationNames.java

@@ -0,0 +1,87 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.javaagent.extension.instrumentation.internal;
+
+import static java.util.Collections.singletonList;
+import static java.util.logging.Level.WARNING;
+
+import io.opentelemetry.javaagent.bootstrap.internal.AgentCommonConfig;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.logging.Logger;
+
+/**
+ * Helper for {@code InstrumentationModule}s whose names have been renamed: expands names containing
+ * the inline marker {@code "<current>|deprecated:<old>"} into the current name followed by the
+ * deprecated name.
+ *
+ * <p>Under {@code otel.instrumentation.common.v3-preview=true} the deprecated name is dropped, so
+ * only the current name is registered. Otherwise, if the deprecated name has been explicitly set
+ * via {@code otel.instrumentation.<old>.enabled} (flat properties or YAML), a warning is logged
+ * pointing users at the current name.
+ *
+ * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
+ * at any time.
+ */
+public final class DeprecatedInstrumentationNames {
+
+  private static final Logger logger =
+      Logger.getLogger(DeprecatedInstrumentationNames.class.getName());
+
+  private static final String DEPRECATED_MARKER = "|deprecated:";
+
+  /**
+   * Expands names containing {@code "<current>|deprecated:<old>"} into the current name followed by
+   * the deprecated name. Names without the marker are returned unchanged.
+   *
+   * <p>Under {@code otel.instrumentation.common.v3-preview=true} the deprecated name is dropped.
+   * Otherwise, if the deprecated name has been explicitly set via {@code
+   * otel.instrumentation.<old>.enabled} (flat properties or YAML), a warning is logged pointing
+   * users at the current name.
+   */
+  public static String[] expandDeprecatedNames(String... names) {
+    boolean hasMarker = false;
+    for (String name : names) {
+      if (name.contains(DEPRECATED_MARKER)) {
+        hasMarker = true;
+        break;
+      }
+    }
+    if (!hasMarker) {
+      return names;
+    }
+
+    boolean v3Preview = AgentCommonConfig.get().isV3Preview();
+    AgentDistributionConfig config = AgentDistributionConfig.get();
+    List<String> expanded = new ArrayList<>(names.length + 1);
+    for (String name : names) {
+      int idx = name.indexOf(DEPRECATED_MARKER);
+      if (idx < 0) {
+        expanded.add(name);
+        continue;
+      }
+      String current = name.substring(0, idx);
+      String deprecated = name.substring(idx + DEPRECATED_MARKER.length());
+      expanded.add(current);
+      if (v3Preview) {
+        continue;
+      }
+      expanded.add(deprecated);
+      List<String> probe = singletonList(deprecated);
+      if (config.isInstrumentationEnabled(probe, true)
+          != config.isInstrumentationEnabled(probe, false)) {
+        logger.log(
+            WARNING,
+            "otel.instrumentation.{0}.enabled is deprecated; "
+                + "use otel.instrumentation.{1}.enabled instead.",
+            new Object[] {deprecated, current});
+      }
+    }
+    return expanded.toArray(new String[0]);
+  }
+
+  private DeprecatedInstrumentationNames() {}
+}