Merge branch 'main' into use-has-value-satisfying

Author: trask

.editorconfig

@@ -761,3 +761,7 @@ ij_properties_spaces_around_key_value_delimiter = false
 [{*.yaml, *.yml}]
 ij_yaml_keep_indents_on_empty_lines = false
 ij_yaml_keep_line_breaks = true
+
+[*.md]
+# Markdown line length is handled by rumdl
+max_line_length = off

.fossa.yml

@@ -420,7 +420,7 @@ targets:
       target: ':instrumentation:cassandra:cassandra-4.4:library'
     - type: gradle
       path: ./
-      target: ':instrumentation:clickhouse:clickhouse-client-common:javaagent'
+      target: ':instrumentation:clickhouse:clickhouse-client-common-0.5:javaagent'
     - type: gradle
       path: ./
       target: ':instrumentation:clickhouse:clickhouse-client-v1-0.5:javaagent'
@@ -513,7 +513,7 @@ targets:
       target: ':instrumentation:hibernate:hibernate-6.0:javaagent'
     - type: gradle
       path: ./
-      target: ':instrumentation:hibernate:hibernate-common:javaagent'
+      target: ':instrumentation:hibernate:hibernate-common-3.3:javaagent'
     - type: gradle
       path: ./
       target: ':instrumentation:hibernate:hibernate-procedure-call-4.3:javaagent'
@@ -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'
@@ -591,7 +591,7 @@ targets:
       target: ':instrumentation:jedis:jedis-4.0:javaagent'
     - type: gradle
       path: ./
-      target: ':instrumentation:jedis:jedis-common:javaagent'
+      target: ':instrumentation:jedis:jedis-common-1.4:javaagent'
     - type: gradle
       path: ./
       target: ':instrumentation:jetty:jetty-11.0:javaagent'
@@ -624,10 +624,10 @@ targets:
       target: ':instrumentation:jms:jms-3.0:javaagent'
     - type: gradle
       path: ./
-      target: ':instrumentation:jms:jms-common:bootstrap'
+      target: ':instrumentation:jms:jms-common-1.1:bootstrap'
     - type: gradle
       path: ./
-      target: ':instrumentation:jms:jms-common:javaagent'
+      target: ':instrumentation:jms:jms-common-1.1:javaagent'
     - type: gradle
       path: ./
       target: ':instrumentation:jsf:jsf-common-jakarta:javaagent'
@@ -882,7 +882,7 @@ targets:
       target: ':instrumentation:redisson:redisson-3.17:javaagent'
     - type: gradle
       path: ./
-      target: ':instrumentation:redisson:redisson-common:javaagent'
+      target: ':instrumentation:redisson:redisson-common-3.0:javaagent'
     - type: gradle
       path: ./
       target: ':instrumentation:restlet:restlet-1.1:javaagent'
@@ -1131,7 +1131,7 @@ targets:
       target: ':instrumentation:play:play-ws:play-ws-2.1:javaagent'
     - type: gradle
       path: ./
-      target: ':instrumentation:play:play-ws:play-ws-common:javaagent'
+      target: ':instrumentation:play:play-ws:play-ws-common-1.0:javaagent'
     - type: gradle
       path: ./
       target: ':instrumentation:reactor:reactor-netty:reactor-netty-0.9:javaagent'
@@ -1194,7 +1194,7 @@ targets:
       target: ':instrumentation:vertx:vertx-http-client:vertx-http-client-5.0:javaagent'
     - type: gradle
       path: ./
-      target: ':instrumentation:vertx:vertx-http-client:vertx-http-client-common:javaagent'
+      target: ':instrumentation:vertx:vertx-http-client:vertx-http-client-common-3.0:javaagent'
     - type: gradle
       path: ./
       target: ':instrumentation:vertx:vertx-sql-client:vertx-sql-client-4.0:javaagent'
@@ -1203,7 +1203,7 @@ targets:
       target: ':instrumentation:vertx:vertx-sql-client:vertx-sql-client-5.0:javaagent'
     - type: gradle
       path: ./
-      target: ':instrumentation:vertx:vertx-sql-client:vertx-sql-client-common:javaagent'
+      target: ':instrumentation:vertx:vertx-sql-client:vertx-sql-client-common-4.0:javaagent'
 
 experimental:
   gradle:

.github/agents/code-review-and-fix.agent.md

@@ -178,27 +178,27 @@ Auto-fix boundaries:
     but absent from the current module's check (or vice versa) reveal a version boundary —
     the class was likely added or removed between versions.
     Then determine the comment form for each class:
-   **Positive floor class** (proves "at least version X"): look up when the class was
-   **introduced** → comment `// added in X.Y`.
-   **Positive ceiling class** (proves "not yet version Y"): look up when the class was
-   **removed** → comment `// removed in Y.Z` (meaning: its presence here ensures we
-   don't match version Y.Z+ where a different module takes over).
-   **Negated exclusion class** in `not(hasClassesNamed(...))`: look up when the class was
-   **introduced** → comment `// added in Y.Z`, because that first appearance begins the
-   excluded version range.
-   **Single positive class that provides both bounds**: include both facts in one comment,
-   e.g. `// added in X.Y, removed in Y.Z`.
-    A ceiling class might have been *introduced* much earlier than the module's target version.
-   Do not use `// added in` for a positive ceiling class — that is misleading. The relevant
-   fact is when it was **removed**. But for a negated exclusion class, `// added in` is the
-   correct form because the class's introduction is exactly what starts excluding newer versions.
-    Validate the version in the comment before adding or requesting it. Do not guess the
-    version from the module name alone; confirm it with repository or upstream evidence.
-    Sources: muzzle `versions.set(...)` ranges, sibling module `classLoaderMatcher()` checks,
-    module directory names, existing code comments, Javadoc/release notes.
-    Do NOT add a `classLoaderMatcher()` override where one does not already exist —
-    this method is only for version-boundary detection when muzzle is insufficient,
-    not for optimization (use `TypeInstrumentation.classLoaderOptimization()` instead)
+  **Positive floor class** (proves "at least version X"): look up when the class was
+  **introduced** → comment `// added in X.Y`.
+  **Positive ceiling class** (proves "not yet version Y"): look up when the class was
+  **removed** → comment `// removed in Y.Z` (meaning: its presence here ensures we
+  don't match version Y.Z+ where a different module takes over).
+  **Negated exclusion class** in `not(hasClassesNamed(...))`: look up when the class was
+  **introduced** → comment `// added in Y.Z`, because that first appearance begins the
+  excluded version range.
+  **Single positive class that provides both bounds**: include both facts in one comment,
+  e.g. `// added in X.Y, removed in Y.Z`.
+  A ceiling class might have been *introduced* much earlier than the module's target version.
+  Do not use `// added in` for a positive ceiling class — that is misleading. The relevant
+  fact is when it was **removed**. But for a negated exclusion class, `// added in` is the
+  correct form because the class's introduction is exactly what starts excluding newer versions.
+  Validate the version in the comment before adding or requesting it. Do not guess the
+  version from the module name alone; confirm it with repository or upstream evidence.
+  Sources: muzzle `versions.set(...)` ranges, sibling module `classLoaderMatcher()` checks,
+  module directory names, existing code comments, Javadoc/release notes.
+  Do NOT add a `classLoaderMatcher()` override where one does not already exist —
+  this method is only for version-boundary detection when muzzle is insufficient,
+  not for optimization (use `TypeInstrumentation.classLoaderOptimization()` instead)
   - redundant `isMethod()` in method matchers inside `transform()` when the matcher already
     names a specific, non-empty method (e.g., `isMethod().and(named("execute"))` →
     `named("execute")`). Do not remove `isMethod()` when the name could be empty —

.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()`.