Merge remote-tracking branch 'upstream/main' into copilot/rename-jaxws-modules

Author: trask

.fossa.yml

@@ -630,10 +630,10 @@ targets:
       target: ':instrumentation:jms:jms-common:javaagent'
     - type: gradle
       path: ./
-      target: ':instrumentation:jsf:jsf-common-javax:javaagent'
+      target: ':instrumentation:jsf:jsf-common-jakarta: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-mojarra-1.2:javaagent'
@@ -904,12 +904,6 @@ targets:
     - type: gradle
       path: ./
       target: ':instrumentation:rocketmq:rocketmq-client-5.0:javaagent'
-    - type: gradle
-      path: ./
-      target: ':instrumentation:runtime-telemetry:runtime-telemetry-java17:javaagent'
-    - type: gradle
-      path: ./
-      target: ':instrumentation:runtime-telemetry:runtime-telemetry-java8:javaagent'
     - type: gradle
       path: ./
       target: ':instrumentation:rxjava:rxjava-1.0:library'

.github/agents/draft-release-notes.agent.md

@@ -67,10 +67,10 @@ must be communicated through:
    (`otel.instrumentation.…`) since that is what most users configure today:
 
    ```java
-   boolean captureEventName = config.getBoolean("capture_event_name/development", false);
-   if (captureEventName) {
+   boolean oldSetting = config.getBoolean("old_setting/development", false);
+   if (oldSetting) {
      logger.warning(
-         "The otel.instrumentation.logback-appender.experimental.capture-event-name setting is"
+         "The otel.instrumentation.<module>.experimental.old-setting setting is"
              + " deprecated and will be removed in a future version.");
    }
    ```

.github/agents/knowledge/config-property-stability.md

@@ -90,10 +90,39 @@ For multi-class checks, and for negated exclusions, add a version comment **abov
 name string**.
 
 - **Positive floor class** in `hasClassesNamed(...)`: use `// added in X.Y`.
+  When the landmark class comes from a different artifact than the instrumentation's usual
+  library module, choose the form based on what the comment is documenting:
+  - If the version boundary is for that different artifact itself, use
+    `// added in groupId:artifactId X.Y`.
+  - If the comment is documenting the main library-module boundary or an optional-component
+    presence condition that happens via a different artifact, use
+    `// added in X.Y (via groupId:artifactId A.B)`.
+  - For `javax.servlet:javax.servlet-api` and `jakarta.servlet:jakarta.servlet-api`, use the
+    shorthand `Servlet` instead of the full Maven coordinate, for example `// added in Servlet
+    5.0` or `// added in X.Y (via Servlet 5.0)`.
 - **Positive ceiling class** in `hasClassesNamed(...)`: use `// removed in Y.Z`.
+  When the landmark class comes from a different artifact than the instrumentation's usual
+  library module, choose the form based on what the comment is documenting:
+  - If the version boundary is for that different artifact itself, use
+    `// removed in groupId:artifactId Y.Z`.
+  - If the comment is documenting the main library-module boundary through a class that is
+    supplied by a different artifact, use `// removed in Y.Z (via groupId:artifactId A.B)`.
+  - For `javax.servlet:javax.servlet-api` and `jakarta.servlet:jakarta.servlet-api`, use the
+    shorthand `Servlet` instead of the full Maven coordinate, for example `// removed in Servlet
+    5.0` or `// removed in Y.Z (via Servlet 5.0)`.
 - **Negated exclusion class** in `not(hasClassesNamed(...))` or
   `.and(not(hasClassesNamed(...)))`: use `// added in Y.Z`, because that class's first
   appearance is what starts excluding `Y.Z+`.
+  When the landmark class comes from a different artifact than the instrumentation's usual
+  library module, choose the form based on what the comment is documenting:
+  - If the excluded range begins when that different artifact appears, use
+    `// added in groupId:artifactId Y.Z`.
+  - If the excluded range is described in terms of the main library-module version but the
+    landmark class is supplied by a different artifact, use
+    `// added in Y.Z (via groupId:artifactId A.B)`.
+  - For `javax.servlet:javax.servlet-api` and `jakarta.servlet:jakarta.servlet-api`, use the
+    shorthand `Servlet` instead of the full Maven coordinate, for example `// added in Servlet
+    5.0` or `// added in Y.Z (via Servlet 5.0)`.
 
 You may add brief parenthetical context, but only when it adds interesting, non-duplicative
 signal beyond the version role itself, for example native instrumentation notes, backport
@@ -121,6 +150,29 @@ The compact form does **not** apply when matchers are chained (e.g., positive +
 In that case, follow the multi-class rule: place each version comment directly above its
 class name string.
 
+Within a chain, each `hasClassesNamed("...")` call with a **single inline class string** —
+whether used directly, as `not(hasClassesNamed("..."))`, or inside `.and(...)` — should
+keep the class on one line and place its version comment on the line immediately above
+that call:
+
+```java
+// added in 4.0.0.Final
+return hasClassesNamed("io.netty.handler.codec.http.HttpMessage")
+    // added in 4.1.0.Final
+    .and(not(hasClassesNamed("io.netty.handler.codec.http.CombinedHttpHeaders")));
+```
+
+```java
+// removed in 4.0
+return not(hasClassesNamed("io.vertx.core.Starter"))
+    // added in 5.0
+    .and(not(hasClassesNamed("io.vertx.core.http.impl.HttpClientConnectionInternal")));
+```
+
+Only break a class onto its own line (with the comment indented above it) when that call
+has multiple class strings, or when the chained landmark requires a multi-line two-line
+form (such as the artifact-presence-gate two-liner).
+
 **How to identify ceiling classes**: look for a **newer sibling module** for the same
 library, such as `mongo-4.0` next to `mongo-3.7`. If the newer module's
 `classLoaderMatcher()` checks a different variant of the same class, such as
@@ -184,7 +236,8 @@ OpenTelemetry instrumentation and the agent should opt out.
 public ElementMatcher.Junction<ClassLoader> classLoaderMatcher() {
   // added in 7.0.0
   return hasClassesNamed("org.elasticsearch.client.RestClient$InternalRequest")
-      // added in 8.10 (native OTel support)
+      // artifact presence gate (native OTel support)
+      // added in co.elastic.clients:elasticsearch-java 8.10
       .and(not(hasClassesNamed(
           "co.elastic.clients.transport.instrumentation.Instrumentation")));
 }
@@ -195,13 +248,117 @@ public ElementMatcher.Junction<ClassLoader> classLoaderMatcher() {
 ```java
 @Override
 public ElementMatcher.Junction<ClassLoader> classLoaderMatcher() {
-  // added in azure-core 1.53
+  // added in 1.53
   return hasClassesNamed("com.azure.core.util.LibraryTelemetryOptions")
-      // added in azure-core-tracing-opentelemetry 1.0.0-beta.47
+      // artifact presence gate (native OTel support)
+      // added in com.azure:azure-core-tracing-opentelemetry 1.0.0-beta.47
       .and(not(hasClassesNamed("com.azure.core.tracing.opentelemetry.OpenTelemetryTracer")));
 }
 ```
 
+#### Main target artifact
+
+Bare version numbers like `// added in 2.2.0` resolve to **the `InstrumentationModule`'s main
+target artifact**, which is normally the artifact pinned by the module's muzzle
+`pass { group + module }` block in `build.gradle.kts`.
+
+When a single gradle module hosts **multiple `InstrumentationModule` classes targeting
+different artifacts** (rare — for example `aws-sdk-2.2/javaagent` has separate
+`InstrumentationModule`s for `:aws-core`, `:sqs`, `:sns`, `:lambda`, and `:bedrock-runtime`),
+open each `classLoaderMatcher()` with a one-line comment naming the target artifact. Bare
+version numbers in the landmark comments then resolve unambiguously to that artifact.
+
+```java
+@Override
+public ElementMatcher.Junction<ClassLoader> classLoaderMatcher() {
+  // this instrumentation module targets software.amazon.awssdk:lambda
+  return hasClassesNamed(
+      // added in 2.2.0
+      "software.amazon.awssdk.services.lambda.model.InvokeRequest",
+      // added in 2.17.0 (via software.amazon.awssdk:json-utils 2.17.0)
+      "software.amazon.awssdk.protocols.jsoncore.JsonNode");
+}
+```
+
+`(via groupId:artifactId A.B)` still means the landmark lives in a required transitive of
+the target artifact. `// added in groupId:artifactId X.Y` (no `via`) still means the landmark
+lives in an independent, opt-in artifact whose presence itself is the gate.
+
+Single-`InstrumentationModule` gradle modules do not need this header.
+
+#### Artifact presence gate annotation
+
+When a landmark class lives in an **opt-in artifact that is not the module's target
+artifact**, use a two-line role comment: `// artifact presence gate` followed by
+`// added in groupId:artifactId X.Y`. Parenthetical context goes on whichever line it
+qualifies — attach it to `artifact presence gate` when it describes **why** the gate
+exists (e.g. `native OTel support`), and to `added in …` when it qualifies the **coordinate
+or version** (e.g. `renamed from extension.incubator`):
+
+```java
+// artifact presence gate
+// added in groupId:artifactId X.Y
+```
+
+```java
+// artifact presence gate (why the gate exists)
+// added in groupId:artifactId X.Y
+```
+
+```java
+// artifact presence gate
+// added in groupId:artifactId X.Y (coordinate/version qualifier)
+```
+
+The `artifact presence gate` label signals "this check is not pinning a version
+boundary of the target artifact — it is detecting that an independent, opt-in dependency
+is on the classpath". The version X.Y is the first version of that opt-in artifact where
+the class existed, for completeness. "Artifact presence" distinguishes this from the
+ordinary class-presence role of `hasClassesNamed` itself.
+
+Typical cases:
+
+- `.and(not(hasClassesNamed(...)))` to back off when a separately-shipped native OTel
+  bridge is present.
+- `.and(hasClassesNamed(...))` to require an add-on that is not a required transitive of
+  the target artifact.
+
+Examples:
+
+```java
+// artifact presence gate (native OTel support)
+// added in com.azure:azure-core-tracing-opentelemetry 1.0.0-beta.47
+.and(not(hasClassesNamed("com.azure.core.tracing.opentelemetry.OpenTelemetryTracer")));
+```
+
+```java
+// artifact presence gate (native OTel support)
+// added in co.elastic.clients:elasticsearch-java 8.10
+.and(not(hasClassesNamed("co.elastic.clients.transport.instrumentation.Instrumentation")));
+```
+
+Do **not** use the `artifact presence gate` label when the landmark class lives in the
+target artifact or a required transitive — those are ordinary version boundaries and use
+the usual role comments (`// added in X.Y`, `// added in X.Y (via groupId:artifactId A.B)`).
+Conversely, do not omit the `groupId:artifactId` qualifier on the `added in` line when
+using the `artifact presence gate` label: the label and the qualifier always go together.
+
+#### `io.opentelemetry*` groupId shorthand
+
+For artifacts whose `groupId` starts with `io.opentelemetry` (for example
+`io.opentelemetry:opentelemetry-api`, `io.opentelemetry:opentelemetry-api-incubator`,
+`io.opentelemetry.instrumentation:opentelemetry-instrumentation-annotations`), omit the
+`groupId` and use just the artifact name in role comments:
+
+```java
+// added in opentelemetry-api 1.38.0
+// artifact presence gate
+// added in opentelemetry-instrumentation-annotations 1.16.0
+```
+
+The shorthand does **not** apply to non-OpenTelemetry artifacts — those always use the
+full coordinate.
+
 #### Rules for `classLoaderMatcher()`
 
 - **Do NOT add `classLoaderMatcher()` for optimization.** The "skip when library is absent"
@@ -218,11 +375,24 @@ public ElementMatcher.Junction<ClassLoader> classLoaderMatcher() {
   comment above the statement or expression. When matchers are chained, place each version
   comment directly above its class name string.
   - Positive floor class → `// added in X.Y`, optionally with brief, non-duplicative context
-    such as `renamed from javax` or `backported to 2.12.3`.
+    such as `renamed from javax` or `backported to 2.12.3`. For a landmark class from a
+    different artifact, use `// added in groupId:artifactId X.Y` when the boundary is for that
+    artifact, or `// added in X.Y (via groupId:artifactId A.B)` when the boundary or presence
+    condition is for the main library module. For `javax.servlet:javax.servlet-api` and
+    `jakarta.servlet:jakarta.servlet-api`, use `Servlet` instead of the full Maven coordinate.
   - Positive ceiling class → `// removed in Y.Z`, optionally with brief, non-duplicative
-    context such as `replaced by jakarta variant` or `moved to internal.async`.
+    context such as `replaced by jakarta variant` or `moved to internal.async`. For a landmark
+    class from a different artifact, use `// removed in groupId:artifactId Y.Z` when the
+    boundary is for that artifact, or `// removed in Y.Z (via groupId:artifactId A.B)` when the
+    boundary is for the main library module. For `javax.servlet:javax.servlet-api` and
+    `jakarta.servlet:jakarta.servlet-api`, use `Servlet` instead of the full Maven coordinate.
   - Negated exclusion class → `// added in Y.Z`, optionally with brief, non-duplicative
-    context such as `native OTel support` or `shaded into core module`.
+    context such as `native OTel support` or `shaded into core module`. For a landmark class
+    from a different artifact, use `// added in groupId:artifactId Y.Z` when the excluded range
+    is driven by that artifact, or `// added in Y.Z (via groupId:artifactId A.B)` when the
+    excluded range is described in terms of the main library module. For
+    `javax.servlet:javax.servlet-api` and `jakarta.servlet:jakarta.servlet-api`, use `Servlet`
+    instead of the full Maven coordinate.
   - Single positive class serving as both floor and ceiling → include both boundaries, for
     example `// added in X.Y, removed in Y.Z`.
   Do not use `// added in` for a **positive** ceiling class, because the upper bound depends on