Merge branch 'main' into use-contains-points-satisfying

Author: trask

.fossa.yml

@@ -367,9 +367,6 @@ targets:
     - type: gradle
       path: ./
       target: ':instrumentation:aws-lambda:aws-lambda-events-2.2:javaagent'
-    - type: gradle
-      path: ./
-      target: ':instrumentation:aws-lambda:aws-lambda-events-2.2:library'
     - type: gradle
       path: ./
       target: ':instrumentation:aws-lambda:aws-lambda-events-3.11:library'
@@ -570,7 +567,7 @@ targets:
       target: ':instrumentation:jaxws:jaxws-2.0-metro-2.2:javaagent'
     - type: gradle
       path: ./
-      target: ':instrumentation:jaxws:jaxws-common:javaagent'
+      target: ':instrumentation:jaxws:jaxws-common-2.0:javaagent'
     - type: gradle
       path: ./
       target: ':instrumentation:jaxws:jaxws-jws-api-1.1:javaagent'
@@ -1053,7 +1050,7 @@ targets:
       target: ':instrumentation:xxl-job:xxl-job-2.3.0:javaagent'
     - type: gradle
       path: ./
-      target: ':instrumentation:xxl-job:xxl-job-common:javaagent'
+      target: ':instrumentation:xxl-job:xxl-job-common-1.9.2:javaagent'
     - type: gradle
       path: ./
       target: ':instrumentation:zio:zio-2.0:javaagent'

.gitattributes

@@ -4,3 +4,5 @@
 *.cmd text eol=crlf
 
 licenses/** linguist-generated
+
+.github/workflows/*.lock.yml linguist-generated=true merge=ours

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

@@ -15,7 +15,7 @@ Load only files relevant to the current scope to reduce noise and avoid over-con
 | `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 |
+| `javaagent-singletons-patterns.md` | `*Singletons`, `*SpanNaming`, and similar 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, test method signatures and throws clauses, resource cleanup patterns, attribute assertion patterns, `satisfies()` lambda usage |

.github/agents/knowledge/README.md

@@ -21,7 +21,7 @@ When a "Knowledge File" is listed, load it from `knowledge/` before reviewing th
 | Naming | Module/package naming | New or renamed modules/packages | `module-naming.md` |
 | Javaagent | Advice patterns | `@Advice` classes | `javaagent-advice-patterns.md` |
 | Javaagent | Module structure patterns | `InstrumentationModule`, `TypeInstrumentation` | `javaagent-module-patterns.md` |
-| Javaagent | Singletons patterns | `*Singletons` holder classes, singleton accessors, callers of singleton accessors/fields | `javaagent-singletons-patterns.md` |
+| Javaagent | Singletons patterns | `*Singletons`, `*SpanNaming`, and similar holder classes; singleton accessors; callers of singleton accessors/fields | `javaagent-singletons-patterns.md` |
 | 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` |
@@ -34,8 +34,9 @@ When a "Knowledge File" is listed, load it from `knowledge/` before reviewing th
 | Config | metadata.yaml format and declarative_name conversion — Mandatory for every instrumentation module | Any instrumentation module in scope (javaagent, library, or testing) | `metadata-yaml-format.md` |
 | Build | Gradle conventions, muzzle, test tasks, plugins | `build.gradle.kts`, `settings.gradle.kts` | `gradle-conventions.md` |
 | Build | `testcontainersBuildService` declaration | Testcontainers dependency without `usesService` | `gradle-conventions.md` |
-| Style | Prefer instance creation over singletons for stateless interface impls (except on hot paths or Kotlin `object` declarations) | `TextMapGetter`, `TextMapSetter`, `*AttributesGetter`, `AttributesExtractor`, `SpanNameExtractor`, `HttpServerResponseMutator`, enum/static singletons | — |
+| Style | Prefer instance creation over singletons for stateless interface impls (except on hot paths or Kotlin `object` declarations) | `TextMapGetter`, `TextMapSetter`, `*AttributesGetter`, `AttributesExtractor`, `SpanNameExtractor`, enum/static singletons | — |
 | Style | Prefer `value == null` / `value != null` over `null == value` / `null != value` | Null comparisons | — |
+| Style | Do not rewrite `value.equals(CONSTANT)` to `CONSTANT.equals(value)` solely for defensive null-safety; first verify that `value` can be null and that treating null as non-equal is the intended behavior | `.equals(...)` comparisons | — |
 | Style | No unnecessary explicit type witnesses on generic method calls (`Collections.<String>emptyList()`) | Java generic method calls with explicit type parameters | — |
 | Style | Remove redundant null guards on attribute puts | `AttributesBuilder.put`, `onStart`, `onEnd`, attribute extraction methods | — |
 | General | No redundant `ByteBuffer.duplicate()` on `Value.getValue()` | `Value.getValue()` with `BYTES` type, `ByteBuffer` handling | — |
@@ -125,6 +126,15 @@ Reason about visibility from "what does the advice method directly reference?".
 
 Public API getters should use `get*` (or `is*` for booleans).
 
+## [Style] Equals Comparisons
+
+Prefer the natural receiver form, such as `value.equals(CONSTANT)`, when `value` is expected to be
+non-null. Do not flip operands to `CONSTANT.equals(value)` as a blanket null-safety cleanup.
+
+If `value` can actually be null, first decide whether null should be tolerated or should fail fast.
+Use an explicit null check or `Objects.equals(...)` when null is part of the valid contract; otherwise
+keep the dereference so an unexpected null is visible.
+
 ## [Style] Catch Exception Variable Naming
 
 Prefer `e` as the exception variable name in catch clauses when the exception is
@@ -152,9 +162,8 @@ recognizes `expected` and `ok`.
 ## [Style] Prefer Instance Creation Over Singletons
 
 Stateless implementations of telemetry interfaces — `TextMapGetter`, `TextMapSetter`,
-`*AttributesGetter`, `AttributesExtractor`, `SpanNameExtractor`,
-`HttpServerResponseMutator` — should use instance creation (`new MyGetter()`) instead of
-singleton patterns.
+`*AttributesGetter`, `AttributesExtractor`, `SpanNameExtractor` — should use instance creation
+(`new MyGetter()`) instead of singleton patterns.
 
 Replace every singleton reference (`MyGetter.INSTANCE`, `MyGetter.getInstance()`) with
 `new MyGetter()`. Do not restructure surrounding code — if the original used a local

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

@@ -266,20 +266,27 @@ These system properties support the metadata collection pipeline. They are not r
 test correctness and are being added as a separate migration — **do not add them during
 review**. Only verify correctness when they are already present.
 
+Do not add `collectMetadata` or `metadataConfig` to `javaagent-unit-tests` projects. These are
+unit tests, and metadata collection should not run there.
+
 | Property | Type | Value |
 | --- | --- | --- |
 | `collectMetadata` | System property | Pass-through of `otelProps.collectMetadata`; defaults to `false` |
 | `metadataConfig` | System property | A single `key=value` string describing the non-default configuration active during this test run |
 
 When already present, verify:
 
+- `metadataConfig` is only used in files that also configure `collectMetadata`. A lone
+  `metadataConfig` does not enable collection and should be removed, not added as a partial
+  metadata migration.
 - `collectMetadata` is in `tasks.test` for single-test-task modules, or in
   `withType<Test>().configureEach` for modules that explicitly register additional `Test`
   tasks via `by registering(Test::class)` (`latestDepTest` does not count) — never on
   individual tasks. Do not use
   `withType<Test>().configureEach { ... }` in single-test-task modules.
-- `metadataConfig` is on each non-default task. It may also appear on the default `test`
-  task when that task itself runs with non-default `jvmArgs` (e.g., an experimental flag
-  enabled module-wide via `withType<Test>().configureEach { jvmArgs(...) }`); in that case
-  the `metadataConfig` value should describe those non-default jvmArgs.
+- `metadataConfig` is on each non-default task that participates in metadata collection. It may
+  also appear on the default `test` task when that task participates in metadata collection and
+  itself runs with non-default `jvmArgs` (e.g., an experimental flag enabled module-wide via
+  `withType<Test>().configureEach { jvmArgs(...) }`); in that case the `metadataConfig` value
+  should describe those non-default jvmArgs.
 - The `metadataConfig` value matches at least one of the jvmArgs configured in the task

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

@@ -42,7 +42,9 @@ the IDE's perspective, and per-method placement is inconsistent with the rest of
 ## Advice Methods Must Be Static
 
 All `@Advice.OnMethodEnter` and `@Advice.OnMethodExit` methods **must be `static`**. ByteBuddy
-inlines advice code directly into the instrumented method — there is no advice object instance.
+inlines advice code directly into the instrumented method by default — there is no advice object
+instance. Do not add or remove `inline = false` as cleanup; it is a semantic signal used by
+muzzle/indy tooling.
 
 ```java
 // ✅ Correct

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

@@ -2,11 +2,13 @@
 
 ## Quick Reference
 
-- Use when: reviewing `*Singletons` holder classes and their callers
+- Use when: reviewing `*Singletons`, `*SpanNaming`, and similar holder classes and their callers
 - Review focus: field/accessor naming, eager initialization, singleton accessor call sites
 
 Javaagent modules keep shared `Instrumenter` instances and related collaborators in a dedicated
-`Singletons` holder class such as `MyLibrarySingletons`.
+`Singletons` holder class such as `MyLibrarySingletons`. Some modules also use focused helper
+holders such as `*ServerSpanNaming` for shared span-name or route-name collaborators; apply the
+same accessor and call-site rules when these classes expose stored singleton fields.
 
 ## Rules
 
@@ -18,8 +20,10 @@ Javaagent modules keep shared `Instrumenter` instances and related collaborators
 - 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`. 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).
+  field. It applies regardless of whether the holder class is named `*Singletons`,
+  `*ServerSpanNaming`, or another focused holder name. 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()`
@@ -32,7 +36,9 @@ Javaagent modules keep shared `Instrumenter` instances and related collaborators
   - `RESPONSE_STATUS` stays `RESPONSE_STATUS`
 - Callers should static import only exported singleton accessors and uppercase constant-like
   fields, and use those members unqualified: accessors for lower camel collaborators, fields for
-  uppercase constant-like members.
+  uppercase constant-like members. This includes route/span naming accessors such as
+  `serverSpanName()` when they simply return a stored `HttpServerRouteGetter` or similar
+  collaborator.
 - 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.

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

@@ -87,6 +87,12 @@ Add `examples` only for module-specific configs with non-obvious format (lists,
 ### 1. Validate experimental markers match
 
 - `/development` in declarative_name ↔ `experimental` in flat name (MUST match both ways)
+- Do not rename an existing, published `declarative_name` solely to make it match the mechanical
+  conversion rule. Flat property lookup normalizes `-` to `.`, so a legacy YAML key such as
+  `java.aws_sdk.use_propagator_for_messaging/development` can still resolve to
+  `otel.instrumentation.aws-sdk.experimental-use-propagator-for-messaging` without a special
+  mapping. Let the automated validation decide whether a `SPECIAL_MAPPINGS` entry is actually
+  needed.
 - WRONG: `otel.instrumentation.servlet.capture-request-parameters` + `java.servlet.capture_request_parameters/development`
 - RIGHT: `otel.instrumentation.servlet.experimental.capture-request-parameters` + `java.servlet.capture_request_parameters/development`
 
@@ -152,4 +158,6 @@ FAIL in ../instrumentation/liberty/liberty-20.0/metadata.yaml:
 ## Edge Cases
 
 - Properties without `otel.instrumentation.` prefix → check SPECIAL_MAPPINGS
-- Already has declarative_name → skip conversion
+- Already has declarative_name → skip conversion unless the automated validation fails; preserve
+  existing user-facing YAML keys and add a `SPECIAL_MAPPINGS` bridge entry only when normalized flat
+  property lookup cannot resolve the existing name