Add support for library links in metadata

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
 

instrumentation-docs/readme.md

@@ -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/src/main/java/io/opentelemetry/instrumentation/docs/internal/InstrumentationMetaData.java

@@ -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/utils/YamlHelper.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/test/java/io/opentelemetry/instrumentation/docs/utils/YamlHelperTest.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/activej-http-6.0/metadata.yaml

@@ -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/akka/akka-actor-2.3/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-fork-join-2.5/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-http-10.0/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

instrumentation/alibaba-druid-1.0/metadata.yaml

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

instrumentation/apache-dbcp-2.0/metadata.yaml

@@ -5,3 +5,4 @@ description: >
   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.
+library_link: https://commons.apache.org/proper/commons-dbcp/

instrumentation/apache-dubbo-2.7/metadata.yaml

@@ -2,6 +2,7 @@ description: The Apache Dubbo instrumentation provides RPC client spans and RPC
   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.
+library_link: https://github.com/apache/dubbo/
 configurations:
   - name: otel.instrumentation.common.peer-service-mapping
     description: Used to specify a mapping from host names or IP addresses to peer services.

instrumentation/apache-httpasyncclient-4.1/metadata.yaml

@@ -1 +1,2 @@
 description: This instrumentation enables HTTP client spans and HTTP client metrics for the Apache HttpAsyncClient.
+library_link: https://hc.apache.org/index.html

instrumentation/apache-httpclient/apache-httpclient-2.0/metadata.yaml

@@ -1 +1,2 @@
 description: This instrumentation enables HTTP client spans and HTTP client metrics for versions 2 and 3 of the Apache HttpClient.
+library_link: https://hc.apache.org/index.html

instrumentation/apache-httpclient/apache-httpclient-4.0/metadata.yaml

@@ -1 +1,2 @@
 description: This instrumentation enables HTTP client spans and HTTP client metrics for version 4 of the Apache HttpClient.
+library_link: https://hc.apache.org/index.html

instrumentation/apache-httpclient/apache-httpclient-4.3/metadata.yaml

@@ -1 +1,2 @@
 description: This instrumentation provides a library integration that enables HTTP client spans and HTTP client metrics for the Apache HttpClient.
+library_link: https://hc.apache.org/index.html

instrumentation/apache-httpclient/apache-httpclient-5.0/metadata.yaml

@@ -1 +1,2 @@
 description: This instrumentation enables HTTP client spans and HTTP client metrics for version 5 of the Apache HttpClient.
+library_link: https://hc.apache.org/index.html

instrumentation/apache-httpclient/apache-httpclient-5.2/library/metadata.yaml

@@ -1 +1,2 @@
 description: This instrumentation enables CLIENT spans and metrics for the Apache HttpAsyncClient.
+library_link: https://hc.apache.org/index.html

instrumentation/apache-httpclient/apache-httpclient-5.2/metadata.yaml

@@ -1 +1,2 @@
 description: This instrumentation provides a library integration that enables HTTP client spans and HTTP client metrics for the Apache HttpClient.
+library_link: https://hc.apache.org/index.html

instrumentation/apache-shenyu-2.4/metadata.yaml

@@ -1,6 +1,7 @@
 description: >
   This instrumentation does not emit telemetry on its own. Instead, it augments existing HTTP server
   spans and HTTP server metrics with the HTTP route and Shenyu specific attributes.
+library_link: https://shenyu.apache.org/
 configurations:
   - name: otel.instrumentation.apache-shenyu.experimental-span-attributes
     description: > 

instrumentation/armeria/armeria-1.3/metadata.yaml

@@ -1,3 +1,4 @@
 description: >
   This instrumentation enables HTTP client spans and metrics for the Armeria HTTP client, and HTTP
   server spans and metrics for the Armeria HTTP server.
+library_link: https://armeria.dev/

instrumentation/armeria/armeria-grpc-1.14/metadata.yaml

@@ -1,3 +1,4 @@
 description: >
   This instrumentation enables RPC client spans and metrics for the Armeria gRPC client, and RPC
   server spans and metrics for the Armeria gRPC server.
+library_link: https://armeria.dev/

instrumentation/async-http-client/async-http-client-1.9/metadata.yaml

@@ -1 +1,2 @@
 description: This instrumentation enables HTTP client spans and HTTP client metrics for version 1 of the AsyncHttpClient (AHC) HTTP client.
+library_link: https://github.com/AsyncHttpClient/async-http-client

instrumentation/async-http-client/async-http-client-2.0/metadata.yaml

@@ -1 +1,2 @@
 description: This instrumentation enables HTTP client spans and HTTP client metrics for version 2 of the AsyncHttpClient (AHC) HTTP client.
+library_link: https://github.com/AsyncHttpClient/async-http-client

instrumentation/avaje-jex-3.0/metadata.yaml

@@ -2,3 +2,4 @@ description: >
   This instrumentation does not emit telemetry on its own. Instead, it hooks into the Avaje Jex
   Context to extract the HTTP route and attach it to existing HTTP server spans and HTTP server
   metrics.
+library_link: https://avaje.io/jex/

instrumentation/aws-lambda/aws-lambda-core-1.0/metadata.yaml

@@ -8,6 +8,7 @@ description: >
   For custom wrappers when using library instrumentation, you can configure the `OTEL_INSTRUMENTATION_AWS_LAMBDA_HANDLER`
   environment variable to contain your lambda handler method (in the format `package.ClassName::methodName`) and use
   one of wrappers as your lambda `Handler`.
+library_link: https://docs.aws.amazon.com/lambda/latest/dg/java-handler.html
 configurations:
   - name: otel.instrumentation.aws-lambda.flush-timeout
     type: int

instrumentation/aws-lambda/aws-lambda-events-2.2/metadata.yaml

@@ -2,6 +2,7 @@ description: >
   This version of the library instrumentation is deprecated, please use the `aws-lambda-events-3.11`
   library instrumentation instead. This instrumentation builds on top of the `aws-lambda-core-1.0`
   instrumentation, expanding support to cover the Lambda library, including standard and custom event types.
+library_link: https://docs.aws.amazon.com/lambda/latest/dg/java-handler.html
 configurations:
   - name: otel.instrumentation.aws-lambda.flush-timeout
     type: int

instrumentation/aws-lambda/aws-lambda-events-3.11/metadata.yaml

@@ -1,6 +1,7 @@
 description: >
   This instrumentation builds on top of the `aws-lambda-core-1.0` instrumentation, expanding support
   to cover the Lambda library, including standard and custom event types.
+library_link: https://docs.aws.amazon.com/lambda/latest/dg/java-handler.html
 configurations:
   - name: otel.instrumentation.aws-lambda.flush-timeout
     type: int

instrumentation/aws-sdk/aws-sdk-1.11/metadata.yaml

@@ -2,6 +2,7 @@ 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.
+library_link: https://aws.amazon.com/sdk-for-java/
 configurations:
   - name: otel.instrumentation.aws-sdk.experimental-span-attributes
     description: >

instrumentation/aws-sdk/aws-sdk-2.2/metadata.yaml

@@ -2,6 +2,7 @@ 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.
+library_link: https://aws.amazon.com/sdk-for-java/
 configurations:
   - name: otel.instrumentation.messaging.experimental.receive-telemetry.enabled
     description: >

instrumentation/azure-core/azure-core-1.14/metadata.yaml

@@ -1 +1,2 @@
 description: This instrumentation enables context propagation for the Azure Core library, it does not emit any telemetry on its own.
+library_link: https://learn.microsoft.com/en-us/java/api/overview/azure/core-readme?view=azure-java-stable

instrumentation/azure-core/azure-core-1.19/metadata.yaml

@@ -1 +1,2 @@
 description: This instrumentation enables context propagation for the Azure Core library, it does not emit any telemetry on its own.
+library_link: https://learn.microsoft.com/en-us/java/api/overview/azure/core-readme?view=azure-java-stable

instrumentation/azure-core/azure-core-1.36/metadata.yaml

@@ -1 +1,2 @@
 description: This instrumentation enables context propagation for the Azure Core library, it does not emit any telemetry on its own.
+library_link: https://learn.microsoft.com/en-us/java/api/overview/azure/core-readme?view=azure-java-stable

instrumentation/c3p0-0.9/metadata.yaml

@@ -1 +1,2 @@
 description: The c3p0 instrumentation provides connection pool metrics for c3p0 data sources.
+library_link: https://github.com/swaldman/c3p0

instrumentation/camel-2.20/metadata.yaml

@@ -2,6 +2,7 @@ description: >
   This instrumentation enables tracing for Apache Camel 2.x applications by generating spans for
   each route execution. For Camel versions 3.5 and newer, users should instead use the native
   'camel-opentelemetry' component provided directly by the Camel project.
+library_link: https://camel.apache.org/
 configurations:
   - name: otel.instrumentation.camel.experimental-span-attributes
     description: >