Merge branch 'main' into otelbot/update-opentelemetry-sdk-to-1.48.0

Author: laurit

.github/workflows/codeql.yml

@@ -50,7 +50,7 @@ jobs:
           cache-read-only: ${{ github.event_name == 'pull_request' }}
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@b56ba49b26e50535fa1e7f7db0f4f7b4bf65d80d # v3.28.10
+        uses: github/codeql-action/init@6bb031afdd8eb862ea3fc1848194185e076637e5 # v3.28.11
         with:
           languages: java, actions
           # using "latest" helps to keep up with the latest Kotlin support
@@ -65,4 +65,4 @@ jobs:
         run: ./gradlew assemble -x javadoc -x :instrumentation:quarkus-resteasy-reactive:quarkus3-testing:quarkusGenerateCodeDev -x :instrumentation:quarkus-resteasy-reactive:quarkus2-testing:quarkusGenerateCodeDev --no-build-cache --no-daemon
 
       - name: Perform CodeQL analysis
-        uses: github/codeql-action/analyze@b56ba49b26e50535fa1e7f7db0f4f7b4bf65d80d # v3.28.10
+        uses: github/codeql-action/analyze@6bb031afdd8eb862ea3fc1848194185e076637e5 # v3.28.11

.github/workflows/ossf-scorecard.yml

@@ -42,6 +42,6 @@ jobs:
       # Upload the results to GitHub's code scanning dashboard (optional).
       # Commenting out will disable upload of results to your repo's Code Scanning dashboard
       - name: "Upload to code-scanning"
-        uses: github/codeql-action/upload-sarif@b56ba49b26e50535fa1e7f7db0f4f7b4bf65d80d # v3.28.10
+        uses: github/codeql-action/upload-sarif@6bb031afdd8eb862ea3fc1848194185e076637e5 # v3.28.11
         with:
           sarif_file: results.sarif

.github/workflows/reusable-native-tests.yml

@@ -21,7 +21,7 @@ jobs:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
       - id: read-java
         run: echo "version=$(cat .java-version)" >> "$GITHUB_OUTPUT"
-      - uses: graalvm/setup-graalvm@b0cb26a8da53cb3e97cdc0c827d8e3071240e730 # v1.3.1.1
+      - uses: graalvm/setup-graalvm@01ed653ac833fe80569f1ef9f25585ba2811baab # v1.3.3.1
         with:
           version: "latest"
           java-version: "${{ steps.read-java.outputs.version }}"

docs/contributing/writing-instrumentation.md

@@ -58,6 +58,7 @@ instrumentation ->
             build.gradle.kts
         testing
             build.gradle.kts
+        metadata.yaml
 ```
 
 The top level `settings.gradle.kts` file would contain the following (please add in alphabetical order):
@@ -68,6 +69,15 @@ include("instrumentation:yarpc-1.0:library")
 include("instrumentation:yarpc-1.0:testing")
 ```
 
+### Instrumentation metadata.yaml (Experimental)
+
+Each module can contain a `metadata.yaml` file that describes the instrumentation. This information
+is then used when generating the [instrumentation-list.yaml](../instrumentation-list.yaml) file.
+The schema for `metadata.yaml` is still in development and may change in the future. See the
+[instrumentation-docs readme](../../instrumentation-docs/readme.md) for more information and the
+latest schema.
+
+
 ### Instrumentation Submodules
 
 When writing instrumentation that requires submodules for different versions, the name of each
@@ -215,10 +225,10 @@ library instrumentation test, there will be code calling into the instrumentatio
 javaagent instrumentation test it will generally use the underlying library API as is and just rely
 on the javaagent to apply all the necessary bytecode changes automatically.
 
-You can use either JUnit 5 (recommended) or Spock to test the instrumentation. Start by creating an
-abstract class with an abstract method, for example `configure()`, that returns the instrumented
-object, such as a client, server, or the main class of the instrumented library. Then, depending on
-the chosen test library, go to the [JUnit](#junit) or [Spock](#spock) section.
+You can use JUnit 5 to test the instrumentation. Start by creating an abstract class with an
+abstract method, for example `configure()`, that returns the instrumented object, such as a client,
+server, or the main class of the instrumented library. See the [JUnit](#junit) section for more
+information.
 
 After writing some tests, return to the `library` package and make sure it has
 a `testImplementation` dependency on the `testing` submodule. Then, create a test class that extends
@@ -281,37 +291,6 @@ You can use the `@RegisterExtension` annotation to make sure that the instrument
 picked up by JUnit. Then, return the same extension instance in the `testing()` method
 implementation so that it's used in all test scenarios implemented in the abstract class.
 
-### Spock
-
-The `testing-common` module contains some utilities that facilitate writing Spock instrumentation
-tests, such as the `InstrumentationSpecification` base class and the `LibraryTestTrait`
-and `AgentTestTrait` traits.
-
-Consider the following abstract test class extending `InstrumentationSpecification`:
-
-```groovy
-abstract class AbstractYarpcTest extends InstrumentationSpecification {
-
-  abstract Yarpc configure(Yarpc yarpc);
-
-  def "test something"() {
-    // ...
-  }
-}
-```
-
-The `InstrumentationSpecification` class contains abstract methods that are implemented by one of
-our test traits in the actual test class. For example:
-
-```groovy
-class LibraryYarpcTest extends AbstractYarpcTest implements LibraryTestTrait {
-
-  @Override
-  Yarpc configure(Yarpc yarpc) {
-    // register interceptor/listener etc
-  }
-}
-```
 
 ## Writing Java agent instrumentation
 
@@ -352,9 +331,8 @@ without the user knowing about the instrumentation.
 
 Create a test that extends the base class you wrote earlier but does nothing in the `configure()`
 method. Unlike the library instrumentation, the javaagent instrumentation is supposed to work
-without any explicit user code modification. Depending on the testing framework, either use
-the `AgentInstrumentationExtension` or implement the `AgentTestingTrait`, and try running tests in
-this class. All tests should pass.
+without any explicit user code modification. Add an `AgentInstrumentationExtension` and try running
+tests in this class. All tests should pass.
 
 Note that all the tests inside the `javaagent` module are run using the `agent-for-testing`
 javaagent, with the instrumentation being loaded as an extension. This is done to perform the same

docs/instrumentation-list.yaml

@@ -58,7 +58,7 @@ apache:
     srcPath: instrumentation/apache-httpclient/apache-httpclient-4.3
     target_versions:
       library:
-      - org.apache.httpcomponents:httpclient:4.3
+      - org.apache.httpcomponents:httpclient:[4.3,4.+)
   - name: apache-httpclient-4.0
     srcPath: instrumentation/apache-httpclient/apache-httpclient-4.0
     target_versions:
@@ -137,7 +137,7 @@ aws:
       - com.amazonaws:aws-java-sdk-sqs:[1.10.33,)
       - com.amazonaws:aws-java-sdk-core:[1.10.33,)
       library:
-      - com.amazonaws:aws-java-sdk-sqs:1.11.106
+      - com.amazonaws:aws-java-sdk-sqs:[1.11.106,1.12.583)
       - com.amazonaws:aws-java-sdk-core:1.11.0
   - name: aws-sdk-2.2
     srcPath: instrumentation/aws-sdk/aws-sdk-2.2
@@ -204,10 +204,13 @@ cassandra:
   - name: cassandra-3.0
     srcPath: instrumentation/cassandra/cassandra-3.0
     target_versions:
-      javaagent: []
+      javaagent:
+      - com.datastax.cassandra:cassandra-driver-core:[3.0,4.0)
 clickhouse:
   instrumentations:
   - name: clickhouse-client-0.5
+    description: Instruments the V1 ClickHouseClient, providing database client spans
+      and metrics.
     srcPath: instrumentation/clickhouse-client-0.5
     target_versions:
       javaagent:
@@ -352,7 +355,7 @@ graphql:
       javaagent:
       - com.graphql-java:graphql-java:[12,20)
       library:
-      - com.graphql-java:graphql-java:12.0
+      - com.graphql-java:graphql-java:[12.0,19.+)
   - name: graphql-java-20.0
     srcPath: instrumentation/graphql-java/graphql-java-20.0
     target_versions:
@@ -651,7 +654,7 @@ jetty:
       javaagent:
       - org.eclipse.jetty:jetty-client:[9.2,10)
       library:
-      - org.eclipse.jetty:jetty-client:9.2.0.v20140526
+      - org.eclipse.jetty:jetty-client:[9.2.0.v20140526,9.+)
   - name: jetty-11.0
     srcPath: instrumentation/jetty/jetty-11.0
     target_versions:
@@ -765,8 +768,8 @@ ktor:
       - io.ktor:ktor-client-core:[2.0.0,3.0.0)
       - io.ktor:ktor-server-core:[2.0.0,3.0.0)
       library:
-      - io.ktor:ktor-server-core:2.0.0
-      - io.ktor:ktor-client-core:2.0.0
+      - io.ktor:ktor-client-core:[2.0.0,2.+)
+      - io.ktor:ktor-server-core:[2.0.0,2.+)
   - name: ktor-3.0
     srcPath: instrumentation/ktor/ktor-3.0
     target_versions:
@@ -780,7 +783,7 @@ ktor:
     srcPath: instrumentation/ktor/ktor-1.0
     target_versions:
       library:
-      - io.ktor:ktor-server-core:1.0.0
+      - io.ktor:ktor-server-core:[1.0.0,1.+)
 kubernetes:
   instrumentations:
   - name: kubernetes-client-7.0
@@ -1049,7 +1052,7 @@ oshi:
       javaagent:
       - com.github.oshi:oshi-core:[5.3.1,)
       library:
-      - com.github.oshi:oshi-core:$oshiVersion
+      - com.github.oshi:oshi-core:5.3.1
 payara:
   instrumentations:
   - name: payara
@@ -1069,8 +1072,11 @@ pekko:
     srcPath: instrumentation/pekko/pekko-http-1.0
     target_versions:
       javaagent:
+      - com.softwaremill.sttp.tapir:tapir-pekko-http-server_3:[1.7,)
+      - com.softwaremill.sttp.tapir:tapir-pekko-http-server_2.12:[1.7,)
       - org.apache.pekko:pekko-http_2.12:[1.0,)
       - org.apache.pekko:pekko-http_3:[1.0,)
+      - com.softwaremill.sttp.tapir:tapir-pekko-http-server_2.13:[1.7,)
       - org.apache.pekko:pekko-http_2.13:[1.0,)
 play:
   instrumentations:
@@ -1233,7 +1239,7 @@ restlet:
       javaagent:
       - org.restlet:org.restlet:[1.1.0, 1.2-M1)
       library:
-      - org.restlet:org.restlet:1.1.5
+      - org.restlet:org.restlet:[1.1.5,1.+)
       - com.noelios.restlet:com.noelios.restlet:1.1.5
   - name: restlet-2.0
     srcPath: instrumentation/restlet/restlet-2.0
@@ -1301,7 +1307,7 @@ rxjava:
       javaagent:
       - io.reactivex.rxjava3:rxjava:[3.0.0,3.1.0]
       library:
-      - io.reactivex.rxjava3:rxjava:3.0.12
+      - io.reactivex.rxjava3:rxjava:[3.0.12,3.1.0)
 scala:
   instrumentations:
   - name: scala-fork-join-2.8
@@ -1446,7 +1452,7 @@ spring:
       javaagent:
       - org.springframework.integration:spring-integration-core:[4.1.0.RELEASE,)
       library:
-      - org.springframework.integration:spring-integration-core:4.1.0.RELEASE
+      - org.springframework.integration:spring-integration-core:[4.1.0.RELEASE,5.+)
   - name: spring-jms-2.0
     srcPath: instrumentation/spring/spring-jms/spring-jms-2.0
     target_versions:

instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/genai/GenAiAttributesGetter.java

@@ -50,7 +50,6 @@ public interface GenAiAttributesGetter<REQUEST, RESPONSE> {
   @Nullable
   Double getRequestTopP(REQUEST request);
 
-  @Nullable
   List<String> getResponseFinishReasons(REQUEST request, RESPONSE response);
 
   @Nullable

instrumentation-docs/readme.md

@@ -39,25 +39,35 @@ public class SpringWebInstrumentationModule extends InstrumentationModule
   }
 ```
 
-## Instrumentation meta-data
+## Instrumentation metadata
 
 * name
   * Identifier for instrumentation module, used to enable/disable
   * Configured in `InstrumentationModule` code for each module
-* versions
-  * List of supported versions by the module
-* type
-  * List of instrumentation types, options of either `library` or `javaagent`
+* srcPath
+  * Path to the source code of the instrumentation module
+* description
+  * Short description of what the instrumentation does
+* target_versions
+  * List of supported versions by the module, broken down by `library` or `javaagent` support
 
 ## Methodology
 
-### Versions targeted
+### metadata.yaml file
+
+Within each instrumentation source directory, a `metadata.yaml` file can be created to provide
+additional information about the instrumentation module.
 
-Javaagent versions are determined by the `muzzle` plugin, so we can attempt to parse the gradle files
+As of now, the following fields are supported:
 
-Library versions are determined by the library versions used in the gradle files.
+```yaml
+description: "Description of what the instrumentation does."
+```
+
+### Versions targeted
 
-### TODO / Notes
+We parse gradle files in order to determine the target versions.
 
-- Is the `library` dependency actually the target version? Is there a better way to present the information?
-- How to handle oshi target version with a conditional?
+- Javaagent versions are determined by the `muzzle` plugin configurations
+- Library versions are determined by the library dependency versions
+  - when available, latestDepTestLibrary is used to determine the latest supported version

instrumentation-docs/src/main/java/io/opentelemetry/instrumentation/docs/GradleParser.java

@@ -13,18 +13,23 @@
 import java.util.regex.Pattern;
 
 class GradleParser {
-  private static final Pattern passBlockPattern =
-      Pattern.compile("pass\\s*\\{(.*?)}", Pattern.DOTALL);
-
-  private static final Pattern libraryPattern =
-      Pattern.compile("library\\(\"([^\"]+:[^\"]+:[^\"]+)\"\\)");
 
   private static final Pattern variablePattern =
       Pattern.compile("val\\s+(\\w+)\\s*=\\s*\"([^\"]+)\"");
 
+  private static final Pattern muzzlePassBlockPattern =
+      Pattern.compile("pass\\s*\\{(.*?)}", Pattern.DOTALL);
+
+  private static final Pattern libraryPattern =
+      Pattern.compile("library\\(\"([^\"]+:[^\"]+):([^\"]+)\"\\)");
+
   private static final Pattern compileOnlyPattern =
       Pattern.compile(
-          "compileOnly\\(\"([^\"]+)\"\\)\\s*\\{\\s*version\\s*\\{(?:\\s*//.*\\n)*\\s*strictly\\(\"([^\"]+)\"\\)\\s*}\\s*}");
+          "compileOnly\\(\"([^\"]+:[^\"]+)(?::[^\"]+)?\"\\)\\s*\\{\\s*version\\s*\\{.*?strictly\\(\"([^\"]+)\"\\).*?}\\s*",
+          Pattern.DOTALL);
+
+  private static final Pattern latestDepTestLibraryPattern =
+      Pattern.compile("latestDepTestLibrary\\(\"([^\"]+:[^\"]+):([^\"]+)\"\\)");
 
   /**
    * Parses gradle files for muzzle and dependency information
@@ -55,7 +60,7 @@ public static Set<String> parseGradleFile(String gradleFileContents, Instrumenta
    */
   private static Set<String> parseMuzzle(String gradleFileContents, Map<String, String> variables) {
     Set<String> results = new HashSet<>();
-    Matcher passBlockMatcher = passBlockPattern.matcher(gradleFileContents);
+    Matcher passBlockMatcher = muzzlePassBlockPattern.matcher(gradleFileContents);
 
     while (passBlockMatcher.find()) {
       String passBlock = passBlockMatcher.group(1);
@@ -74,26 +79,50 @@ private static Set<String> parseMuzzle(String gradleFileContents, Map<String, St
 
   /**
    * Parses the "dependencies" block from the given Gradle file content and extracts information
-   * about what library versions are supported.
+   * about what library versions are supported. Looks for library() and compileOnly() blocks for
+   * lower bounds, and latestDepTestLibrary() for upper bounds.
    *
    * @param gradleFileContents Contents of a Gradle build file as a String
    * @param variables Map of variable names to their values
    * @return A set of strings summarizing the group, module, and versions
    */
   private static Set<String> parseLibraryDependencies(
       String gradleFileContents, Map<String, String> variables) {
-    Set<String> results = new HashSet<>();
+    Map<String, String> versions = new HashMap<>();
+
     Matcher libraryMatcher = libraryPattern.matcher(gradleFileContents);
+
     while (libraryMatcher.find()) {
-      String dependency = libraryMatcher.group(1);
-      results.add(interpolate(dependency, variables));
+      String groupAndArtifact = libraryMatcher.group(1);
+      String version = libraryMatcher.group(2);
+      versions.put(groupAndArtifact, version);
     }
 
     Matcher compileOnlyMatcher = compileOnlyPattern.matcher(gradleFileContents);
     while (compileOnlyMatcher.find()) {
-      String dependency = compileOnlyMatcher.group(1) + ":" + compileOnlyMatcher.group(2);
-      results.add(interpolate(dependency, variables));
+      String groupAndArtifact = compileOnlyMatcher.group(1);
+      String version = compileOnlyMatcher.group(2);
+      versions.put(groupAndArtifact, version);
     }
+
+    Matcher latestDepTestLibraryMatcher = latestDepTestLibraryPattern.matcher(gradleFileContents);
+    while (latestDepTestLibraryMatcher.find()) {
+      String groupAndArtifact = latestDepTestLibraryMatcher.group(1);
+      String version = latestDepTestLibraryMatcher.group(2);
+      if (versions.containsKey(groupAndArtifact)) {
+        versions.put(groupAndArtifact, versions.get(groupAndArtifact) + "," + version);
+      }
+    }
+
+    Set<String> results = new HashSet<>();
+    for (Map.Entry<String, String> entry : versions.entrySet()) {
+      if (entry.getValue().contains(",")) {
+        results.add(interpolate(entry.getKey() + ":[" + entry.getValue() + ")", variables));
+      } else {
+        results.add(interpolate(entry.getKey() + ":" + entry.getValue(), variables));
+      }
+    }
+
     return results;
   }