Merge branch 'main' into indy-opentelemetry-api

Author: SylvainJuge

.github/workflows/overhead-benchmark-daily.yml

@@ -42,17 +42,15 @@ jobs:
       - name: Copy results back to gh-pages branch
         run: rsync -avv benchmark-overhead/results/ gh-pages/benchmark-overhead/results/ && rm -rf benchmark-overhead/results
 
+      - name: Use CLA approved bot
+        run: .github/scripts/use-cla-approved-bot.sh
+
       - name: Commit updated results
-        uses: EndBug/add-and-commit@a94899bca583c204427a224a7af87c02f9b325d5 # v9.1.4
-        with:
-          add: "benchmark-overhead/results"
-          cwd: "./gh-pages"
-          branch: "gh-pages"
-          message: "update test result data"
-          author_name: otelbot
-          author_email: [email protected]
-          committer_name: otelbot
-          committer_email: [email protected]
+        working-directory: ./gh-pages
+        run: |
+          git add benchmark-overhead/results
+          git commit -m "update test result data"
+          git push
 
   workflow-notification:
     permissions:

CONTRIBUTING.md

@@ -15,10 +15,28 @@ See [Running the tests](./docs/contributing/running-tests.md) for more details.
 
 ### Snapshot builds
 
-For developers testing code changes before a release is complete, there are
-snapshot builds of the `main` branch. They are available from
-the Sonatype snapshot repository at `https://central.sonatype.com/repository/maven-snapshots/`
-([browse](https://central.sonatype.com/service/rest/repository/browse/maven-snapshots/io/opentelemetry/)).
+For developers testing code changes before a release is complete, snapshot builds of the `main`
+branch are available from the Sonatype snapshot repository at `https://central.sonatype.com/repository/maven-snapshots/`.
+
+To find the latest snapshot, check the maven metadata (replace `{LATEST_VERSION}` with the current
+stable release):
+
+```
+https://central.sonatype.com/repository/maven-snapshots/io/opentelemetry/javaagent/opentelemetry-javaagent/{LATEST_VERSION}-SNAPSHOT/maven-metadata.xml
+```
+
+Look for the `<timestamp>` and `<buildNumber>` in the XML response, then construct the download URL:
+
+```
+https://central.sonatype.com/repository/maven-snapshots/io/opentelemetry/javaagent/opentelemetry-javaagent/{VERSION}-SNAPSHOT/opentelemetry-javaagent-{VERSION}-{TIMESTAMP}-{BUILD_NUMBER}.jar
+```
+
+For example, if the metadata shows timestamp `20250925.160708` and build number `56` for version
+`2.21.0`, the snapshot JAR URL would be:
+
+```
+https://central.sonatype.com/repository/maven-snapshots/io/opentelemetry/javaagent/opentelemetry-javaagent/2.21.0-SNAPSHOT/opentelemetry-javaagent-2.21.0-20250925.160708-56.jar
+```
 
 ### Building from source
 

benchmark-overhead/build.gradle.kts

@@ -1,6 +1,6 @@
 plugins {
   id("java")
-  id("com.diffplug.spotless") version "7.2.1"
+  id("com.diffplug.spotless") version "8.0.0"
 }
 
 spotless {

conventions/build.gradle.kts

@@ -1,7 +1,7 @@
 plugins {
   `kotlin-dsl`
   // When updating, update below in dependencies too
-  id("com.diffplug.spotless") version "7.2.1"
+  id("com.diffplug.spotless") version "8.0.0"
 }
 
 spotless {
@@ -54,12 +54,12 @@ dependencies {
   implementation("org.apache.maven:maven-aether-provider:3.3.9")
 
   // When updating, update above in plugins too
-  implementation("com.diffplug.spotless:spotless-plugin-gradle:7.2.1")
+  implementation("com.diffplug.spotless:spotless-plugin-gradle:8.0.0")
   implementation("com.google.guava:guava:33.5.0-jre")
-  implementation("com.gradleup.shadow:shadow-gradle-plugin:9.1.0")
+  implementation("com.gradleup.shadow:shadow-gradle-plugin:9.2.1")
   implementation("org.apache.httpcomponents:httpclient:4.5.14")
   implementation("com.gradle.develocity:com.gradle.develocity.gradle.plugin:4.2")
-  implementation("org.owasp:dependency-check-gradle:12.1.5")
+  implementation("org.owasp:dependency-check-gradle:12.1.6")
   implementation("ru.vyarus:gradle-animalsniffer-plugin:2.0.1")
   implementation("org.spdx:spdx-gradle-plugin:0.9.0")
   // When updating, also update dependencyManagement/build.gradle.kts

custom-checks/src/test/java/io/opentelemetry/javaagent/customchecks/OtelInternalJavadocTest.java

@@ -14,7 +14,7 @@ class OtelInternalJavadocTest {
   void test() {
     doTest(
         "internal/InternalJavadocPositiveCases.java",
-        """
+"""
 package io.opentelemetry.javaagent.customchecks.internal;
 
 // BUG: Diagnostic contains: doesn't end with any of the applicable javadoc disclaimers
@@ -30,7 +30,7 @@ public static class Two {}
 """);
     doTest(
         "internal/InternalJavadocNegativeCases.java",
-        """
+"""
 package io.opentelemetry.javaagent.customchecks.internal;
 
 /**

dependencyManagement/build.gradle.kts

@@ -37,7 +37,7 @@ val DEPENDENCY_BOMS = listOf(
 
 val autoServiceVersion = "1.1.1"
 val autoValueVersion = "1.11.0"
-val errorProneVersion = "2.41.0"
+val errorProneVersion = "2.42.0"
 val byteBuddyVersion = "1.17.7"
 val asmVersion = "9.8"
 val jmhVersion = "1.37"

docs/contributing/documenting-instrumentation.md

@@ -96,6 +96,22 @@ configurations:
     description: Enables statement sanitization for database queries.
     type: boolean
     default: true
+override_telemetry: false
+additional_telemetry:
+  - when: "default"
+    metrics:
+      - name: "metric.name"
+        description: "Metric description"
+        type: "COUNTER"
+        unit: "1"
+        attributes:
+          - name: "attribute.name"
+            type: "STRING"
+    spans:
+      - span_kind: "CLIENT"
+        attributes:
+          - name: "span.attribute"
+            type: "STRING"
 ```
 
 ### Description (required)
@@ -205,6 +221,82 @@ If an instrumentation is disabled by default, set `disabled_by_default: true`. T
 the instrumentation will not be active unless explicitly enabled by the user. If this field is omitted,
 it defaults to `false`, meaning the instrumentation is enabled by default.
 
+### Manual Telemetry Documentation (optional)
+
+You can manually document telemetry metadata (metrics and spans) directly in the `metadata.yaml` file
+using the `additional_telemetry` field. This is useful for:
+
+- Documenting telemetry that may not be captured during automated test runs
+- Adding telemetry documentation when `.telemetry` files are not available
+- Providing additional context or details about emitted telemetry
+
+#### additional_telemetry
+
+The `additional_telemetry` field allows you to specify telemetry metadata organized by configuration
+conditions (`when` field):
+
+```yaml
+additional_telemetry:
+  - when: "default"  # Telemetry emitted by default
+    metrics:
+      - name: "http.server.request.duration"
+        description: "Duration of HTTP server requests"
+        type: "HISTOGRAM"
+        unit: "ms"
+        attributes:
+          - name: "http.method"
+            type: "STRING"
+          - name: "http.status_code"
+            type: "LONG"
+    spans:
+      - span_kind: "SERVER"
+        attributes:
+          - name: "http.method"
+            type: "STRING"
+          - name: "http.url"
+            type: "STRING"
+  - when: "otel.instrumentation.example.experimental-metrics.enabled"  # Telemetry enabled by configuration
+    metrics:
+      - name: "example.experimental.metric"
+        description: "Experimental metric enabled by configuration"
+        type: "COUNTER"
+        unit: "1"
+```
+
+Each telemetry entry includes:
+
+- `when`: The configuration condition under which this telemetry is emitted. Use `"default"` for telemetry
+  emitted by default, or specify the configuration option name for conditional telemetry.
+- `metrics`: List of metrics with their name, description, type, unit, and attributes
+- `spans`: List of span configurations with their span_kind and attributes
+
+For metrics, supported `type` values include: `COUNTER`, `GAUGE`, `HISTOGRAM`, `EXPONENTIAL_HISTOGRAM`.
+
+For spans, supported `span_kind` values include: `CLIENT`, `SERVER`, `PRODUCER`, `CONSUMER`, `INTERNAL`.
+
+For attributes, supported `type` values include: `STRING`, `LONG`, `DOUBLE`, `BOOLEAN`.
+
+#### override_telemetry
+
+Set `override_telemetry: true` to completely replace any auto-generated telemetry data from `.telemetry`
+files. When this is enabled, only the manually documented telemetry in `additional_telemetry` will be
+used, and any `.telemetry` files will be ignored.
+
+```yaml
+override_telemetry: true
+additional_telemetry:
+  - when: "default"
+    metrics:
+      - name: "manually.documented.metric"
+        description: "This completely replaces auto-generated telemetry"
+        type: "GAUGE"
+        unit: "bytes"
+```
+
+If `override_telemetry` is `false` or omitted (default behavior), manual telemetry will be merged with
+auto-generated telemetry, with manual entries taking precedence in case of conflicts (same metric name
+or span kind within the same `when` condition).
+
 ## Instrumentation List (docs/instrumentation-list.md)
 
 The contents of the `metadata.yaml` files are combined with other information about the instrumentation

docs/instrumentation-list.yaml

@@ -390,6 +390,33 @@ libraries:
       default: ''
     telemetry:
     - when: default
+      metrics:
+      - name: rpc.client.duration
+        description: The duration of an outbound RPC invocation.
+        type: HISTOGRAM
+        unit: ms
+        attributes:
+        - name: rpc.method
+          type: STRING
+        - name: rpc.service
+          type: STRING
+        - name: rpc.system
+          type: STRING
+        - name: server.address
+          type: STRING
+        - name: server.port
+          type: LONG
+      - name: rpc.server.duration
+        description: The duration of an inbound RPC invocation.
+        type: HISTOGRAM
+        unit: ms
+        attributes:
+        - name: rpc.method
+          type: STRING
+        - name: rpc.service
+          type: STRING
+        - name: rpc.system
+          type: STRING
       spans:
       - span_kind: CLIENT
         attributes:
@@ -6399,13 +6426,6 @@ libraries:
     scope:
       name: io.opentelemetry.runtime-telemetry-java8
   rxjava:
-  - name: rxjava-1.0
-    source_path: instrumentation/rxjava/rxjava-1.0
-    scope:
-      name: io.opentelemetry.rxjava-1.0
-    target_versions:
-      library:
-      - io.reactivex:rxjava:1.0.7
   - name: rxjava-2.0
     source_path: instrumentation/rxjava/rxjava-2.0
     scope:
@@ -7977,6 +7997,13 @@ internal:
   source_path: instrumentation/internal/internal-lambda
   scope:
     name: io.opentelemetry.internal-lambda
+- name: rxjava-1.0
+  source_path: instrumentation/rxjava/rxjava-1.0
+  scope:
+    name: io.opentelemetry.rxjava-1.0
+  target_versions:
+    library:
+    - io.reactivex:rxjava:1.0.7
 - name: internal-eclipse-osgi-3.6
   source_path: instrumentation/internal/internal-eclipse-osgi-3.6
   scope:

examples/distro/build.gradle

@@ -12,8 +12,8 @@ buildscript {
     }
   }
   dependencies {
-    classpath "com.diffplug.spotless:spotless-plugin-gradle:7.2.1"
-    classpath "com.gradleup.shadow:shadow-gradle-plugin:9.1.0"
+    classpath "com.diffplug.spotless:spotless-plugin-gradle:8.0.0"
+    classpath "com.gradleup.shadow:shadow-gradle-plugin:9.2.1"
     classpath "io.opentelemetry.instrumentation:gradle-plugins:2.21.0-alpha-SNAPSHOT"
   }
 }

examples/extension/build.gradle

@@ -10,8 +10,8 @@ plugins {
   into a single jar.
   See https://imperceptiblethoughts.com/shadow/ for more details about Shadow plugin.
    */
-  id "com.gradleup.shadow" version "9.1.0"
-  id "com.diffplug.spotless" version "7.2.1"
+  id "com.gradleup.shadow" version "9.2.1"
+  id "com.diffplug.spotless" version "8.0.0"
 
   id "io.opentelemetry.instrumentation.muzzle-generation" version "2.21.0-alpha-SNAPSHOT"
   id "io.opentelemetry.instrumentation.muzzle-check" version "2.21.0-alpha-SNAPSHOT"
@@ -95,7 +95,7 @@ dependencies {
   Only dependencies added to `implementation` configuration will be picked up by Shadow plugin
   and added to the resulting jar for our extension's distribution.
    */
-  implementation 'org.apache.commons:commons-lang3:3.18.0'
+  implementation 'org.apache.commons:commons-lang3:3.19.0'
 
   //All dependencies below are only for tests
   testImplementation("org.testcontainers:testcontainers:1.21.3")