Instrumentation metadata - "features" (#14816)

Author: jaydeluca

docs/contributing/documenting-instrumentation.md

@@ -88,6 +88,9 @@ semantic_conventions:
   - HTTP_CLIENT_SPANS
   - DATABASE_CLIENT_SPANS
   - JVM_RUNTIME_METRICS
+features:
+  - HTTP_ROUTE
+  - CONTEXT_PROPAGATION
 disabled_by_default: true
 classification: library
 library_link: https://github.com/...
@@ -174,6 +177,20 @@ List of possible options:
 * [GENAI_CLIENT_SPANS](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/gen-ai-spans.md)
 * [GENAI_CLIENT_METRICS](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/gen-ai-metrics.md#generative-ai-client-metrics)
 
+### Features (optional)
+
+As a way to help further categorize instrumentations, you can add a `features` field with a list of
+the relevant functionality descriptions.
+
+List of possible options:
+
+* `HTTP_ROUTE`: Instrumentation that enriches HTTP spans with route information
+* `EXPERIMENTAL_ONLY`: Instrumentation that is experimental and may not be stable
+* `CONTEXT_PROPAGATION`: Instrumentation that provides context propagation capabilities
+* `AUTO_INSTRUMENTATION_SHIM`: Instrumentation that adapts or bridges instrumentation from upstream libraries or frameworks
+* `CONTROLLER_SPANS`: Instrumentation that generates controller-level spans
+* `VIEW_SPANS`: Instrumentation that generates view-level spans
+
 ### Library Link
 
 For library instrumentations, include a `library_link` field with a URL to the library or framework's

docs/instrumentation-list.yaml

@@ -70,6 +70,8 @@ libraries:
     description: This instrumentation provides context propagation for Akka actors,
       it does not emit any telemetry on its own.
     library_link: https://doc.akka.io/libraries/akka-core/current/typed/index.html
+    features:
+    - CONTEXT_PROPAGATION
     source_path: instrumentation/akka/akka-actor-2.3
     scope:
       name: io.opentelemetry.akka-actor-2.3
@@ -83,6 +85,8 @@ libraries:
     description: This instrumentation provides context propagation for the Akka Fork-Join
       Pool, it does not emit any telemetry on its own.
     library_link: https://doc.akka.io/libraries/akka-core/current/typed/index.html
+    features:
+    - CONTEXT_PROPAGATION
     source_path: instrumentation/akka/akka-actor-fork-join-2.5
     scope:
       name: io.opentelemetry.akka-actor-fork-join-2.5
@@ -101,6 +105,8 @@ libraries:
     - HTTP_SERVER_SPANS
     - HTTP_SERVER_METRICS
     library_link: https://doc.akka.io/docs/akka-http/current/index.html
+    features:
+    - HTTP_ROUTE
     source_path: instrumentation/akka/akka-http-10.0
     scope:
       name: io.opentelemetry.akka-http-10.0

instrumentation-docs/instrumentations.sh

@@ -14,13 +14,12 @@ readonly INSTRUMENTATIONS=(
   "apache-dbcp-2.0:javaagent:test"
   "apache-dbcp-2.0:javaagent:testStableSemconv"
   "apache-dubbo-2.7:javaagent:testDubbo"
-  "apache-dubbo-2.7:javaagent:testDubbo"
   "apache-httpasyncclient-4.1:javaagent:test"
   "apache-httpclient:apache-httpclient-2.0:javaagent:test"
   "apache-httpclient:apache-httpclient-4.0:javaagent:test"
-  #  "apache-httpclient:apache-httpclient-4.3:library:test"  # See https://github.com/open-telemetry/opentelemetry-java-instrumentation/issues/14771
+  "apache-httpclient:apache-httpclient-4.3:library:test"
   "apache-httpclient:apache-httpclient-5.0:javaagent:test"
-  #  "apache-httpclient:apache-httpclient-5.2:library:test"  # See https://github.com/open-telemetry/opentelemetry-java-instrumentation/issues/14771
+  "apache-httpclient:apache-httpclient-5.2:library:test"
   "armeria:armeria-1.3:javaagent:test"
   "armeria:armeria-grpc-1.14:javaagent:test"
   "async-http-client:async-http-client-1.9:javaagent:test"

instrumentation-docs/readme.md

@@ -134,6 +134,15 @@ public class SpringWebInstrumentationModule extends InstrumentationModule
     * FAAS_SERVER_SPANS
     * GENAI_CLIENT_SPANS
     * GENAI_CLIENT_METRIC
+* features
+  * The specific functionality that the instrumentation provides
+  * Options are:
+    * HTTP_ROUTE
+    * EXPERIMENTAL_ONLY
+    * CONTEXT_PROPAGATION
+    * AUTO_INSTRUMENTATION_SHIM
+    * CONTROLLER_SPANS
+    * VIEW_SPANS
 * library_link
   * URL to the library or framework's main website or documentation, or if those don't exist, the
   GitHub repository.
@@ -173,6 +182,9 @@ semantic_conventions:                             # List of semantic conventions
   - HTTP_CLIENT_SPANS
   - DATABASE_CLIENT_SPANS
   - JVM_RUNTIME_METRICS
+features:                                        # List of features this instrumentation provides
+  - HTTP_ROUTE
+  - CONTEXT_PROPAGATION
 disabled_by_default: true                         # Defaults to `false`
 classification: internal                          # instrumentation classification: library | internal | custom
 library_link: https://...                         # URL to the library or framework's main website or documentation

instrumentation-docs/src/main/java/io/opentelemetry/instrumentation/docs/internal/InstrumentationFeature.java

@@ -0,0 +1,19 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.docs.internal;
+
+/**
+ * Represents functionality of instrumentations. This class is internal and is hence not for public
+ * use. Its APIs are unstable and can change at any time.
+ */
+public enum InstrumentationFeature {
+  HTTP_ROUTE,
+  EXPERIMENTAL_ONLY,
+  CONTEXT_PROPAGATION,
+  AUTO_INSTRUMENTATION_SHIM,
+  CONTROLLER_SPANS,
+  VIEW_SPANS,
+}

instrumentation-docs/src/main/java/io/opentelemetry/instrumentation/docs/internal/InstrumentationMetadata.java

@@ -47,6 +47,8 @@ public class InstrumentationMetadata {
   @Nullable
   private Boolean overrideTelemetry;
 
+  private List<InstrumentationFeature> features = emptyList();
+
   public InstrumentationMetadata() {
     this.classification = InstrumentationClassification.LIBRARY.name();
   }
@@ -147,6 +149,14 @@ public void setOverrideTelemetry(@Nullable Boolean overrideTelemetry) {
     this.overrideTelemetry = overrideTelemetry;
   }
 
+  public List<InstrumentationFeature> getFeatures() {
+    return features;
+  }
+
+  public void setFeatures(@Nullable List<InstrumentationFeature> features) {
+    this.features = Objects.requireNonNullElse(features, emptyList());
+  }
+
   /**
    * This class is internal and is hence not for public use. Its APIs are unstable and can change at
    * any time.
@@ -162,6 +172,7 @@ public static class Builder {
     private List<SemanticConvention> semanticConventions = emptyList();
     private List<ManualTelemetryEntry> additionalTelemetry = emptyList();
     @Nullable private Boolean overrideTelemetry;
+    private List<InstrumentationFeature> features = emptyList();
 
     @CanIgnoreReturnValue
     public Builder description(@Nullable String description) {
@@ -217,6 +228,12 @@ public Builder overrideTelemetry(@Nullable Boolean overrideTelemetry) {
       return this;
     }
 
+    @CanIgnoreReturnValue
+    public Builder features(@Nullable List<InstrumentationFeature> features) {
+      this.features = Objects.requireNonNullElse(features, emptyList());
+      return this;
+    }
+
     public InstrumentationMetadata build() {
       InstrumentationMetadata metadata =
           new InstrumentationMetadata(
@@ -231,6 +248,7 @@ public InstrumentationMetadata build() {
               configurations);
       metadata.setAdditionalTelemetry(additionalTelemetry);
       metadata.setOverrideTelemetry(overrideTelemetry);
+      metadata.setFeatures(features);
       return metadata;
     }
   }

instrumentation-docs/src/main/java/io/opentelemetry/instrumentation/docs/utils/YamlHelper.java

@@ -215,6 +215,13 @@ private static void addMetadataProperties(
       if (module.getMetadata().getDisabledByDefault()) {
         moduleMap.put("disabled_by_default", module.getMetadata().getDisabledByDefault());
       }
+      if (!module.getMetadata().getFeatures().isEmpty()) {
+        List<String> functionNames =
+            module.getMetadata().getFeatures().stream()
+                .map(Enum::name)
+                .collect(Collectors.toList());
+        moduleMap.put("features", functionNames);
+      }
     }
   }
 

instrumentation-docs/src/test/java/io/opentelemetry/instrumentation/docs/utils/YamlHelperTest.java

@@ -16,6 +16,7 @@
 import io.opentelemetry.instrumentation.docs.internal.EmittedMetrics;
 import io.opentelemetry.instrumentation.docs.internal.EmittedSpans;
 import io.opentelemetry.instrumentation.docs.internal.InstrumentationClassification;
+import io.opentelemetry.instrumentation.docs.internal.InstrumentationFeature;
 import io.opentelemetry.instrumentation.docs.internal.InstrumentationMetadata;
 import io.opentelemetry.instrumentation.docs.internal.InstrumentationModule;
 import io.opentelemetry.instrumentation.docs.internal.InstrumentationType;
@@ -122,6 +123,10 @@ void testGenerateInstrumentationYamlSeparatesClassifications() throws Exception
             .description("Spring Web 6.0 instrumentation")
             .classification(InstrumentationClassification.LIBRARY.name())
             .disabledByDefault(false)
+            .features(
+                List.of(
+                    InstrumentationFeature.HTTP_ROUTE, InstrumentationFeature.CONTEXT_PROPAGATION))
+            .semanticConventions(List.of(DATABASE_CLIENT_METRICS, DATABASE_CLIENT_SPANS))
             .configurations(
                 List.of(
                     new ConfigurationOption(
@@ -189,6 +194,12 @@ void testGenerateInstrumentationYamlSeparatesClassifications() throws Exception
               spring:
               - name: spring-web-6.0
                 description: Spring Web 6.0 instrumentation
+                semantic_conventions:
+                - DATABASE_CLIENT_METRICS
+                - DATABASE_CLIENT_SPANS
+                features:
+                - HTTP_ROUTE
+                - CONTEXT_PROPAGATION
                 source_path: instrumentation/spring/spring-web/spring-web-6.0
                 minimum_java_version: 11
                 scope:
@@ -227,6 +238,9 @@ void testMetadataParser() throws JsonProcessingException {
             classification: internal
             disabled_by_default: true
             library_link: https://example.com/test-library
+            features:
+              - HTTP_ROUTE
+              - CONTROLLER_SPANS
             configurations:
               - name: otel.instrumentation.common.db-statement-sanitizer.enabled
                 description: Enables statement sanitization for database queries.
@@ -243,6 +257,10 @@ void testMetadataParser() throws JsonProcessingException {
         .isEqualTo("Enables statement sanitization for database queries.");
     assertThat(config.defaultValue()).isEqualTo("true");
 
+    assertThat(metadata.getFeatures())
+        .containsExactly(
+            InstrumentationFeature.HTTP_ROUTE, InstrumentationFeature.CONTROLLER_SPANS);
+
     assertThat(metadata.getClassification()).isEqualTo(InstrumentationClassification.INTERNAL);
     assertThat(metadata.getDescription()).isEqualTo("test description");
     assertThat(metadata.getDisabledByDefault()).isEqualTo(true);
@@ -315,6 +333,21 @@ void testMetadataParserWithOnlyConfigurations() throws JsonProcessingException {
     assertThat(config.type()).isEqualTo(ConfigurationType.BOOLEAN);
   }
 
+  @Test
+  void testMetadataParserWithOnlyFeatures() throws JsonProcessingException {
+    String input =
+        """
+            features:
+              - HTTP_ROUTE
+        """;
+    InstrumentationMetadata metadata = YamlHelper.metaDataParser(input);
+
+    assertThat(metadata.getClassification()).isEqualTo(InstrumentationClassification.LIBRARY);
+    assertThat(metadata.getDescription()).isNull();
+    assertThat(metadata.getDisabledByDefault()).isFalse();
+    assertThat(metadata.getFeatures()).containsExactly(InstrumentationFeature.HTTP_ROUTE);
+  }
+
   @Test
   void testMetricsParsing() throws Exception {
     List<InstrumentationModule> modules = new ArrayList<>();

instrumentation/akka/akka-actor-2.3/metadata.yaml

@@ -1,3 +1,5 @@
 display_name: Akka Actors
 description: This instrumentation provides context propagation for Akka actors, it does not emit any telemetry on its own.
 library_link: https://doc.akka.io/libraries/akka-core/current/typed/index.html
+features:
+  - CONTEXT_PROPAGATION

instrumentation/akka/akka-actor-fork-join-2.5/metadata.yaml

@@ -1,3 +1,5 @@
 display_name: Akka Actors
 description: This instrumentation provides context propagation for the Akka Fork-Join Pool, it does not emit any telemetry on its own.
 library_link: https://doc.akka.io/libraries/akka-core/current/typed/index.html
+features:
+  - CONTEXT_PROPAGATION