Rename JAX-WS 2.0 javaagent modules to spec-scoped names and hierarchical packages (#18184)

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: trask <218610+trask@users.noreply.github.com>
Co-authored-by: Trask Stalnaker <trask.stalnaker@gmail.com>

Author: Copilot

.fossa.yml

@@ -564,16 +564,16 @@ targets:
       target: ':instrumentation:jaxws:jaxws-2.0-axis2-1.6:javaagent'
     - type: gradle
       path: ./
-      target: ':instrumentation:jaxws:jaxws-common:javaagent'
+      target: ':instrumentation:jaxws:jaxws-2.0-cxf-3.0:javaagent'
     - type: gradle
       path: ./
-      target: ':instrumentation:jaxws:jaxws-cxf-3.0:javaagent'
+      target: ':instrumentation:jaxws:jaxws-2.0-metro-2.2:javaagent'
     - type: gradle
       path: ./
-      target: ':instrumentation:jaxws:jaxws-jws-api-1.1:javaagent'
+      target: ':instrumentation:jaxws:jaxws-common:javaagent'
     - type: gradle
       path: ./
-      target: ':instrumentation:jaxws:jaxws-metro-2.2:javaagent'
+      target: ':instrumentation:jaxws:jaxws-jws-api-1.1:javaagent'
     - type: gradle
       path: ./
       target: ':instrumentation:jboss-logmanager:jboss-logmanager-appender-1.1:javaagent'

.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,107 @@ 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.
+
+Emitting the old scope name by default has one consequence: the version `.properties` file
+generated by `generateInstrumentationVersionFile` is named after the **new** module name
+(e.g. `io.opentelemetry.jaxws-2.0-cxf-3.0.properties`), and `Instrumenter.builder` looks the
+version up via `EmbeddedInstrumentationProperties.findVersion(instrumentationName)` keyed on
+the scope name passed in. With the old name as the default the lookup returns `null`, the
+emitted scope has no version, and `TelemetryDataUtil.assertScopeVersion` fails every test in
+CI with:
+
+> Instrumentation version of module `io.opentelemetry.<old>` was empty; make sure that the
+> instrumentation name matches the gradle module name
+
+Resolve this by looking up the version under the **new** module name and calling
+`setInstrumentationVersion` on the builder explicitly:
+
+```java
+private static final String VERSION_LOOKUP_NAME = "io.opentelemetry.jaxws-2.0-cxf-3.0";
+
+private static final String INSTRUMENTATION_NAME =
+    AgentCommonConfig.get().isV3Preview() ? VERSION_LOOKUP_NAME : "io.opentelemetry.jaxws-cxf-3.0";
+
+static {
+  InstrumenterBuilder<CxfRequest, Void> builder =
+      Instrumenter.<CxfRequest, Void>builder(
+              GlobalOpenTelemetry.get(), INSTRUMENTATION_NAME, CxfRequest::spanName)
+          .setEnabled(...);
+  String version = EmbeddedInstrumentationProperties.findVersion(VERSION_LOOKUP_NAME);
+  if (version != null) {
+    builder.setInstrumentationVersion(version);
+  }
+  instrumenter = builder.buildInstrumenter();
+}
+```
+
+### 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 +214,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()`.

.github/scripts/instrumentations.sh

@@ -140,9 +140,9 @@ readonly INSTRUMENTATIONS=(
   "jaxrs:jaxrs-3.0:jaxrs-3.0-resteasy-6.0:javaagent:testExperimental"
   "jaxws:jaxws-2.0:javaagent:test"
   "jaxws:jaxws-2.0-axis2-1.6:javaagent:test"
-  "jaxws:jaxws-cxf-3.0:javaagent:test"
+  "jaxws:jaxws-2.0-cxf-3.0:javaagent:test"
   "jaxws:jaxws-jws-api-1.1:javaagent:test"
-  "jaxws:jaxws-metro-2.2:javaagent:test"
+  "jaxws:jaxws-2.0-metro-2.2:javaagent:test"
   "jdbc:javaagent:test"
   "jdbc:javaagent:testStableSemconv"
   "jedis:jedis-1.4:javaagent:test"

docs/instrumentation-list.yaml

@@ -6801,17 +6801,17 @@ libraries:
     spans:
     - span_kind: INTERNAL
       attributes: []
-- name: jaxws-cxf-3.0
+- name: jaxws-2.0-cxf-3.0
   display_name: Apache CXF 3.x JAX-WS
   description: |
     This instrumentation enriches HTTP server spans with route information, and enables controller spans for Apache CXF JAX-WS web services (controller spans are disabled by default).
   library_link: https://cxf.apache.org/
   features:
   - HTTP_ROUTE
   - CONTROLLER_SPANS
-  source_path: instrumentation/jaxws/jaxws-cxf-3.0
+  source_path: instrumentation/jaxws/jaxws-2.0-cxf-3.0
   scope:
-    name: io.opentelemetry.jaxws-cxf-3.0
+    name: io.opentelemetry.jaxws-2.0-cxf-3.0
   has_javaagent: true
   javaagent_target_versions:
   - org.apache.cxf:cxf-rt-frontend-jaxws:[3.0.0,)
@@ -6855,17 +6855,17 @@ libraries:
         type: STRING
       - name: code.namespace
         type: STRING
-- name: jaxws-metro-2.2
+- name: jaxws-2.0-metro-2.2
   display_name: Metro JAX-WS
   description: |
     This instrumentation enriches HTTP server spans with route information, and enables controller spans for Metro JAX-WS web services (controller spans are disabled by default).
   library_link: https://javaee.github.io/metro/
   features:
   - HTTP_ROUTE
   - CONTROLLER_SPANS
-  source_path: instrumentation/jaxws/jaxws-metro-2.2
+  source_path: instrumentation/jaxws/jaxws-2.0-metro-2.2
   scope:
-    name: io.opentelemetry.jaxws-metro-2.2
+    name: io.opentelemetry.jaxws-2.0-metro-2.2
   has_javaagent: true
   javaagent_target_versions:
   - com.sun.xml.ws:jaxws-rt:[2.2,)

….0/javaagent-unit-tests/build.gradle.kts ….0/javaagent-unit-tests/build.gradle.ktsinstrumentation/jaxws/jaxws-cxf-3.0/javaagent-unit-tests/build.gradle.kts renamed to instrumentation/jaxws/jaxws-2.0-cxf-3.0/javaagent-unit-tests/build.gradle.kts instrumentation/jaxws/jaxws-cxf-3.0/javaagent-unit-tests/build.gradle.kts renamed to instrumentation/jaxws/jaxws-2.0-cxf-3.0/javaagent-unit-tests/build.gradle.kts

@@ -3,7 +3,7 @@ plugins {
 }
 
 dependencies {
-  testImplementation(project(":instrumentation:jaxws:jaxws-cxf-3.0:javaagent"))
+  testImplementation(project(":instrumentation:jaxws:jaxws-2.0-cxf-3.0:javaagent"))
 
   testImplementation("org.apache.cxf:cxf-rt-frontend-jaxws:3.0.0")
 }

…n/cxf/TracingStartInInterceptorTest.java …/v3_0/TracingStartInInterceptorTest.javainstrumentation/jaxws/jaxws-cxf-3.0/javaagent-unit-tests/src/test/java/io/opentelemetry/javaagent/instrumentation/cxf/TracingStartInInterceptorTest.java renamed to instrumentation/jaxws/jaxws-2.0-cxf-3.0/javaagent-unit-tests/src/test/java/io/opentelemetry/javaagent/instrumentation/jaxws/v2_0/cxf/v3_0/TracingStartInInterceptorTest.java instrumentation/jaxws/jaxws-cxf-3.0/javaagent-unit-tests/src/test/java/io/opentelemetry/javaagent/instrumentation/cxf/TracingStartInInterceptorTest.java renamed to instrumentation/jaxws/jaxws-2.0-cxf-3.0/javaagent-unit-tests/src/test/java/io/opentelemetry/javaagent/instrumentation/jaxws/v2_0/cxf/v3_0/TracingStartInInterceptorTest.java

@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package io.opentelemetry.javaagent.instrumentation.cxf;
+package io.opentelemetry.javaagent.instrumentation.jaxws.v2_0.cxf.v3_0;
 
 import static org.assertj.core.api.Assertions.assertThat;
 

…jaxws-cxf-3.0/javaagent/build.gradle.kts …s-2.0-cxf-3.0/javaagent/build.gradle.ktsinstrumentation/jaxws/jaxws-cxf-3.0/javaagent/build.gradle.kts renamed to instrumentation/jaxws/jaxws-2.0-cxf-3.0/javaagent/build.gradle.kts instrumentation/jaxws/jaxws-cxf-3.0/javaagent/build.gradle.kts renamed to instrumentation/jaxws/jaxws-2.0-cxf-3.0/javaagent/build.gradle.kts

@@ -3,9 +3,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package io.opentelemetry.javaagent.instrumentation.cxf;
+package io.opentelemetry.javaagent.instrumentation.jaxws.v2_0.cxf.v3_0;
 
-import static io.opentelemetry.javaagent.instrumentation.cxf.CxfSingletons.instrumenter;
+import static io.opentelemetry.javaagent.instrumentation.jaxws.v2_0.cxf.v3_0.CxfSingletons.instrumenter;
 
 import io.opentelemetry.context.Context;
 import io.opentelemetry.context.Scope;

…agent/instrumentation/cxf/CxfHelper.java …ation/jaxws/v2_0/cxf/v3_0/CxfHelper.javainstrumentation/jaxws/jaxws-cxf-3.0/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/cxf/CxfHelper.java renamed to instrumentation/jaxws/jaxws-2.0-cxf-3.0/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/jaxws/v2_0/cxf/v3_0/CxfHelper.java instrumentation/jaxws/jaxws-cxf-3.0/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/cxf/CxfHelper.java renamed to instrumentation/jaxws/jaxws-2.0-cxf-3.0/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/jaxws/v2_0/cxf/v3_0/CxfHelper.java

@@ -3,8 +3,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package io.opentelemetry.javaagent.instrumentation.cxf;
+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;
@@ -15,7 +16,7 @@
 @AutoService(InstrumentationModule.class)
 public class CxfInstrumentationModule extends InstrumentationModule {
   public CxfInstrumentationModule() {
-    super("cxf", "cxf-3.0", "jaxws");
+    super("cxf", expandDeprecatedNames("jaxws-2.0-cxf-3.0|deprecated:jaxws-cxf-3.0", "jaxws"));
   }
 
   @Override

…tation/cxf/CxfInstrumentationModule.java …0/cxf/v3_0/CxfInstrumentationModule.javainstrumentation/jaxws/jaxws-cxf-3.0/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/cxf/CxfInstrumentationModule.java renamed to instrumentation/jaxws/jaxws-2.0-cxf-3.0/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/jaxws/v2_0/cxf/v3_0/CxfInstrumentationModule.java instrumentation/jaxws/jaxws-cxf-3.0/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/cxf/CxfInstrumentationModule.java renamed to instrumentation/jaxws/jaxws-2.0-cxf-3.0/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/jaxws/v2_0/cxf/v3_0/CxfInstrumentationModule.java

@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package io.opentelemetry.javaagent.instrumentation.cxf;
+package io.opentelemetry.javaagent.instrumentation.jaxws.v2_0.cxf.v3_0;
 
 import org.apache.cxf.message.Exchange;
 import org.apache.cxf.message.Message;