update parsers

Author: jaydeluca

docs/instrumentation-list.yaml

@@ -59,6 +59,8 @@ libraries:
           type: STRING
   akka:
   - name: akka-actor-2.3
+    description: This instrumentation provides context propagation for Akka actors,
+      it does not emit any telemetry on its own.
     source_path: instrumentation/akka/akka-actor-2.3
     scope:
       name: io.opentelemetry.akka-actor-2.3
@@ -68,6 +70,8 @@ libraries:
       - com.typesafe.akka:akka-actor_2.12:[2.3,)
       - com.typesafe.akka:akka-actor_2.13:[2.3,)
   - name: akka-actor-fork-join-2.5
+    description: This instrumentation provides context propagation for the Akka Fork-Join
+      Pool, it does not emit any telemetry on its own.
     source_path: instrumentation/akka/akka-actor-fork-join-2.5
     scope:
       name: io.opentelemetry.akka-actor-fork-join-2.5
@@ -780,6 +784,37 @@ libraries:
     target_versions:
       javaagent:
       - com.linecorp.armeria:armeria-grpc:[1.14.0,)
+    telemetry:
+    - when: default
+      spans:
+      - span_kind: CLIENT
+        attributes:
+        - name: rpc.grpc.status_code
+          type: LONG
+        - 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
+      - span_kind: SERVER
+        attributes:
+        - name: rpc.grpc.status_code
+          type: LONG
+        - 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
   async:
   - name: async-http-client-1.9
     description: This instrumentation enables CLIENT spans and metrics for version
@@ -887,7 +922,7 @@ libraries:
   aws:
   - name: aws-lambda-core-1.0
     description: |
-      Provides lightweight instrumentation of the Lambda core library, supporting all versions. Use this package if you only use `RequestStreamHandler` or know you don't use any event classes from `aws-lambda-java-events`. This also includes when you are using `aws-serverless-java-container` to run e.g., a Spring Boot application on Lambda.
+      Provides lightweight instrumentation of the Lambda core library, supporting all versions. It generates FaaS SERVER spans with the `faas.invocation_id` attribute. Use this package if you only use `RequestStreamHandler` or know you don't use any event classes from `aws-lambda-java-events`. This also includes when you are using `aws-serverless-java-container` to run e.g., a Spring Boot application on Lambda.
     source_path: instrumentation/aws-lambda/aws-lambda-core-1.0
     scope:
       name: io.opentelemetry.aws-lambda-core-1.0
@@ -901,6 +936,13 @@ libraries:
       description: Flush timeout in milliseconds.
       type: int
       default: 10000
+    telemetry:
+    - when: default
+      spans:
+      - span_kind: SERVER
+        attributes:
+        - name: faas.invocation_id
+          type: STRING
   - name: aws-lambda-events-2.2
     description: |
       Provides full instrumentation of the Lambda library, including standard and custom event types, from `aws-lambda-java-events` 2.2+.
@@ -918,7 +960,32 @@ libraries:
       description: Flush timeout in milliseconds.
       type: int
       default: 10000
+    telemetry:
+    - when: default
+      spans:
+      - span_kind: CONSUMER
+        attributes:
+        - name: messaging.operation
+          type: STRING
+        - name: messaging.system
+          type: STRING
+      - span_kind: SERVER
+        attributes:
+        - name: faas.invocation_id
+          type: STRING
+        - name: faas.trigger
+          type: STRING
+        - name: http.request.method
+          type: STRING
+        - name: http.response.status_code
+          type: LONG
+        - name: url.full
+          type: STRING
+        - name: user_agent.original
+          type: STRING
   - name: aws-sdk-1.11
+    description: |
+      This instrumentation covers the AWS SDK 1.11+ client library, enabling messaging and client spans and metrics for calls to AWS services including DynamoDB, EC2, Kinesis, Lambda, RDS, S3, secrets manager, SNS/SQS and step functions.
     source_path: instrumentation/aws-sdk/aws-sdk-1.11
     scope:
       name: io.opentelemetry.aws-sdk-1.11
@@ -931,7 +998,8 @@ libraries:
       - com.amazonaws:aws-java-sdk-core:1.11.0
     configurations:
     - name: otel.instrumentation.aws-sdk.experimental-span-attributes
-      description: Enables experimental span attributes for AWS SDK instrumentation.
+      description: |
+        Enables the experimental span attributes `aws.agent`, `aws.bucket.name`, `aws.queue.url`, `aws.queue.name`, `aws.stream.name`, `aws.table.name`, `aws.lambda.function.arn` and `aws.lambda.function.name` for AWS SDK instrumentation.
       type: boolean
       default: false
     - name: otel.instrumentation.messaging.experimental.receive-telemetry.enabled
@@ -1143,6 +1211,8 @@ libraries:
         - name: url.full
           type: STRING
   - name: aws-sdk-2.2
+    description: |
+      This instrumentation covers the AWS SDK 2.2+ client library, enabling messaging and client spans and metrics for calls to AWS services including DynamoDB, EC2, Kinesis, Lambda, RDS, S3, SNS/SQS and Bedrock.
     source_path: instrumentation/aws-sdk/aws-sdk-2.2
     scope:
       name: io.opentelemetry.aws-sdk-2.2
@@ -1170,7 +1240,8 @@ libraries:
       type: list
       default: ''
     - name: otel.instrumentation.aws-sdk.experimental-span-attributes
-      description: Enables experimental span attributes for AWS SDK instrumentation.
+      description: |
+        Enables experimental span attributes `aws.agent`, `aws.lambda.function.arn` and `aws.lambda.function.name` for AWS SDK instrumentation.
       type: boolean
       default: false
     - name: otel.instrumentation.aws-sdk.experimental-use-propagator-for-messaging
@@ -1179,9 +1250,8 @@ libraries:
       type: boolean
       default: false
     - name: otel.instrumentation.genai.capture-message-content
-      description: Determines whether Generative AI events include full content of
-        user and assistant messages. Note that full content can have data privacy
-        and size concerns and care should be taken when enabling this
+      description: |
+        Determines whether Generative AI events include full content of user and assistant messages. Note that full content can have data privacy and size concerns and care should be taken when enabling this
       type: boolean
       default: false
     - name: otel.instrumentation.aws-sdk.experimental-record-individual-http-error
@@ -1499,20 +1569,26 @@ libraries:
           type: STRING
   azure:
   - name: azure-core-1.14
+    description: This instrumentation enables context propagation for the Azure Core
+      library, it does not emit any telemetry on its own.
     source_path: instrumentation/azure-core/azure-core-1.14
     scope:
       name: io.opentelemetry.azure-core-1.14
     target_versions:
       javaagent:
       - com.azure:azure-core:[1.14.0,1.19.0)
   - name: azure-core-1.19
+    description: This instrumentation enables context propagation for the Azure Core
+      library, it does not emit any telemetry on its own.
     source_path: instrumentation/azure-core/azure-core-1.19
     scope:
       name: io.opentelemetry.azure-core-1.19
     target_versions:
       javaagent:
       - com.azure:azure-core:[1.19.0,1.36.0)
   - name: azure-core-1.36
+    description: This instrumentation enables context propagation for the Azure Core
+      library, it does not emit any telemetry on its own.
     source_path: instrumentation/azure-core/azure-core-1.36
     scope:
       name: io.opentelemetry.azure-core-1.36

instrumentation-docs/instrumentations.sh

@@ -114,6 +114,9 @@ readonly INSTRUMENTATIONS=(
   "spring:spring-webmvc:spring-webmvc-6.0:javaagent:test"
   "spring:spring-webmvc:spring-webmvc-6.0:javaagent:testExperimental"
   "openai:openai-java-1.1:javaagent:test"
+  "aws-lambda:aws-lambda-core-1.0:javaagent:test"
+  "aws-lambda:aws-lambda-events-2.2:javaagent:test"
+  "azure-core:azure-core-1.19:javaagent:testAzure"
 )
 
 #  Some instrumentation test suites don't run ARM, so we use colima to run them in an x86_64

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

@@ -64,7 +64,7 @@ private void enrichModule(InstrumentationModule module) throws IOException {
     }
 
     module.setTargetVersions(getVersionInformation(module));
-    module.setMetrics(MetricParser.getMetrics(module, fileManager));
+    module.setMetrics(MetricParser.get(module, fileManager));
     module.setSpans(SpanParser.getSpans(module, fileManager));
   }
 

instrumentation-docs/src/main/java/io/opentelemetry/instrumentation/docs/parsers/EmittedParser.java

@@ -0,0 +1,8 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.docs.parsers;
+
+abstract class EmittedParser {}

instrumentation-docs/src/main/java/io/opentelemetry/instrumentation/docs/parsers/MetricParser.java

@@ -20,7 +20,7 @@
  * This class is responsible for parsing metric files from the `.telemetry` directory of an
  * instrumentation module and filtering them by scope.
  */
-public class MetricParser {
+public class MetricParser extends TelemetryParser {
 
   /**
    * Retrieves metrics for a given instrumentation module, filtered by scope.
@@ -29,7 +29,7 @@ public class MetricParser {
    * @param fileManager the file manager to use for file operations
    * @return a map where the key is the 'when' condition and the value is a list of metrics
    */
-  public static Map<String, List<EmittedMetrics.Metric>> getMetrics(
+  public static Map<String, List<EmittedMetrics.Metric>> get(
       InstrumentationModule module, FileManager fileManager) {
     Map<String, EmittedMetrics> metrics =
         EmittedMetricsParser.getMetricsFromFiles(fileManager.rootDir(), module.getSrcPath());
@@ -109,7 +109,10 @@ public static Map<String, Map<String, AggregatedMetricInfo>> aggregateMetrics(
           aggregatedMetrics.computeIfAbsent(when, k -> new HashMap<>());
 
       for (EmittedMetrics.MetricsByScope metricsByScope : metrics.getMetricsByScope()) {
-        if (metricsByScope.getScope().equals(targetScopeName)) {
+        if (metricsByScope.getScope().equals(targetScopeName)
+            || scopeAllowList
+                .getOrDefault(targetScopeName, Set.of())
+                .contains(metricsByScope.getScope())) {
           for (EmittedMetrics.Metric metric : metricsByScope.getMetrics()) {
             AggregatedMetricInfo aggInfo =
                 metricKindMap.computeIfAbsent(

instrumentation-docs/src/main/java/io/opentelemetry/instrumentation/docs/parsers/SpanParser.java

@@ -21,7 +21,7 @@
  * This class is responsible for parsing span files from the `.telemetry` directory of an
  * instrumentation module and filtering them by scope.
  */
-public class SpanParser {
+public class SpanParser extends TelemetryParser {
 
   // We want to ignore test related attributes
   private static final List<String> EXCLUDED_ATTRIBUTES =
@@ -87,7 +87,10 @@ public static Map<String, Map<String, Set<TelemetryAttribute>>> aggregateSpans(
           aggregatedAttributes.computeIfAbsent(when, k -> new HashMap<>());
 
       for (EmittedSpans.SpansByScope spansByScope : spans.getSpansByScope()) {
-        if (spansByScope.getScope().equals(targetScopeName)) {
+        if (spansByScope.getScope().equals(targetScopeName)
+            || scopeAllowList
+                .getOrDefault(targetScopeName, Set.of())
+                .contains(spansByScope.getScope())) {
           processSpansForScope(spansByScope, spanKindMap);
         }
       }

instrumentation-docs/src/main/java/io/opentelemetry/instrumentation/docs/parsers/TelemetryParser.java

@@ -0,0 +1,20 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.docs.parsers;
+
+import java.util.Map;
+import java.util.Set;
+
+abstract class TelemetryParser {
+
+  // If an instrumentation module uses an instrumenter or telemetry class from another module, it
+  // might report telemetry with a different scope name, resulting in us excluding it. There are
+  // cases where we want to include this data, so we provide this way to override that exclusion
+  // filter. The key is the scope of the module being analyzed, the value is a set of additional
+  // allowed scopes.
+  protected static final Map<String, Set<String>> scopeAllowList =
+      Map.of("io.opentelemetry.armeria-grpc-1.14", Set.of("io.opentelemetry.grpc-1.6"));
+}

instrumentation-docs/src/test/java/io/opentelemetry/instrumentation/docs/parsers/MetricParserTest.java

@@ -107,6 +107,31 @@ void testPreservesMetricMetadata() {
     assertThat(foundMetric.getUnit()).isEqualTo("unit");
   }
 
+  @Test
+  void testScopeOverrideForGrpc() {
+    String targetScopeName = "io.opentelemetry.armeria-grpc-1.14";
+
+    EmittedMetrics.Metric metric1 =
+        createMetric("my.metric1", "description of my.metric1", "attr1");
+
+    EmittedMetrics.MetricsByScope targetMetricsByScope =
+        new EmittedMetrics.MetricsByScope("io.opentelemetry.grpc-1.6", List.of(metric1));
+
+    EmittedMetrics emittedMetrics = new EmittedMetrics("default", List.of(targetMetricsByScope));
+
+    Map<String, Map<String, MetricParser.MetricAggregator.AggregatedMetricInfo>> metrics =
+        MetricParser.MetricAggregator.aggregateMetrics("default", emittedMetrics, targetScopeName);
+
+    Map<String, List<EmittedMetrics.Metric>> result =
+        MetricParser.MetricAggregator.buildFilteredMetrics(metrics);
+
+    EmittedMetrics.Metric foundMetric = result.get("default").get(0);
+    assertThat(foundMetric.getName()).isEqualTo("my.metric1");
+    assertThat(foundMetric.getDescription()).isEqualTo("description of my.metric1");
+    assertThat(foundMetric.getType()).isEqualTo("gauge");
+    assertThat(foundMetric.getUnit()).isEqualTo("unit");
+  }
+
   private static EmittedMetrics.Metric createMetric(
       String name, String description, String attrName) {
     return new EmittedMetrics.Metric(

instrumentation-docs/src/test/java/io/opentelemetry/instrumentation/docs/parsers/SpanParserTest.java

@@ -195,4 +195,70 @@ void testSpanAggregatorFiltersAndAggregatesCorrectly() {
         .extracting(TelemetryAttribute::getName)
         .containsExactly("my.operation");
   }
+
+  @Test
+  void getSpansFromFilesIncludesAllowListedScopes(@TempDir Path tempDir) throws IOException {
+    Path telemetryDir = Files.createDirectories(tempDir.resolve(".telemetry"));
+
+    String file1Content =
+        """
+        when: default
+        spans_by_scope:
+          - scope: io.opentelemetry.grpc-1.6
+            spans:
+              - span_kind: CLIENT
+                attributes:
+                  - name: rpc.system
+                    type: STRING
+                  - name: rpc.grpc.status_code
+                    type: LONG
+                  - name: server.port
+                    type: LONG
+                  - name: rpc.method
+                    type: STRING
+                  - name: rpc.service
+                    type: STRING
+                  - name: server.address
+                    type: STRING
+              - span_kind: SERVER
+                attributes:
+                  - name: rpc.system
+                    type: STRING
+                  - name: rpc.grpc.status_code
+                    type: LONG
+                  - name: server.port
+                    type: LONG
+                  - name: rpc.method
+                    type: STRING
+                  - name: rpc.service
+                    type: STRING
+                  - name: server.address
+                    type: STRING
+      """;
+
+    Files.writeString(telemetryDir.resolve("spans-1.yaml"), file1Content);
+
+    try (MockedStatic<FileManager> fileManagerMock = mockStatic(FileManager.class)) {
+      fileManagerMock
+          .when(() -> FileManager.readFileToString(telemetryDir.resolve("spans-1.yaml").toString()))
+          .thenReturn(file1Content);
+
+      Map<String, EmittedSpans> fileContents =
+          EmittedSpanParser.getSpansByScopeFromFiles(tempDir.toString(), "");
+
+      EmittedSpans emittedSpans = fileContents.get("default");
+
+      // Aggregate spans - only target scope should be included
+      Map<String, Map<String, Set<TelemetryAttribute>>> spans =
+          SpanParser.SpanAggregator.aggregateSpans(
+              "default", emittedSpans, "io.opentelemetry.armeria-grpc-1.14");
+
+      Map<String, List<EmittedSpans.Span>> result =
+          SpanParser.SpanAggregator.buildFilteredSpans(spans);
+
+      assertThat(result.size()).isEqualTo(1);
+      assertThat(result.get("default")).isNotNull();
+      assertThat(result.get("default").size()).isEqualTo(2);
+    }
+  }
 }

instrumentation/aws-lambda/aws-lambda-core-1.0/javaagent/build.gradle.kts

@@ -28,5 +28,4 @@ tasks.withType<Test>().configureEach {
   jvmArgs("-XX:+IgnoreUnrecognizedVMOptions")
 
   systemProperty("collectMetadata", findProperty("collectMetadata")?.toString() ?: "false")
-  systemProperty("collectSpans", true)
 }