Enable documenting semconv info in metadata (#14670)

Co-authored-by: Lauri Tulmin <[email protected]>

Author: jaydeluca

docs/contributing/documenting-instrumentation.md

@@ -84,6 +84,10 @@ Example:
 
 ```yaml
 description: "This instrumentation enables..."
+semantic_conventions:
+  - HTTP_CLIENT_SPANS
+  - DATABASE_CLIENT_SPANS
+  - JVM_RUNTIME_METRICS
 disabled_by_default: true
 classification: library
 library_link: https://github.com/...
@@ -128,6 +132,32 @@ Some notes when writing descriptions:
 * It is not usually necessary to include specific library or framework version numbers in the
   description, unless that context is significant in some way.
 
+
+### Semantic Conventions
+
+If the instrumentation adheres to one or more specific semantic conventions, include a
+`semantic_conventions` field with a list of the relevant semantic convention categories.
+
+List of possible options:
+
+* [HTTP_CLIENT_SPANS](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/http/http-spans.md#http-client)
+* [HTTP_CLIENT_METRICS](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/http/http-metrics.md#http-client)
+* [HTTP_SERVER_SPANS](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/http/http-spans.md#http-server)
+* [HTTP_SERVER_METRICS](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/http/http-metrics.md#http-server)
+* [RPC_CLIENT_SPANS](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/rpc/rpc-spans.md#client-attributes)
+* [RPC_CLIENT_METRICS](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/rpc/rpc-metrics.md#rpc-client)
+* [RPC_SERVER_SPANS](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/rpc/rpc-spans.md#server-attributes)
+* [RPC_SERVER_METRICS](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/rpc/rpc-metrics.md#rpc-server)
+* [MESSAGING_SPANS](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/messaging/messaging-spans.md)
+* [DATABASE_CLIENT_SPANS](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/database/database-spans.md)
+* [DATABASE_CLIENT_METRICS](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/database/database-metrics.md)
+* [DATABASE_POOL_METRICS](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/database/database-metrics.md)
+* [JVM_RUNTIME_METRICS](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/runtime/jvm-metrics.md)
+* [GRAPHQL_SERVER_SPANS](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/graphql/graphql-spans.md)
+* [FAAS_SERVER_SPANS](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/faas/faas-spans.md)
+* [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)
+
 ### Library Link
 
 For library instrumentations, include a `library_link` field with a URL to the library or framework's

docs/instrumentation-list.yaml

@@ -10,6 +10,9 @@ libraries:
     display_name: ActiveJ
     description: This instrumentation enables HTTP server spans and HTTP server metrics
       for the ActiveJ HTTP server.
+    semantic_conventions:
+    - HTTP_SERVER_SPANS
+    - HTTP_SERVER_METRICS
     library_link: https://activej.io/
     source_path: instrumentation/activej-http-6.0
     minimum_java_version: 17
@@ -92,6 +95,11 @@ libraries:
     display_name: Akka HTTP
     description: |
       This instrumentation enables HTTP client spans and metrics for the Akka HTTP client, and HTTP server spans and metrics for the Akka HTTP server.
+    semantic_conventions:
+    - HTTP_CLIENT_SPANS
+    - HTTP_CLIENT_METRICS
+    - HTTP_SERVER_SPANS
+    - HTTP_SERVER_METRICS
     library_link: https://doc.akka.io/docs/akka-http/current/index.html
     source_path: instrumentation/akka/akka-http-10.0
     scope:
@@ -181,6 +189,8 @@ libraries:
   - name: alibaba-druid-1.0
     description: |
       The Alibaba Druid instrumentation generates database connection pool metrics for druid data sources.
+    semantic_conventions:
+    - DATABASE_POOL_METRICS
     library_link: https://github.com/alibaba/druid
     source_path: instrumentation/alibaba-druid-1.0
     scope:
@@ -274,9 +284,12 @@ libraries:
           type: STRING
   apache:
   - name: apache-dbcp-2.0
+    display_name: Apache DBCP
     description: |
       This instrumentation enables database connection pools metrics for Apache DBCP.
       The instrumentation uses `MBeanRegistration` methods for lifecycle detection, therefore it only activates if the `BasicDataSource` is registered to an `MBeanServer`. If using Spring Boot, this happens automatically as all Spring beans that support JMX registration are automatically registered by default.
+    semantic_conventions:
+    - DATABASE_POOL_METRICS
     library_link: https://commons.apache.org/proper/commons-dbcp/
     source_path: instrumentation/apache-dbcp-2.0
     scope:
@@ -354,10 +367,14 @@ libraries:
         - name: db.client.connection.pool.name
           type: STRING
   - name: apache-dubbo-2.7
+    display_name: Apache Dubbo
     description: The Apache Dubbo instrumentation provides RPC client spans and RPC
       server spans for Apache Dubbo RPC calls. Each call produces a span named after
       the Dubbo method, enriched with standard RPC attributes (system, service, method),
       network attributes, and error details if an exception occurs.
+    semantic_conventions:
+    - RPC_CLIENT_SPANS
+    - RPC_SERVER_SPANS
     library_link: https://github.com/apache/dubbo/
     source_path: instrumentation/apache-dubbo-2.7
     scope:
@@ -399,8 +416,12 @@ libraries:
         - name: rpc.system
           type: STRING
   - name: apache-httpasyncclient-4.1
+    display_name: Apache HttpAsyncClient
     description: This instrumentation enables HTTP client spans and HTTP client metrics
       for the Apache HttpAsyncClient.
+    semantic_conventions:
+    - HTTP_CLIENT_SPANS
+    - HTTP_CLIENT_METRICS
     library_link: https://hc.apache.org/index.html
     source_path: instrumentation/apache-httpasyncclient-4.1
     scope:
@@ -446,8 +467,12 @@ libraries:
         - name: url.full
           type: STRING
   - name: apache-httpclient-2.0
+    display_name: Apache HttpClient
     description: This instrumentation enables HTTP client spans and HTTP client metrics
       for versions 2 and 3 of the Apache HttpClient.
+    semantic_conventions:
+    - HTTP_CLIENT_SPANS
+    - HTTP_CLIENT_METRICS
     library_link: https://hc.apache.org/index.html
     source_path: instrumentation/apache-httpclient/apache-httpclient-2.0
     scope:
@@ -491,8 +516,12 @@ libraries:
         - name: url.full
           type: STRING
   - name: apache-httpclient-4.0
+    display_name: Apache HttpClient
     description: This instrumentation enables HTTP client spans and HTTP client metrics
       for version 4 of the Apache HttpClient.
+    semantic_conventions:
+    - HTTP_CLIENT_SPANS
+    - HTTP_CLIENT_METRICS
     library_link: https://hc.apache.org/index.html
     source_path: instrumentation/apache-httpclient/apache-httpclient-4.0
     scope:
@@ -539,8 +568,12 @@ libraries:
         - name: url.full
           type: STRING
   - name: apache-httpclient-4.3
+    display_name: Apache HttpClient
     description: This instrumentation provides a library integration that enables
       HTTP client spans and HTTP client metrics for the Apache HttpClient.
+    semantic_conventions:
+    - HTTP_CLIENT_SPANS
+    - HTTP_CLIENT_METRICS
     library_link: https://hc.apache.org/index.html
     source_path: instrumentation/apache-httpclient/apache-httpclient-4.3
     scope:
@@ -588,8 +621,12 @@ libraries:
         - name: url.full
           type: STRING
   - name: apache-httpclient-5.0
+    display_name: Apache HttpClient
     description: This instrumentation enables HTTP client spans and HTTP client metrics
       for version 5 of the Apache HttpClient.
+    semantic_conventions:
+    - HTTP_CLIENT_SPANS
+    - HTTP_CLIENT_METRICS
     library_link: https://hc.apache.org/index.html
     source_path: instrumentation/apache-httpclient/apache-httpclient-5.0
     scope:
@@ -635,8 +672,12 @@ libraries:
         - name: url.full
           type: STRING
   - name: apache-httpclient-5.2
+    display_name: Apache HttpClient
     description: This instrumentation provides a library integration that enables
       HTTP client spans and HTTP client metrics for the Apache HttpClient.
+    semantic_conventions:
+    - HTTP_CLIENT_SPANS
+    - HTTP_CLIENT_METRICS
     library_link: https://hc.apache.org/index.html
     source_path: instrumentation/apache-httpclient/apache-httpclient-5.2
     scope:

instrumentation-docs/readme.md

@@ -114,6 +114,26 @@ public class SpringWebInstrumentationModule extends InstrumentationModule
 * name
   * Identifier for instrumentation module, used to enable/disable
   * Configured in `InstrumentationModule` code for each module
+* semantic_conventions
+  * The semantic conventions that the instrumentation module adheres to
+  * Options are:
+    * HTTP_CLIENT_SPANS
+    * HTTP_CLIENT_METRICS
+    * HTTP_SERVER_SPANS
+    * HTTP_SERVER_METRICS
+    * RPC_CLIENT_SPANS
+    * RPC_CLIENT_METRICS
+    * RPC_SERVER_SPANS
+    * RPC_SERVER_METRICS
+    * MESSAGING_SPANS
+    * DATABASE_CLIENT_SPANS
+    * DATABASE_CLIENT_METRICS
+    * DATABASE_POOL_METRICS
+    * JVM_RUNTIME_METRICS
+    * GRAPHQL_SERVER_SPANS
+    * FAAS_SERVER_SPANS
+    * GENAI_CLIENT_SPANS
+    * GENAI_CLIENT_METRIC
 * library_link
   * URL to the library or framework's main website or documentation, or if those don't exist, the
   GitHub repository.
@@ -149,6 +169,10 @@ As of now, the following fields are supported, all of which are optional:
 
 ```yaml
 description: "This instrumentation enables..."    # Description of the instrumentation module
+semantic_conventions:                             # List of semantic conventions the instrumentation adheres to
+  - HTTP_CLIENT_SPANS
+  - DATABASE_CLIENT_SPANS
+  - JVM_RUNTIME_METRICS
 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/InstrumentationMetadata.java

@@ -37,6 +37,9 @@ public class InstrumentationMetadata {
 
   private List<ConfigurationOption> configurations = emptyList();
 
+  @JsonProperty("semantic_conventions")
+  private List<SemanticConvention> semanticConventions = emptyList();
+
   public InstrumentationMetadata() {
     this.classification = InstrumentationClassification.LIBRARY.name();
   }
@@ -47,12 +50,14 @@ public InstrumentationMetadata(
       String classification,
       @Nullable String libraryLink,
       @Nullable String displayName,
+      @Nullable List<SemanticConvention> semanticConventions,
       @Nullable List<ConfigurationOption> configurations) {
     this.classification = classification;
     this.disabledByDefault = disabledByDefault;
     this.description = description;
     this.libraryLink = libraryLink;
     this.displayName = displayName;
+    this.semanticConventions = Objects.requireNonNullElse(semanticConventions, emptyList());
     this.configurations = Objects.requireNonNullElse(configurations, emptyList());
   }
 
@@ -101,6 +106,14 @@ public void setConfigurations(@Nullable List<ConfigurationOption> configurations
     this.configurations = Objects.requireNonNullElse(configurations, emptyList());
   }
 
+  public List<SemanticConvention> getSemanticConventions() {
+    return semanticConventions;
+  }
+
+  public void setSemanticConventions(@Nullable List<SemanticConvention> semanticConventions) {
+    this.semanticConventions = Objects.requireNonNullElse(semanticConventions, emptyList());
+  }
+
   @Nullable
   public String getLibraryLink() {
     return libraryLink;
@@ -122,6 +135,7 @@ public static class Builder {
     @Nullable private String libraryLink;
     @Nullable private String displayName;
     private List<ConfigurationOption> configurations = emptyList();
+    private List<SemanticConvention> semanticConventions = emptyList();
 
     @CanIgnoreReturnValue
     public Builder description(@Nullable String description) {
@@ -159,13 +173,20 @@ public Builder configurations(@Nullable List<ConfigurationOption> configurations
       return this;
     }
 
+    @CanIgnoreReturnValue
+    public Builder semanticConventions(@Nullable List<SemanticConvention> semanticConventions) {
+      this.semanticConventions = Objects.requireNonNullElse(semanticConventions, emptyList());
+      return this;
+    }
+
     public InstrumentationMetadata build() {
       return new InstrumentationMetadata(
           description,
           disabledByDefault,
           classification != null ? classification : InstrumentationClassification.LIBRARY.name(),
           libraryLink,
           displayName,
+          semanticConventions,
           configurations);
     }
   }

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

@@ -0,0 +1,30 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.docs.internal;
+
+/**
+ * Represents the data in a metadata.yaml file. This class is internal and is hence not for public
+ * use. Its APIs are unstable and can change at any time.
+ */
+public enum SemanticConvention {
+  HTTP_CLIENT_SPANS,
+  HTTP_CLIENT_METRICS,
+  HTTP_SERVER_SPANS,
+  HTTP_SERVER_METRICS,
+  RPC_CLIENT_SPANS,
+  RPC_CLIENT_METRICS,
+  RPC_SERVER_SPANS,
+  RPC_SERVER_METRICS,
+  MESSAGING_SPANS,
+  DATABASE_CLIENT_SPANS,
+  DATABASE_CLIENT_METRICS,
+  DATABASE_POOL_METRICS,
+  JVM_RUNTIME_METRICS,
+  GRAPHQL_SERVER_SPANS,
+  FAAS_SERVER_SPANS,
+  GENAI_CLIENT_SPANS,
+  GENAI_CLIENT_METRICS
+}

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

@@ -201,6 +201,14 @@ private static void addMetadataProperties(
       if (module.getMetadata().getDescription() != null) {
         moduleMap.put("description", module.getMetadata().getDescription());
       }
+      if (module.getMetadata().getSemanticConventions() != null
+          && !module.getMetadata().getSemanticConventions().isEmpty()) {
+        List<String> conventionNames =
+            module.getMetadata().getSemanticConventions().stream()
+                .map(Enum::name)
+                .collect(Collectors.toList());
+        moduleMap.put("semantic_conventions", conventionNames);
+      }
       if (module.getMetadata().getLibraryLink() != null) {
         moduleMap.put("library_link", module.getMetadata().getLibraryLink());
       }

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

@@ -5,6 +5,8 @@
 
 package io.opentelemetry.instrumentation.docs.utils;
 
+import static io.opentelemetry.instrumentation.docs.internal.SemanticConvention.DATABASE_CLIENT_METRICS;
+import static io.opentelemetry.instrumentation.docs.internal.SemanticConvention.DATABASE_CLIENT_SPANS;
 import static java.util.Collections.emptyList;
 import static org.assertj.core.api.Assertions.assertThat;
 
@@ -44,6 +46,7 @@ void testPrintInstrumentationList() throws Exception {
             .displayName("Spring Web")
             .classification(InstrumentationClassification.LIBRARY.name())
             .disabledByDefault(true)
+            .semanticConventions(List.of(DATABASE_CLIENT_METRICS, DATABASE_CLIENT_SPANS))
             .build();
 
     modules.add(
@@ -84,6 +87,9 @@ void testPrintInstrumentationList() throws Exception {
               - name: spring-web-6.0
                 display_name: Spring Web
                 description: Spring Web 6.0 instrumentation
+                semantic_conventions:
+                - DATABASE_CLIENT_METRICS
+                - DATABASE_CLIENT_SPANS
                 disabled_by_default: true
                 source_path: instrumentation/spring/spring-web/spring-web-6.0
                 minimum_java_version: 11

instrumentation/activej-http-6.0/metadata.yaml

@@ -1,3 +1,6 @@
 display_name: ActiveJ
 description: This instrumentation enables HTTP server spans and HTTP server metrics for the ActiveJ HTTP server.
 library_link: https://activej.io/
+semantic_conventions:
+  - HTTP_SERVER_SPANS
+  - HTTP_SERVER_METRICS

instrumentation/akka/akka-http-10.0/metadata.yaml

@@ -3,3 +3,8 @@ description: >
   This instrumentation enables HTTP client spans and metrics for the Akka HTTP client, and HTTP
   server spans and metrics for the Akka HTTP server.
 library_link: https://doc.akka.io/docs/akka-http/current/index.html
+semantic_conventions:
+  - HTTP_CLIENT_SPANS
+  - HTTP_CLIENT_METRICS
+  - HTTP_SERVER_SPANS
+  - HTTP_SERVER_METRICS

instrumentation/alibaba-druid-1.0/metadata.yaml

@@ -2,3 +2,5 @@ description: >
   The Alibaba Druid instrumentation generates database connection pool metrics for druid data
   sources.
 library_link: https://github.com/alibaba/druid
+semantic_conventions:
+  - DATABASE_POOL_METRICS