Add support for library links in metadata (#14622)

Author: jaydeluca

docs/contributing/documenting-instrumentation.md

@@ -80,6 +80,20 @@ Each instrumentation should have a `metadata.yaml` file in the root of the instr
 (`instrumentation/{some instrumentation}/metadata.yaml`) that contains structured metadata about the
 instrumentation.
 
+Example:
+
+```yaml
+description: "This instrumentation enables..."
+disabled_by_default: true
+classification: library
+library_link: https://github.com/...
+configurations:
+  - name: otel.instrumentation.common.db-statement-sanitizer.enabled
+    description: Enables statement sanitization for database queries.
+    type: boolean
+    default: true
+```
+
 ### Description (required)
 
 At a minimum, every instrumentation metadata file should include a `description`.
@@ -114,6 +128,10 @@ 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.
 
+### Library Link
+
+For library instrumentations, include a `library_link` field with a URL to the library or framework's
+main website or documentation, or if those don't exist, the GitHub repository.
 
 ### Configurations
 

docs/instrumentation-list.yaml

@@ -114,6 +114,9 @@ public class SpringWebInstrumentationModule extends InstrumentationModule
 * name
   * Identifier for instrumentation module, used to enable/disable
   * Configured in `InstrumentationModule` code for each module
+* library_link
+  * URL to the library or framework's main website or documentation, or if those don't exist, the
+  GitHub repository.
 * source_path
   * Path to the source code of the instrumentation module
 * minimum_java_version
@@ -145,9 +148,10 @@ additional information about the instrumentation module.
 As of now, the following fields are supported, all of which are optional:
 
 ```yaml
-description: "Instruments..."   # Description of the instrumentation module
-disabled_by_default: true       # Defaults to `false`
-classification: internal        # instrumentation classification: library | internal | custom
+description: "This instrumentation enables..."    # Description of the instrumentation module
+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
 configurations:
   - name: otel.instrumentation.common.db-statement-sanitizer.enabled
     description: Enables statement sanitization for database queries.

instrumentation-docs/readme.md

@@ -25,6 +25,10 @@ public class InstrumentationMetaData {
 
   private String classification;
 
+  @JsonProperty("library_link")
+  @Nullable
+  private String libraryLink;
+
   private List<ConfigurationOption> configurations = Collections.emptyList();
 
   public InstrumentationMetaData() {
@@ -35,10 +39,12 @@ public InstrumentationMetaData(
       @Nullable String description,
       String classification,
       @Nullable Boolean disabledByDefault,
+      @Nullable String libraryLink,
       @Nullable List<ConfigurationOption> configurations) {
     this.classification = classification;
     this.disabledByDefault = disabledByDefault;
     this.description = description;
+    this.libraryLink = libraryLink;
     this.configurations = Objects.requireNonNullElse(configurations, Collections.emptyList());
   }
 
@@ -77,4 +83,13 @@ public List<ConfigurationOption> getConfigurations() {
   public void setConfigurations(@Nullable List<ConfigurationOption> configurations) {
     this.configurations = Objects.requireNonNullElse(configurations, Collections.emptyList());
   }
+
+  @Nullable
+  public String getLibraryLink() {
+    return libraryLink;
+  }
+
+  public void setLibraryLink(@Nullable String libraryLink) {
+    this.libraryLink = libraryLink;
+  }
 }

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

@@ -198,6 +198,9 @@ private static void addMetadataProperties(
       if (module.getMetadata().getDescription() != null) {
         moduleMap.put("description", module.getMetadata().getDescription());
       }
+      if (module.getMetadata().getLibraryLink() != null) {
+        moduleMap.put("library_link", module.getMetadata().getLibraryLink());
+      }
       if (module.getMetadata().getDisabledByDefault()) {
         moduleMap.put("disabled_by_default", module.getMetadata().getDisabledByDefault());
       }

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

@@ -43,6 +43,7 @@ void testPrintInstrumentationList() throws Exception {
             "Spring Web 6.0 instrumentation",
             InstrumentationClassification.LIBRARY.toString(),
             true,
+            null,
             null);
 
     modules.add(
@@ -114,6 +115,7 @@ void testGenerateInstrumentationYamlSeparatesClassifications() throws Exception
             "Spring Web 6.0 instrumentation",
             InstrumentationClassification.LIBRARY.toString(),
             false,
+            null,
             List.of(
                 new ConfigurationOption(
                     "otel.instrumentation.spring-web-6.0.enabled",
@@ -134,7 +136,7 @@ void testGenerateInstrumentationYamlSeparatesClassifications() throws Exception
 
     InstrumentationMetaData internalMetadata =
         new InstrumentationMetaData(
-            null, InstrumentationClassification.INTERNAL.toString(), null, null);
+            null, InstrumentationClassification.INTERNAL.toString(), null, null, null);
 
     modules.add(
         new InstrumentationModule.Builder()
@@ -148,7 +150,7 @@ void testGenerateInstrumentationYamlSeparatesClassifications() throws Exception
 
     InstrumentationMetaData customMetadata =
         new InstrumentationMetaData(
-            null, InstrumentationClassification.CUSTOM.toString(), null, null);
+            null, InstrumentationClassification.CUSTOM.toString(), null, null, null);
 
     Map<InstrumentationType, Set<String>> externalAnnotationsVersions =
         Map.of(
@@ -214,6 +216,7 @@ void testMetadataParser() throws JsonProcessingException {
             description: test description
             classification: internal
             disabled_by_default: true
+            library_link: https://example.com/test-library
             configurations:
               - name: otel.instrumentation.common.db-statement-sanitizer.enabled
                 description: Enables statement sanitization for database queries.
@@ -233,6 +236,7 @@ void testMetadataParser() throws JsonProcessingException {
     assertThat(metadata.getClassification()).isEqualTo(InstrumentationClassification.INTERNAL);
     assertThat(metadata.getDescription()).isEqualTo("test description");
     assertThat(metadata.getDisabledByDefault()).isEqualTo(true);
+    assertThat(metadata.getLibraryLink()).isEqualTo("https://example.com/test-library");
   }
 
   @Test
@@ -241,6 +245,18 @@ void testMetadataParserWithOnlyLibraryEntry() throws JsonProcessingException {
     InstrumentationMetaData metadata = YamlHelper.metaDataParser(input);
     assertThat(metadata.getClassification()).isEqualTo(InstrumentationClassification.INTERNAL);
     assertThat(metadata.getDescription()).isNull();
+    assertThat(metadata.getLibraryLink()).isNull();
+    assertThat(metadata.getDisabledByDefault()).isFalse();
+    assertThat(metadata.getConfigurations()).isEmpty();
+  }
+
+  @Test
+  void testMetadataParserWithOnlyLibraryLink() throws JsonProcessingException {
+    String input = "library_link: https://example.com/only-link";
+    InstrumentationMetaData metadata = YamlHelper.metaDataParser(input);
+    assertThat(metadata.getClassification()).isEqualTo(InstrumentationClassification.LIBRARY);
+    assertThat(metadata.getDescription()).isNull();
+    assertThat(metadata.getLibraryLink()).isEqualTo("https://example.com/only-link");
     assertThat(metadata.getDisabledByDefault()).isFalse();
     assertThat(metadata.getConfigurations()).isEmpty();
   }
@@ -485,4 +501,80 @@ void testTelemetryGroupsAreSorted() throws Exception {
 
     assertThat(yaml1).isEqualTo(yaml2);
   }
+
+  @Test
+  void testYamlGenerationWithLibraryLink() throws Exception {
+    List<InstrumentationModule> modules = new ArrayList<>();
+    Map<InstrumentationType, Set<String>> targetVersions = new HashMap<>();
+    targetVersions.put(
+        InstrumentationType.JAVAAGENT, new HashSet<>(List.of("com.example:test-library:[1.0.0,)")));
+
+    InstrumentationMetaData metadataWithLink =
+        new InstrumentationMetaData(
+            "Test library instrumentation with link",
+            InstrumentationClassification.LIBRARY.toString(),
+            false,
+            "https://example.com/test-library-docs",
+            emptyList());
+
+    modules.add(
+        new InstrumentationModule.Builder()
+            .srcPath("instrumentation/test-lib/test-lib-1.0")
+            .instrumentationName("test-lib-1.0")
+            .namespace("test-lib")
+            .group("test-lib")
+            .targetVersions(targetVersions)
+            .metadata(metadataWithLink)
+            .build());
+
+    InstrumentationMetaData metadataWithoutLink =
+        new InstrumentationMetaData(
+            "Test library instrumentation without link",
+            InstrumentationClassification.LIBRARY.toString(),
+            false,
+            null,
+            emptyList());
+
+    modules.add(
+        new InstrumentationModule.Builder()
+            .srcPath("instrumentation/other-lib/other-lib-1.0")
+            .instrumentationName("other-lib-1.0")
+            .namespace("other-lib")
+            .group("other-lib")
+            .targetVersions(targetVersions)
+            .metadata(metadataWithoutLink)
+            .build());
+
+    StringWriter stringWriter = new StringWriter();
+    BufferedWriter writer = new BufferedWriter(stringWriter);
+
+    YamlHelper.generateInstrumentationYaml(modules, writer);
+    writer.flush();
+
+    String expectedYaml =
+        """
+            libraries:
+              other-lib:
+              - name: other-lib-1.0
+                description: Test library instrumentation without link
+                source_path: instrumentation/other-lib/other-lib-1.0
+                scope:
+                  name: io.opentelemetry.other-lib-1.0
+                target_versions:
+                  javaagent:
+                  - com.example:test-library:[1.0.0,)
+              test-lib:
+              - name: test-lib-1.0
+                description: Test library instrumentation with link
+                library_link: https://example.com/test-library-docs
+                source_path: instrumentation/test-lib/test-lib-1.0
+                scope:
+                  name: io.opentelemetry.test-lib-1.0
+                target_versions:
+                  javaagent:
+                  - com.example:test-library:[1.0.0,)
+            """;
+
+    assertThat(expectedYaml).isEqualTo(stringWriter.toString());
+  }
 }

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

@@ -1 +1,2 @@
 description: This instrumentation enables HTTP server spans and HTTP server metrics for the ActiveJ HTTP server.
+library_link: https://activej.io/

instrumentation/activej-http-6.0/metadata.yaml

@@ -1 +1,2 @@
 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

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

@@ -1 +1,2 @@
 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

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

@@ -1,3 +1,4 @@
 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