Merge remote-tracking branch 'upstream/main' into isin

# Conflicts:
#	instrumentation/elasticsearch/elasticsearch-transport-common/testing/src/main/java/io/opentelemetry/javaagent/instrumentation/elasticsearch/transport/AbstractElasticsearchTransportClientTest.java
#	instrumentation/netty/netty-4.0/javaagent/src/test/java/io/opentelemetry/javaagent/instrumentation/netty/v4_0/client/Netty40ConnectionSpanTest.java
#	instrumentation/netty/netty-4.1/javaagent/src/test/java/io/opentelemetry/javaagent/instrumentation/netty/v4_1/Netty41ClientSslTest.java
#	instrumentation/netty/netty-4.1/javaagent/src/test/java/io/opentelemetry/javaagent/instrumentation/netty/v4_1/Netty41ConnectionSpanTest.java

Author: trask

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

@@ -17,7 +17,6 @@ When a "Knowledge File" is listed, load it from `knowledge/` before reviewing th
 | Style | Style guide | Always | — |
 | Style | Uppercase field names should reflect semantic constants or immutable value constants such as `Duration` timeouts/intervals, not simply `static final` | Always | — |
 | Naming | Getter naming (`get` / `is`) | Always | — |
-| Naming | Boolean/collection option naming (`set*Enabled`, `setCapture*`, `setEmitExperimental*`) | `Experimental` or `TelemetryBuilder` setter changes | `library-patterns.md` |
 | 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`, `Singletons` | `javaagent-module-patterns.md` |

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

@@ -51,18 +51,37 @@ Verify `build.gradle.kts` applies the correct plugin for the module type:
 | `library/` | `otel.library-instrumentation` |
 | `testing/` | `otel.java-conventions` |
 
-## Boolean Project Properties
+## Shared Gradle Project Properties
 
-For simple boolean Gradle project properties in `build.gradle.kts`, prefer the repository's most
-common pattern:
+In `build.gradle.kts`, prefer the shared `otelProps` extension for repository-wide Gradle project
+properties that are already modeled there, including:
+
+- `testLatestDeps`
+- `denyUnsafe`
+- `collectMetadata`
+- `testJavaVersion`
+- `testJavaVM`
+- `maxTestRetries`
+- `enableStrictContext`
+
+Examples:
 
 ```kotlin
-val myFlag = findProperty("myFlag") == "true"
-if (myFlag) {
+if (otelProps.testLatestDeps) {
   // ...
 }
+
+tasks.withType<Test>().configureEach {
+  systemProperty("collectMetadata", otelProps.collectMetadata)
+}
 ```
 
+For module-local one-off properties that are not part of `otelProps`, using `findProperty(...)`
+directly is still fine.
+
+`settings.gradle.kts` is the exception: it cannot use project extensions like `otelProps`, so
+direct `gradle.startParameter.projectProperties[...]` access is expected there.
+
 ## `testInstrumentation` Dependencies
 
 The `testInstrumentation` configuration declares which other javaagent instrumentation modules
@@ -186,7 +205,7 @@ should apply to all tasks. If so, move them to `withType<Test>().configureEach`.
 ```kotlin
 tasks {
   withType<Test>().configureEach {
-    systemProperty("collectMetadata", findProperty("collectMetadata"))
+    systemProperty("collectMetadata", otelProps.collectMetadata)
     // ... other properties common to all test tasks
   }
 
@@ -205,7 +224,7 @@ review**. Only verify correctness when they are already present.
 
 | Property | Type | Value |
 | --- | --- | --- |
-| `collectMetadata` | System property | Pass-through of the `collectMetadata` Gradle project property; defaults to `"false"` |
+| `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:

.github/agents/knowledge/library-patterns.md

@@ -44,32 +44,3 @@ public final class MyLibraryTelemetry {
 - Builder setter methods return `this` and are annotated `@CanIgnoreReturnValue`.
 - The builder's constructor is package-private — only `Telemetry.builder()` creates it.
 - `build()` returns the `{Library}Telemetry` instance.
-
-## Boolean and Collection Option Naming
-
-Builder methods on `TelemetryBuilder` and `Experimental` classes must follow these
-naming patterns. Flag any new method that deviates.
-
-### Canonical patterns
-
-| Semantic | Pattern | Examples |
-| --- | --- | --- |
-| Feature on/off toggle | `set*Enabled(boolean)` | `setSqlCommenterEnabled`, `setQuerySanitizationEnabled`, `setDataSourceInstrumenterEnabled` |
-| Emit experimental signals | `setEmitExperimental*(boolean)` | `setEmitExperimentalTelemetry`, `setEmitExperimentalMetrics` |
-| Capture data (boolean) | `setCapture*(boolean)` | `setCaptureExperimentalSpanAttributes`, `setCaptureEnduserId`, `setCaptureQuery` |
-| Capture data (collection) | `setCapture*(Collection)` | `setCaptureRequestHeaders`, `setCaptureResponseHeaders`, `setCaptureRequestParameters` |
-
-### Rules
-
-- **`set*Enabled`** is for features that are turned on or off (sanitization, SQL commenter,
-  instrumenter toggles). The thing being named is a feature or processing step.
-- **`setCapture*`** is for options that control whether a piece of data is collected or
-  emitted (attributes, headers, query text, message content). Use the verb form for both
-  boolean and collection variants.
-- **`setEmitExperimental*`** is reserved for the `Experimental` class toggle that enables
-  all experimental telemetry for an instrumentation. Do not use on `TelemetryBuilder`.
-
-### Known exceptions
-
-- `setPreferJfrMetrics(boolean)` — selects JFR over JMX for overlapping metrics; it is a
-  strategy selector, not a feature toggle or data capture flag.

.github/agents/knowledge/testing-general-patterns.md

@@ -3,13 +3,29 @@
 ## Quick Reference
 
 - Use when: test files (`**/src/test/**`) are in scope
-- Review focus: assertion style, test class visibility, attribute assertion patterns
+- Review focus: assertion style, test class visibility, resource cleanup patterns, attribute assertion patterns
 
 ## Assertion Framework
 
 - JUnit 5, AssertJ assertions (not JUnit `assertEquals`/`assertTrue`).
 - Test classes and methods should be package-private (no `public`).
 
+## Test Resource Cleanup
+
+- In JUnit tests, when an `AutoCloseable` is intended to remain live for most or all of the test
+  and only needs cleanup at test end, prefer `AutoCleanupExtension` with `deferCleanup(...)`
+  over wrapping most of the test body in try-with-resources.
+- Reuse an existing `cleanup` extension when one is already in scope.
+  Otherwise, add a `@RegisterExtension` field when the deferred-cleanup pattern improves
+  clarity or avoids wrapping most of the test body.
+- Keep try-with-resources for semantically scoped resources whose lifetime must end before the
+  rest of the test continues, such as `Scope` / `Context.makeCurrent()`, Mockito
+  `MockedStatic`, and short-lived readers, writers, streams, response bodies, or parsers.
+- Do not use `AutoCleanupExtension` in non-JUnit helper methods, `@BeforeAll`, or other shared
+  setup code where cleanup is not tied to a single test method.
+- If the test intentionally closes the resource mid-test or asserts behavior around explicit
+  close, keep the direct close or try-with-resources in the test body.
+
 ## Span Attribute Assertions
 
 - Use `span.hasAttributesSatisfyingExactly(...)` with `equalTo(...)`/`satisfies(...)` for
@@ -30,19 +46,24 @@
   `equalTo(AttributeKey<Long>, int)` overload, so `equalTo(longKey("iteration"), iteration)` is
   preferred over `equalTo(longKey("iteration"), (long) iteration)`.
 
-## `satisfies()` Lambda Parameters
+## Attribute Assertion `satisfies()` Lambda Parameters
 
-**`satisfies()` lambda parameters are `AbstractAssert` instances, not raw values.**
-Inside a `satisfies(AttributeKey, Consumer)` lambda the parameter (e.g., `taskId`) is an
-`AbstractStringAssert<?>` (for string keys), `AbstractLongAssert<?>` (for long keys), etc.
+**Attribute-assertion `satisfies()` lambda parameters are `AbstractAssert` instances, not raw
+values.** Inside a `satisfies(AttributeKey, Consumer)` lambda the parameter (e.g., `taskId`) is
+an `AbstractStringAssert<?>` (for string keys), `AbstractLongAssert<?>` (for long keys), etc.
 Fluent assertion calls like `taskId.contains(jobName)` or `taskId.startsWith(prefix)` are
 already proper AssertJ assertions — they throw on failure. Do **not** wrap them in
 `assertThat(value.contains(x)).isTrue()`, which degrades the failure message.
 
-- For generic outer `satisfies(AttributeKey, lambda)` parameters, use `val`.
+- For `satisfies(AttributeKey, lambda)` outer parameters, use `val`.
   Do not use short generic alternatives like `k` or `v` for the outer parameter.
-- If a `satisfies(...)` lambda contains a nested inner lambda and a second parameter name is
-  required, keep the outer parameter as `val` and use `v` for the nested parameter.
+- If an attribute-assertion `satisfies(...)` lambda contains a nested inner lambda and a second
+  parameter name is required, keep the outer parameter as `val` and use `v` for the nested
+  parameter.
+- This naming guidance does **not** apply to non-attribute `satisfies(...)` usages such as
+  `span.satisfies(...)`, `point.satisfies(...)`, or `assertThat(result).satisfies(...)`.
+  In those cases, prefer a descriptive subject name like `spanData`, `pointData`, `resource`,
+  or `result` instead of generic names like `val`.
 
 ## AssertJ Idiomatic Simplifications
 

CHANGELOG.md

@@ -8,6 +8,10 @@
   and deprecated config key `otel.instrumentation.graphql.add-operation-name-to-span-name.enabled`
   in favor of `setQuerySanitizationEnabled()`, `setOperationNameInSpanNameEnabled()`, and
   `otel.instrumentation.graphql.operation-name-in-span-name.enabled`
+- Deprecated the declarative config name `statement_sanitizer` in favor of `query_sanitization`
+- Deprecated the declarative config group `common.database` in favor of `common.db`
+- Deprecated the GraphQL declarative config name `query_sanitizer` in favor of
+  `query_sanitization`
 
 ## Version 2.26.1 (2026-03-23)
 

conventions/src/main/kotlin/io.opentelemetry.instrumentation.base.gradle.kts

@@ -1,9 +1,14 @@
 /** Common setup for manual instrumentation of libraries and javaagent instrumentation. */
 
+import io.opentelemetry.instrumentation.gradle.OtelPropsExtension
+
 plugins {
   `java-library`
+  id("otel.props-conventions")
 }
 
+val otelProps = the<OtelPropsExtension>()
+
 /**
  * We define three dependency configurations to use when adding dependencies to libraries being
  * instrumented.
@@ -26,9 +31,6 @@ plugins {
  *   precedence. Use this to restrict the latest version dependency from the default `+`, for
  *   example to restrict to just a major version by specifying `2.+`.
  */
-
-val testLatestDeps = gradle.startParameter.projectProperties["testLatestDeps"] == "true"
-
 @CacheableRule
 abstract class TestLatestDepsRule : ComponentMetadataRule {
   override fun execute(context: ComponentMetadataContext) {
@@ -77,15 +79,15 @@ configurations {
     // mutating the version for latest dep tests.
     configuration.dependencies.whenObjectAdded {
       val dep = copy()
-      if (testLatestDeps) {
+      if (otelProps.testLatestDeps) {
         (dep as ExternalDependency).version {
           require("latest.release")
         }
       }
       testImplementation.dependencies.add(dep)
     }
   }
-  if (testLatestDeps) {
+  if (otelProps.testLatestDeps) {
     dependencies {
       components {
         all<TestLatestDepsRule>()
@@ -108,7 +110,7 @@ configurations {
   }
 }
 
-if (testLatestDeps) {
+if (otelProps.testLatestDeps) {
   afterEvaluate {
     tasks {
       withType<JavaCompile>().configureEach {

conventions/src/main/kotlin/io.opentelemetry.instrumentation.javaagent-testing.gradle.kts

@@ -1,3 +1,5 @@
+import io.opentelemetry.instrumentation.gradle.OtelPropsExtension
+
 plugins {
   `java-library`
 
@@ -14,7 +16,7 @@ val testIndyProperty = providers.gradleProperty("testIndy")
   .map { it == "true" }
   .orElse(false)
 
-val denyUnsafe = gradle.startParameter.projectProperties["denyUnsafe"] == "true"
+val otelProps = the<OtelPropsExtension>()
 
 dependencies {
   /*
@@ -148,7 +150,7 @@ afterEvaluate {
         shadowJar.archiveFile.get().asFile,
         failOnContextLeakOverride,
         testIndyEnabled,
-        denyUnsafe
+        otelProps.denyUnsafe
       )
     )
 

conventions/src/main/kotlin/io/opentelemetry/instrumentation/gradle/OtelPropsExtension.kt

@@ -0,0 +1,32 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.gradle
+
+import org.gradle.api.JavaVersion
+import org.gradle.api.Project
+
+open class OtelPropsExtension(private val project: Project) {
+  val testLatestDeps: Boolean
+    get() = project.findProperty("testLatestDeps") == "true"
+
+  val denyUnsafe: Boolean
+    get() = project.findProperty("denyUnsafe") == "true"
+
+  val collectMetadata: Boolean
+    get() = project.findProperty("collectMetadata") == "true"
+
+  val testJavaVersion: JavaVersion?
+    get() = project.findProperty("testJavaVersion")?.toString()?.let(JavaVersion::toVersion)
+
+  val testJavaVM: String?
+    get() = project.findProperty("testJavaVM")?.toString()
+
+  val maxTestRetries: Int?
+    get() = project.findProperty("maxTestRetries")?.toString()?.toInt()
+
+  val enableStrictContext: Boolean
+    get() = project.findProperty("enableStrictContext")?.toString()?.toBoolean() ?: true
+}

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

@@ -1,6 +1,8 @@
+import io.opentelemetry.instrumentation.gradle.OtelPropsExtension
 import net.ltgt.gradle.errorprone.errorprone
 
 plugins {
+  id("otel.props-conventions")
   id("net.ltgt.errorprone")
 }
 
@@ -10,7 +12,7 @@ dependencies {
 }
 
 val disableErrorProne = properties["disableErrorProne"]?.toString()?.toBoolean() ?: false
-val testLatestDeps = gradle.startParameter.projectProperties["testLatestDeps"] == "true"
+val otelProps = the<OtelPropsExtension>()
 
 tasks {
   withType<JavaCompile>().configureEach {
@@ -133,7 +135,7 @@ tasks {
         disable("AddNullMarkedToClass")
         disable("AddNullMarkedToPackageInfo")
 
-        if (testLatestDeps) {
+        if (otelProps.testLatestDeps) {
           // Some latest dep tests are compiled for java 17 although the base version uses an older
           // version. Disable rules that suggest using new language features.
           disable("StatementSwitchToExpressionSwitch")

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

@@ -1,4 +1,5 @@
 import io.opentelemetry.instrumentation.gradle.OtelJavaExtension
+import io.opentelemetry.instrumentation.gradle.OtelPropsExtension
 import org.gradle.api.tasks.testing.logging.TestExceptionFormat
 import java.time.Duration
 
@@ -8,12 +9,14 @@ plugins {
   checkstyle
   idea
 
+  id("otel.props-conventions")
   id("otel.errorprone-conventions")
   id("otel.spotless-conventions")
   id("org.sonatype.gradle.plugins.scan")
 }
 
 val otelJava = extensions.create<OtelJavaExtension>("otelJava")
+val otelProps = the<OtelPropsExtension>()
 
 afterEvaluate {
   val previousBaseArchiveName = base.archivesName.get()
@@ -320,9 +323,8 @@ tasks.withType<Test>().configureEach {
   useJUnitPlatform()
 
   // work around jvm crash on openJ9 8 after updating armeria to 1.33.1
-  val testJavaVersion = gradle.startParameter.projectProperties["testJavaVersion"]?.let(JavaVersion::toVersion)
-  val useJ9 = gradle.startParameter.projectProperties["testJavaVM"]?.run { this == "openj9" }
-    ?: false
+  val testJavaVersion = otelProps.testJavaVersion
+  val useJ9 = otelProps.testJavaVM == "openj9"
   if (useJ9 && testJavaVersion != null && testJavaVersion.isJava8) {
     jvmArgs("-Xjit:exclude={io/opentelemetry/testing/internal/io/netty/buffer/HeapByteBufUtil.*}," +
         "exclude={io/opentelemetry/testing/internal/io/netty/buffer/UnpooledHeapByteBuf.*}," +
@@ -332,10 +334,10 @@ tasks.withType<Test>().configureEach {
 
   // There's no real harm in setting this for all tests even if any happen to not be using context
   // propagation.
-  jvmArgs("-Dio.opentelemetry.context.enableStrictContext=${rootProject.findProperty("enableStrictContext") ?: true}")
+  jvmArgs("-Dio.opentelemetry.context.enableStrictContext=${otelProps.enableStrictContext}")
   // TODO: Have agent map unshaded to shaded.
   if (project.findProperty("disableShadowRelocate") != "true") {
-    jvmArgs("-Dio.opentelemetry.javaagent.shaded.io.opentelemetry.context.enableStrictContext=${rootProject.findProperty("enableStrictContext") ?: true}")
+    jvmArgs("-Dio.opentelemetry.javaagent.shaded.io.opentelemetry.context.enableStrictContext=${otelProps.enableStrictContext}")
   } else {
     jvmArgs("-Dotel.instrumentation.opentelemetry-api.enabled=false")
     jvmArgs("-Dotel.instrumentation.opentelemetry-instrumentation-api.enabled=false")
@@ -359,7 +361,7 @@ tasks.withType<Test>().configureEach {
   timeout.set(Duration.ofMinutes(15))
 
   val defaultMaxRetries = if (System.getenv().containsKey("CI")) 5 else 0
-  val maxTestRetries = gradle.startParameter.projectProperties["maxTestRetries"]?.toInt() ?: defaultMaxRetries
+  val maxTestRetries = otelProps.maxTestRetries ?: defaultMaxRetries
 
   develocity.testRetry {
     // You can see tests that were retried by this mechanism in the collected test reports and build scans.
@@ -388,9 +390,8 @@ class KeystoreArgumentsProvider(
 }
 
 afterEvaluate {
-  val testJavaVersion = gradle.startParameter.projectProperties["testJavaVersion"]?.let(JavaVersion::toVersion)
-  val useJ9 = gradle.startParameter.projectProperties["testJavaVM"]?.run { this == "openj9" }
-    ?: false
+  val testJavaVersion = otelProps.testJavaVersion
+  val useJ9 = otelProps.testJavaVM == "openj9"
   tasks.withType<Test>().configureEach {
     if (testJavaVersion != null) {
       javaLauncher.set(