Merge branch 'main' into capture-request-headers

Author: trask

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

@@ -126,7 +126,7 @@ Auto-fix boundaries:
     same parent and apply the step-by-step procedure in `gradle-conventions.md`.
     After adding, verify by running the module's tests.
   - missing version comments on `hasClassesNamed()` landmark classes in existing
-    `classLoaderMatcher()` overrides (multi-class checks or `.and(not(...))` chains only) —
+    `classLoaderMatcher()` overrides, including single-class lower-bound checks —
     determine each class's **role** (floor vs ceiling) and add the matching comment.
     First check: does a **newer** sibling instrumentation module exist for this library
     (e.g., `mongo-4.0` next to `mongo-3.7`)? If so, look at what the newer module checks
@@ -142,6 +142,8 @@ Auto-fix boundaries:
     A ceiling class might have been *introduced* much earlier than the module's target version.
     Do not use `// added in` for a ceiling class — that is misleading. The relevant fact is
     when it was **removed**.
+    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 —
@@ -151,6 +153,9 @@ Auto-fix boundaries:
     names a specific, non-empty method (e.g., `isMethod().and(named("execute"))` →
     `named("execute")`). Do not remove `isMethod()` when the name could be empty —
     `named("")` matches constructors and static initializers.
+  - redundant `this.` qualifier on advice class references inside `transform()` — prefer
+    `getClass().getName() + "$InnerClassName"`, not `this.getClass().getName() +
+    "$InnerClassName"`
   - singleton-to-instance-creation conversion for stateless telemetry interface
     implementations (`TextMapGetter`, `TextMapSetter`, `*AttributesGetter`,
     `AttributesExtractor`, `SpanNameExtractor`, `HttpServerResponseMutator`) — replace

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

@@ -94,7 +94,11 @@ For each file in scope:
 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.
-6. Prevent duplicates:
+6. Flag a missing `// added in X.Y` comment on a single-class lower-bound
+   `hasClassesNamed(...)` check in `classLoaderMatcher()` only after validating that the
+   stated version is factually correct from repository or upstream evidence; the comment
+   documents why the matcher exists and which version boundary it enforces.
+7. Prevent duplicates:
    - If equivalent `REVIEW:` already exists above the same line, do not add another.
 
 Comment formatting rules:

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

@@ -15,6 +15,7 @@ When a "Knowledge File" is listed, load it from `knowledge/` before reviewing th
 | --- | --- | --- | --- |
 | General | Logic, correctness, reliability, safety, copy/paste mistakes, incorrect comments | Always | — |
 | Style | Style guide | Always | — |
+| Style | Uppercase field names should reflect semantic constants, not simply `static final` | Always | — |
 | Naming | Getter naming (`get` / `is`) | Always | — |
 | Naming | Module/package naming | New or renamed modules/packages | `module-naming.md` |
 | Javaagent | Advice patterns | `@Advice` classes | `javaagent-advice-patterns.md` |

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

@@ -191,5 +191,5 @@ the instrumentation automatically rather than letting it fail at runtime.
 - **`@Advice.OnMethodEnter` or `@Advice.OnMethodExit` missing `suppress = Throwable.class`** when the method has a non-trivial body (library calls, collection iteration, reflection). Exceptions: `instrumentation/internal/` infrastructure code, test sources, and methods whose bodies provably cannot throw (e.g., `return true;`, returning a literal or a single constant). Do not add or flag `suppress` on provably throw-free bodies.
 - **Exception thrown in advice code or a helper called from advice** — javaagent code must never throw; use `suppress = Throwable.class` as the safety net.
 - **`@Advice.OnMethodExit` method named `onEnter`** (or vice versa) — the method name should match the annotation. A mismatch is a copy-paste bug that compiles but confuses readers and may mask intent errors.
-- **`.class.getName()` used in `transform()` to reference advice** — see `javaagent-module-patterns.md` for the correct `getClass().getName()` pattern. Flag both `InnerAdvice.class.getName()` and `OuterInstrumentation.class.getName() + "$InnerAdvice"` — any `.class` literal in a `transform()` method triggers unwanted class loading.
+- **Advice referenced in `transform()` using anything other than `getClass().getName() + "$InnerAdvice"`** — see `javaagent-module-patterns.md` for the canonical pattern. Flag `this.getClass().getName() + "$InnerAdvice"` as a redundant qualifier, and flag both `InnerAdvice.class.getName()` and `OuterInstrumentation.class.getName() + "$InnerAdvice"` because any `.class` literal in a `transform()` method triggers unwanted class loading.
 - **`onThrowable = Throwable.class` on return-only exit advice** — if the exit method only processes `@Advice.Return` and has no `@Advice.Enter` state to clean up, `onThrowable` should be omitted. The return value is `null`/zero on the exceptional path, and dereferencing it causes a suppressed exception for no benefit. Keep `suppress = Throwable.class` but remove `onThrowable`.

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

@@ -187,10 +187,13 @@ public ElementMatcher.Junction<ClassLoader> classLoaderMatcher() {
   which is irrelevant and misleading; the purpose is the upper bound.
   To identify ceiling classes, check if a newer sibling module's `classLoaderMatcher()`
   checks a different variant or replacement class.
-- **Do NOT add version comments on trivial single-class checks.** A single-class
-  `hasClassesNamed(...)` check whose landmark corresponds to the module's base
-  version does not need a comment — the version is obvious from the module name. Do not
-  suggest adding one.
+- **Single-class lower-bound comments are required.** When a single-class
+  `hasClassesNamed(...)` check exists solely to establish the module's lower bound, add an
+  inline `// added in X.Y` comment. The comment explains why the matcher exists and which
+  version boundary it enforces. First validate that `X.Y` is factually correct from
+  repository or upstream evidence; do not infer it from the module name alone. Flag a
+  missing comment in this case, and do not flag an existing one for removal unless the
+  comment is demonstrably wrong.
 - Prefer **one landmark class** per version boundary — choose the most stable/specific class.
 - Pair with **muzzle config** (`assertInverse.set(true)`) for full coverage.
 - Use `hasClassesNamed(...)` (from `AgentElementMatchers`) — not raw ByteBuddy matchers.
@@ -254,9 +257,7 @@ sufficient for optimization.
 
 ### Rules
 
-- Do not flag or change the visibility or `final` modifier on `TypeInstrumentation`,
-  `InstrumentationModule`, or advice classes. Both `public class` and package-private `class`
-  (with or without `final`) are acceptable — this is not a style issue in javaagent code.
+- Do not flag or change the visibility or `final` modifier on advice classes.
 - `typeMatcher()` should match only the types the instrumentation genuinely needs. Prefer
   `named("fully.qualified.ClassName")` or `namedOneOf(...)` for single classes.
   `extendsClass(...)` and `implementsInterface(...)` are appropriate when the instrumentation
@@ -267,12 +268,14 @@ sufficient for optimization.
   Keep `isMethod()` when the name could be empty, since `named("")` matches constructors and
   class initializers.
 - Reference the advice class using `getClass().getName() + "$InnerClassName"` — not
-  `InnerClassName.class.getName()`, `OuterClass.class.getName()`, or a string literal.
+  `this.getClass().getName() + "$InnerClassName"`, `InnerClassName.class.getName()`,
+  `OuterClass.class.getName()`, or a string literal.
   Any `.class.getName()` reference — whether to the inner advice class or the outer
   instrumentation class — causes class loading in the agent's class loader, where library
   types used by the advice are unavailable (causing `NoClassDefFoundError`).
   `getClass().getName()` avoids this because it is a virtual call on the already-loaded
-  `this` instance, not a class literal.
+  instance, not a class literal. Omit the redundant `this.` qualifier and use the shorter
+  repository convention.
 
 ## Singletons Pattern
 

.github/labeler.yml

@@ -7,4 +7,5 @@ test native:
           - instrumentation/spring/**
           - smoke-tests-otel-starter/**
           - dependencyManagement/build.gradle.kts
+          - settings.gradle.kts
       - all-globs-to-all-files: '!instrumentation/spring/**/javaagent/**'

.github/renovate.json5

@@ -18,7 +18,7 @@
         'patch',
       ],
       schedule: [
-        'before 8am on Tuesday',
+        '* 0-7 * * 2', // weekly, before 8am on Tuesday
       ],
     },
     {
@@ -29,8 +29,8 @@
         'dockerfile',
         'custom.regex',
       ],
-      extends: [
-        'schedule:weekly',
+      schedule: [
+        '* 0-7 * * 2', // weekly, before 8am on Tuesday
       ],
       groupName: 'weekly update',
     },

.github/workflows/codeql.yml

@@ -32,7 +32,7 @@ jobs:
         include:
           - language: actions
           - language: java
-    runs-on: oracle-vm-8cpu-32gb-x86-64
+    runs-on: ${{ github.repository == 'open-telemetry/opentelemetry-java-instrumentation' && 'oracle-vm-8cpu-32gb-x86-64' || 'ubuntu-latest' }}
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 

.github/workflows/label.yml

@@ -7,10 +7,14 @@ permissions:
 jobs:
   label:
     runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      pull-requests: write
     steps:
+    - uses: actions/create-github-app-token@f8d387b68d61c58ab83c6c016672934102569859 # v3.0.0
+      id: otelbot-token
+      with:
+        app-id: ${{ vars.OTELBOT_JAVA_INSTRUMENTATION_APP_ID }}
+        private-key: ${{ secrets.OTELBOT_JAVA_INSTRUMENTATION_PRIVATE_KEY }}
+
     - uses: actions/labeler@634933edcd8ababfe52f92936142cc22ac488b1b # v6.0.1
       with:
-        repo-token: "${{ secrets.GITHUB_TOKEN }}"
+        # Not using GITHUB_TOKEN since labels from that token do not trigger workflows.
+        repo-token: "${{ steps.otelbot-token.outputs.token }}"

conventions/src/main/kotlin/otel.java-conventions.gradle.kts

@@ -418,7 +418,7 @@ afterEvaluate {
 checkstyle {
   configFile = rootProject.file("buildscripts/checkstyle.xml")
   // this version should match the version of google_checks.xml used as basis for above configuration
-  toolVersion = "13.3.0"
+  toolVersion = "13.4.0"
   maxWarnings = 0
 }