Merge remote-tracking branch 'upstream/main' into class-loader-matcher

# Conflicts:
#	instrumentation/jaxrs/jaxrs-2.0/jaxrs-2.0-jersey-2.0/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/jaxrs/v2_0/JerseyInstrumentationModule.java

Author: trask

.fossa.yml

@@ -346,9 +346,6 @@ targets:
     - type: gradle
       path: ./
       target: ':instrumentation:armeria:armeria-grpc-1.14:javaagent'
-    - type: gradle
-      path: ./
-      target: ':instrumentation:async-http-client:async-http-client-1-common:javaagent'
     - type: gradle
       path: ./
       target: ':instrumentation:async-http-client:async-http-client-1.8:javaagent'
@@ -358,6 +355,9 @@ targets:
     - type: gradle
       path: ./
       target: ':instrumentation:async-http-client:async-http-client-2.0:javaagent'
+    - type: gradle
+      path: ./
+      target: ':instrumentation:async-http-client:async-http-client-common-1.8:javaagent'
     - type: gradle
       path: ./
       target: ':instrumentation:aws-lambda:aws-lambda-core-1.0:javaagent'
@@ -427,9 +427,6 @@ targets:
     - type: gradle
       path: ./
       target: ':instrumentation:clickhouse:clickhouse-client-v2-0.8:javaagent'
-    - type: gradle
-      path: ./
-      target: ':instrumentation:couchbase:couchbase-2-common:javaagent'
     - type: gradle
       path: ./
       target: ':instrumentation:couchbase:couchbase-2.0:javaagent'
@@ -448,6 +445,9 @@ targets:
     - type: gradle
       path: ./
       target: ':instrumentation:couchbase:couchbase-3.4:javaagent'
+    - type: gradle
+      path: ./
+      target: ':instrumentation:couchbase:couchbase-common-2.0:javaagent'
     - type: gradle
       path: ./
       target: ':instrumentation:dropwizard:dropwizard-metrics-4.0:javaagent'
@@ -630,10 +630,10 @@ targets:
       target: ':instrumentation:jms:jms-common:javaagent'
     - type: gradle
       path: ./
-      target: ':instrumentation:jsf:jsf-jakarta-common:javaagent'
+      target: ':instrumentation:jsf:jsf-common-javax:javaagent'
     - type: gradle
       path: ./
-      target: ':instrumentation:jsf:jsf-javax-common:javaagent'
+      target: ':instrumentation:jsf:jsf-jakarta-common:javaagent'
     - type: gradle
       path: ./
       target: ':instrumentation:jsf:jsf-mojarra-1.2:javaagent'
@@ -1092,7 +1092,7 @@ targets:
       target: ':instrumentation:jaxrs:jaxrs-2.0:jaxrs-2.0-resteasy-3.1:javaagent'
     - type: gradle
       path: ./
-      target: ':instrumentation:jaxrs:jaxrs-2.0:jaxrs-2.0-resteasy-common:javaagent'
+      target: ':instrumentation:jaxrs:jaxrs-2.0:jaxrs-2.0-resteasy-common-3.0:javaagent'
     - type: gradle
       path: ./
       target: ':instrumentation:jaxrs:jaxrs-3.0:jaxrs-3.0-annotations:javaagent'

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

@@ -139,6 +139,10 @@ Auto-fix boundaries:
 
 - Safe to fix:
   - import cleanup or direct style-guide conformance
+    **Extra step for shared/common modules**: when the modified file resides in a module
+    whose directory name contains `-common`, or whose Gradle path ends with `:testing`,
+    `:library`, or `:bootstrap`, **first search all sibling modules** under the same
+    instrumentation parent for callers of the type or member before applying the fix.
   - normalization of existing `@SuppressWarnings` syntax or placement, but preserve any
     accurate explanatory comment attached to the suppression instead of deleting it as
     style noise
@@ -152,6 +156,8 @@ Auto-fix boundaries:
     already valid AssertJ assertions; do not wrap them in `assertThat(...).isTrue()`
   - AssertJ `.as(...)` descriptions and `.withFailMessage(...)` in tests — remove them
     and prefer direct assertions whose failure output already exposes the unexpected values
+  - `@Test` method `throws` clauses — limit them to a single exception type and keep that type as
+    specific as possible.
   - deterministic semconv constant handling aligned with repository rules
   - missing test-task wiring patterns with clear canonical form
   - missing `testInstrumentation` cross-version references — when a javaagent module belongs
@@ -227,6 +233,10 @@ Auto-fix boundaries:
     readers/writers/streams/response bodies).
     Do not apply this conversion in non-JUnit helper methods, `@BeforeAll`, or shared
     setup code.
+  - class-scoped resources created in `@BeforeAll` or other shared setup — prefer
+    `AutoCleanupExtension` with `deferAfterAll(...)` over nested `@AfterAll` cleanup
+    chains. Do not introduce or keep `AutoCleanupExtension` solely for a single
+    `deferAfterAll(...)` call — use a plain `@AfterAll` instead.
   - `hasAttributesSatisfying(...)` calls in test assertions — replace with
     `hasAttributesSatisfyingExactly(...)` because it is more precise (the non-exact
     variant silently ignores unexpected attributes)
@@ -295,6 +305,12 @@ Auto-fix boundaries:
     add the correctly named/shaped method with the implementation, deprecate the old method
     to delegate to the new one, and add a `@deprecated` Javadoc tag naming the replacement.
     For stable modules, annotate instead: the fix requires a broader compatibility decision.
+    **Exception — javaagent modules**: javaagent modules (Gradle path ends with `:javaagent`,
+    including shared `-common` javaagent modules) are bundled into the agent jar and are not
+    a public API. Do **not** apply a deprecation cycle; rename or change the API directly
+    and update all in-repo callers in the same commit. A deprecation cycle is only required
+    for non-stable modules whose artifacts are published for external consumption (e.g.,
+    `:library`, `:testing`, `instrumentation-api*`).
 - Do not auto-fix (report in the final output instead):
   - missing `testExperimental` task — when experimental flags are set unconditionally
     on all test tasks instead of being isolated in a dedicated task
@@ -397,22 +413,30 @@ Execute these steps strictly in order — do not reorder:
       pre-existing failure — note it in the final output but do not block the commit.
    5. Never commit code that fails tests you can reproduce locally.
 
-   **Testing-module dependent validation**: when any modified module is a `testing` module
-   (its Gradle path ends with `:testing`), you must **also** run `:check` (both normal and
-   `-PtestLatestDeps=true`) for every sibling `library` and `javaagent` module under the
-   same instrumentation parent. `testing` modules contain shared abstract test base classes
-   consumed by those siblings — changes to visibility, method signatures, or class structure
-   in the `testing` module can break compilation or tests in dependent modules.
-
-   To find siblings, list the parent directory of the `testing` module and look for
+   **Shared-module dependent validation**: when any modified module is a shared module
+   consumed by sibling instrumentation modules, you must **also** run `:check` (both normal
+   and `-PtestLatestDeps=true`) for every sibling `library` and `javaagent` module under the
+   same instrumentation parent. A module is shared if its Gradle path ends with `:testing`,
+   or its directory name contains `-common` (e.g., `couchbase-2-common`, `netty-common`),
+   or it is named `library`, `bootstrap`, or `testing-common`. Changes to visibility,
+   method signatures, or class structure in a shared module can break compilation or tests
+   in dependent sibling modules — including failures that compile cleanly but throw
+   `IllegalAccessError` at runtime inside ByteBuddy advice.
+
+   To find siblings, list the parent directory of the shared module and look for
    `library/`, `javaagent/`, and any version-variant directories that contain `library/`
-   or `javaagent/` submodules. Run `:check` for each.
+   or `javaagent/` submodules. Also check `settings.gradle.kts` for every module under
+   the same instrumentation group. Run `:check` for each sibling that transitively
+   depends on the modified shared module.
 
    Example: if you modify files in
    `:instrumentation:foo:foo-1.0:testing`, also run `:check` for
    `:instrumentation:foo:foo-1.0:library`,
    `:instrumentation:foo:foo-1.0:javaagent`, and any version-variant siblings such as
    `:instrumentation:foo:foo-2.0:library` if it depends on the `foo-1.0:testing` module.
+   Likewise, if you modify files in `:instrumentation:couchbase:couchbase-2-common:javaagent`,
+   also run `:check` for `:instrumentation:couchbase:couchbase-2.0:javaagent` and
+   `:instrumentation:couchbase:couchbase-2.6:javaagent`.
 
    Do not move on to step 2 until every required `:check` run from this step, including
    sibling-module validation and any re-runs after fixes or reverts, has fully completed

.github/agents/knowledge/README.md

@@ -18,7 +18,7 @@ Load only files relevant to the current scope to reduce noise and avoid over-con
 | `javaagent-singletons-patterns.md` | `*Singletons` holder classes, singleton accessors, callers of singleton accessors/fields |
 | `library-patterns.md` | Library instrumentation telemetry, builder, getter, or setter pattern changes |
 | `module-naming.md` | New or renamed modules or packages; settings includes |
-| `testing-general-patterns.md` | Test files in scope — assertion style, resource cleanup patterns, attribute assertion patterns, `satisfies()` lambda usage |
+| `testing-general-patterns.md` | Test files in scope — assertion style, test method signatures and throws clauses, resource cleanup patterns, attribute assertion patterns, `satisfies()` lambda usage |
 | `testing-experimental-flags.md` | `testExperimental` task or experimental span-attribute assertions |
 | `testing-semconv-stability.md` | Semconv opt-in modes, `emitOld*`/`emitStable*`, `maybeStable`, Semconv test tasks |
 

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

@@ -18,6 +18,15 @@ The CHANGELOG uses distinct headings to distinguish:
 - `⚠️ Breaking changes to non-stable APIs` — alpha/non-stable modules (routine)
 - `⚠️ Breaking Changes` — stable module changes (rare, requires strong justification)
 
+### Javaagent modules are not a public API
+
+Javaagent modules (Gradle path ends with `:javaagent`, including shared `-common` javaagent
+modules) are bundled into the agent jar and are **not** published for external consumption.
+Do **not** apply a deprecation cycle to symbols in javaagent modules — rename or change the
+API directly and update all in-repo callers in the same commit. The deprecate-then-remove
+cycle described below applies only to non-stable modules whose artifacts are published
+(e.g., `:library`, `:testing`, `instrumentation-api*`).
+
 ## The Deprecate-Then-Remove Cycle
 
 ### Alpha (non-stable) modules

.github/agents/knowledge/general-rules.md

@@ -25,7 +25,7 @@ When a "Knowledge File" is listed, load it from `knowledge/` before reviewing th
 | Javaagent | Incorrect `classLoaderMatcher()` | `classLoaderMatcher()` override that is redundant (muzzle already handles it) or missing when needed (muzzle cannot distinguish version range) | `javaagent-module-patterns.md` |
 | Semconv | Library vs javaagent semconv constant usage | Semconv constants/assertions | — |
 | Semconv | Dual semconv testing | `SemconvStability`, `maybeStable`, semconv Gradle tasks | `testing-semconv-stability.md` |
-| Testing | General test patterns | Test files in scope — assertion style, resource cleanup, attribute assertions | `testing-general-patterns.md` |
+| Testing | General test patterns | Test files in scope — assertion style, test method signatures and throws clauses, resource cleanup, attribute assertions | `testing-general-patterns.md` |
 | Testing | Experimental flag tests | `testExperimental`, experimental attribute assertions, `experimental` flags in JVM args or system properties | `testing-experimental-flags.md` |
 | Library | TelemetryBuilder/getter/setter patterns | Library instrumentation classes | `library-patterns.md` |
 | API | Deprecation and breaking-change policy | Public API changes | `api-deprecation-policy.md` |

.github/agents/knowledge/gradle-conventions.md

@@ -188,7 +188,7 @@ module it extends) imports or instantiates Testcontainers types (`GenericContain
 rely solely on the presence of an `org.testcontainers:*` dependency in `build.gradle.kts`,
 because the dependency may only be used by some suites in the module.
 
-## Prefer `withType<Test>().configureEach` (when multiple test tasks exist)
+## Prefer `withType<Test>().configureEach` (ONLY when multiple test tasks exist)
 
 When a module has custom test tasks (e.g., `testStableSemconv`), system properties and JVM
 args that apply to **all** test tasks should be set once in a `withType<Test>().configureEach`
@@ -197,13 +197,24 @@ block, not repeated on each individual task.
 If a property or JVM arg is moved into `withType<Test>().configureEach`, remove any now-redundant
 copies from individual tasks unless a task intentionally overrides the shared value.
 
-When there is only one test task, `tasks.test { ... }` is fine — do not convert it to
-`withType<Test>().configureEach` and do not flag it.
+When the module's `build.gradle.kts` does not explicitly register additional `Test` tasks,
+`tasks.test { ... }` is fine — **do not** convert it to `withType<Test>().configureEach` and
+do not flag it.
 
-**How to spot violations:** If `build.gradle.kts` has both a `test { ... }` block and a
-custom test task (e.g., `val testStableSemconv by registering(Test::class)`), check whether
-any `systemProperty(...)` or `jvmArgs(...)` calls appear inside the `test { }` block that
-should apply to all tasks. If so, move them to `withType<Test>().configureEach`.
+**`latestDepTest` does not count as a second test task for this rule.** It is registered
+implicitly by the convention plugin when `testLatestDeps` is set, and it inherits the
+configuration of `tasks.test`. A module with only a `tasks.test { ... }` block and no
+`by registering(Test::class)` declarations is a single-test-task module — leave it alone
+even if `testLatestDeps = true`.
+
+Only consider converting to `withType<Test>().configureEach` when the **same
+`build.gradle.kts`** explicitly registers one or more additional `Test` tasks via
+`val foo by registering(Test::class)`.
+
+**How to spot violations:** If `build.gradle.kts` has both a `test { ... }` block and an
+explicit `by registering(Test::class)` custom test task (e.g., `testStableSemconv`), check
+whether any `systemProperty(...)` or `jvmArgs(...)` calls appear inside the `test { }` block
+that should apply to all tasks. If so, move them to `withType<Test>().configureEach`.
 
 ```kotlin
 tasks {
@@ -232,7 +243,8 @@ review**. Only verify correctness when they are already present.
 
 When already present, verify:
 
-- `collectMetadata` is in `withType<Test>().configureEach` (or `tasks.test` if only one test
-  task) — never on individual tasks.
+- `collectMetadata` is in `withType<Test>().configureEach` (or `tasks.test` if the module
+  does not explicitly register additional `Test` tasks — `latestDepTest` does not count) —
+  never on individual tasks.
 - `metadataConfig` is on each non-default task, not on the default `test` task.
 - The `metadataConfig` value matches at least one of the jvmArgs configured in the task

.github/agents/knowledge/javaagent-singletons-patterns.md

@@ -17,7 +17,9 @@ Javaagent modules keep shared `Instrumenter` instances and related collaborators
   `"io.opentelemetry.<module-name>"`.
 - For exported collaborators, keep the field `private`, use a lower camel case field name, and
   give the accessor method the exact same name as the field. Do not prefix these accessors with
-  `get`.
+  `get`. This rule applies only to zero-arg methods that directly return a stored singleton
+  field; methods that take arguments or compute a value are not singleton accessors and keep
+  their normal names (including `get*` when appropriate).
   - `instrumenter` -> `instrumenter()`
   - `helper` -> `helper()`
   - `setter` -> `setter()`
@@ -34,6 +36,9 @@ Javaagent modules keep shared `Instrumenter` instances and related collaborators
 - Keep verb-named helper methods as verbs when they perform work instead of returning a stored
   field. These methods are not singleton accessors and should not be static imported under this
   rule.
+- Methods on a `*Singletons` class that take arguments (for example `addressAndPort(client)` or
+  `getAddressAndPort(client)`) are not singleton accessors. Do not apply the field-style
+  accessor naming rule to them, and do not flag their `get*` prefix on that basis.
 
 ## Preferred Pattern
 
@@ -103,7 +108,8 @@ class MyInstrumentation implements TypeInstrumentation {
   final` field would be clearer and matches the naming guidance, including semantic keys/handles
   and immutable value constants.
 - Accessor methods named `getInstrumenter()`, `getHelper()`, `getSetter()`, and similar when they
-  simply return a backing field.
+  simply return a backing field. Do not flag `get*`-prefixed methods that take arguments or
+  compute a value rather than returning a stored singleton field.
 - Call sites that qualify singleton accessor or uppercase constant-like field usage with the holder
   class instead of static importing the accessor or field.
 - Static imports of non-accessor helper methods on a `*Singletons` class when the method performs

.github/agents/knowledge/metadata-yaml-format.md

@@ -49,8 +49,8 @@ For `otel.instrumentation.*` properties not in SPECIAL_MAPPINGS:
 1. Strip `otel.instrumentation.` prefix
 2. Replace `-` with `_` (kebab-case → snake_case)
 3. Handle `experimental`:
-   - `experimental.` path segment → remove, add `/development` to next segment
-   - `experimental-` in name → add `/development` to that segment
+   - `experimental.` as a separate path segment → **remove** it, add `/development` to next segment
+   - `experimental-` as a prefix within a segment name → **keep** it (as `experimental_`), add `/development` to that segment
 4. Prepend `java.`
 
 Examples:
@@ -59,9 +59,15 @@ Examples:
 |------------------------------------------------------------------------------|-------------------------------------------------------------|
 | `otel.instrumentation.grpc.emit-message-events`                              | `java.grpc.emit_message_events`                             |
 | `otel.instrumentation.grpc.experimental-span-attributes`                     | `java.grpc.experimental_span_attributes/development`        |
+| `otel.instrumentation.aws-sdk.experimental-span-attributes`                  | `java.aws_sdk.experimental_span_attributes/development`     |
 | `otel.instrumentation.logback-appender.experimental.capture-code-attributes` | `java.logback_appender.capture_code_attributes/development` |
 | `otel.instrumentation.common.experimental.controller-telemetry.enabled`      | `java.common.controller_telemetry/development.enabled`      |
 
+**Key distinction**:
+
+- `experimental-span-attributes` (hyphenated compound) → `experimental_span_attributes/development` (prefix **kept**)
+- `experimental.capture-code-attributes` (separate segment) → `capture_code_attributes/development` (segment **removed**)
+
 ## Examples Guidelines
 
 Add `examples` only for module-specific configs with non-obvious format (lists, patterns, enums).