Merge remote-tracking branch 'upstream/main' into declarative-config-thread-details-provider2

# Conflicts:
#	javaagent-extension-api/src/main/java/io/opentelemetry/javaagent/extension/instrumentation/internal/AgentDistributionConfig.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'
@@ -835,9 +835,6 @@ targets:
     - type: gradle
       path: ./
       target: ':instrumentation:opentelemetry-api:opentelemetry-api-1.50:javaagent'
-    - type: gradle
-      path: ./
-      target: ':instrumentation:opentelemetry-api:opentelemetry-api-1.52:javaagent'
     - type: gradle
       path: ./
       target: ':instrumentation:opentelemetry-api:opentelemetry-api-1.56:javaagent'
@@ -910,15 +907,9 @@ targets:
     - type: gradle
       path: ./
       target: ':instrumentation:runtime-telemetry:runtime-telemetry-java17:javaagent'
-    - type: gradle
-      path: ./
-      target: ':instrumentation:runtime-telemetry:runtime-telemetry-java17:library'
     - type: gradle
       path: ./
       target: ':instrumentation:runtime-telemetry:runtime-telemetry-java8:javaagent'
-    - type: gradle
-      path: ./
-      target: ':instrumentation:runtime-telemetry:runtime-telemetry-java8:library'
     - type: gradle
       path: ./
       target: ':instrumentation:rxjava:rxjava-1.0:library'
@@ -1095,7 +1086,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'
@@ -1171,9 +1162,6 @@ targets:
     - type: gradle
       path: ./
       target: ':instrumentation:spring:spring-jms:spring-jms-6.0:javaagent'
-    - type: gradle
-      path: ./
-      target: ':instrumentation:spring:spring-web:spring-web-3.1:javaagent'
     - type: gradle
       path: ./
       target: ':instrumentation:spring:spring-web:spring-web-3.1:library'

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

@@ -28,6 +28,7 @@ Always load:
 
 - `docs/contributing/style-guide.md`
 - `knowledge/general-rules.md` — review checklist and core rules
+- `knowledge/metadata-yaml-format.md` — **MANDATORY** for any instrumentation module
 
 Load other knowledge files only when their scope trigger applies.
 Use the **Knowledge File** column in the checklist table.
@@ -103,6 +104,10 @@ Scope rules:
 
 ### Phase 3: Review and Fix
 
+**Before reviewing source files**: For each instrumentation module in scope, execute the full
+`metadata-yaml-format.md` validation procedure on its `metadata.yaml`. This is mandatory
+regardless of whether metadata.yaml was modified in the PR.
+
 For each file in scope:
 
 1. Skip non-reviewable files:
@@ -134,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
@@ -147,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
@@ -222,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)
@@ -240,6 +255,10 @@ Auto-fix boundaries:
   - redundant `if (value != null)` guards around `AttributesBuilder.put()` calls —
     `put` is a no-op for null values, so remove the conditional and pass the value
     directly (same for span, log, and metrics attribute setters).
+    Apply this only when the guarded value can be passed through directly to the
+    attribute setter. If the null check is guarding a dereference or other derived
+    computation, keep the explicit guard instead of rewriting it into a ternary
+    expression just to pass `null` to `put()`.
     **Exception**: when the `AttributeKey` is typed as `Long` and the source value is
     `Integer`, the generic overload cannot match (`Integer ≠ Long`), so Java resolves
     to the `int` convenience overload `put(AttributeKey<Long>, int)` via auto-unboxing.
@@ -248,6 +267,8 @@ Auto-fix boundaries:
     When the value type **matches** the `AttributeKey` type parameter (e.g.,
     `Boolean` → `AttributeKey<Boolean>`, `Long` → `AttributeKey<Long>`), the generic
     `@Nullable T` overload is selected directly, null is safe, and the guard is redundant.
+    For example, keep `if (view != null) { attributes.put(KEY, view.getClass().getName()); }`
+    as-is; do not rewrite it to `attributes.put(KEY, view == null ? null : view.getClass().getName())`.
   - defensive `if (param == null)` checks on parameters not annotated `@Nullable` —
     these contradict the framework's nullability contract; remove the guard. Conversely,
     add `@Nullable` to a parameter only when `null` is actually passed by callers or an
@@ -284,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
@@ -293,9 +320,9 @@ Auto-fix boundaries:
 - Never change:
   - literal type suffixes (e.g., `200` → `200L` or vice-versa) — Java widens
     automatically; both forms compile identically and the change is noise
-  - non-capturing lambdas or method references as unnecessary allocations; do not flag or
-    fix these, because on modern JDKs these are typically cached at the call site rather
-    than allocated on every invocation
+  - non-capturing lambdas or method references as allocation issues; do not flag,
+    fix, or justify changes to these as per-call allocations. On HotSpot /
+    OpenJDK 8+, these are cached at the call site.
 
 Output content rules:
 
@@ -386,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/code-review.agent.md

@@ -91,9 +91,8 @@ For each file in scope:
    - PR mode: changed lines only
    - File/directory mode: all lines
 4. Apply checklist rules (below) and insert comments above offending lines.
-5. Do not flag a non-capturing lambda or method reference as an unnecessary allocation,
-   because on modern JDKs these are typically cached at the call site rather than
-   allocated on every invocation.
+5. Do not flag a non-capturing lambda or method reference as an allocation issue.
+   On HotSpot / OpenJDK 8+, these are cached at the call site.
 6. Flag a missing version-boundary comment on a single-class `hasClassesNamed(...)`
    check in `classLoaderMatcher()` only after validating the stated boundary from
    repository or upstream evidence. Use `// added in X.Y` for a pure lower bound.

.github/agents/knowledge/README.md

@@ -11,13 +11,14 @@ Load only files relevant to the current scope to reduce noise and avoid over-con
 | `api-deprecation-policy.md` | Public API removal, rename, or deprecation; stable vs alpha breaking changes |
 | `config-property-stability.md` | `otel.instrumentation.*` property add, remove, rename, or deprecation |
 | `general-rules.md` | Always — review checklist table and core rules enforced on every review |
+| `metadata-yaml-format.md` | Always — mandatory review of metadata.yaml for config coverage |
 | `gradle-conventions.md` | `build.gradle.kts` or `settings.gradle.kts` changes, custom test task registration or wiring |
 | `javaagent-advice-patterns.md` | ByteBuddy `@Advice` class or advice-method changes |
 | `javaagent-module-patterns.md` | `InstrumentationModule`, `TypeInstrumentation`, `VirtualField`, `CallDepth` |
 | `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