Add scope name to metadata (#13531)

Author: jaydeluca

docs/instrumentation-list.yaml

@@ -8,6 +8,7 @@ otelJava {
 
 dependencies {
   implementation("org.yaml:snakeyaml:2.4")
+  implementation("io.opentelemetry:opentelemetry-sdk-common")
 
   testImplementation(enforcedPlatform("org.junit:junit-bom:5.12.1"))
   testImplementation("org.assertj:assertj-core:3.27.3")

instrumentation-docs/build.gradle.kts

@@ -2,6 +2,12 @@
 
 Runs analysis on instrumentation modules in order to generate documentation.
 
+## How to use
+
+Run the doc generator:
+
+`./gradlew :instrumentation-docs:generateDocs`
+
 ## Instrumentation Hierarchy
 
 An "InstrumentationEntity" represents a module that that targets specific code in a framework/library/technology.
@@ -46,10 +52,15 @@ public class SpringWebInstrumentationModule extends InstrumentationModule
   * Configured in `InstrumentationModule` code for each module
 * srcPath
   * Path to the source code of the instrumentation module
+* minimumJavaVersion
+  * Minimum Java version required by the instrumentation module. If not specified, it is assumed to
+    be Java 8
 * description
   * Short description of what the instrumentation does
 * target_versions
   * List of supported versions by the module, broken down by `library` or `javaagent` support
+* scope
+  * Name: The scope name of the instrumentation, `io.opentelemetry.{instrumentation name}`
 
 ## Methodology
 
@@ -62,12 +73,25 @@ As of now, the following fields are supported:
 
 ```yaml
 description: "Description of what the instrumentation does."
+
+# used to mark modules that do not instrument traditional libraries (e.g. methods, annotations)
+# defaults to true
+isLibraryInstrumentation: false
 ```
 
-### Versions targeted
+### Gradle File Derived Information
 
-We parse gradle files in order to determine the target versions.
+We parse gradle files in order to determine several pieces of metadata:
 
 - Javaagent versions are determined by the `muzzle` plugin configurations
 - Library versions are determined by the library dependency versions
   - when available, latestDepTestLibrary is used to determine the latest supported version
+- Minimum Java version is determined by the `otelJava` configurations
+
+### Scope
+
+For now, the scope name is the only value that is implemented in our instrumentations. The scope
+name is determined by the instrumentation module name:  `io.opentelemetry.{instrumentation name}`
+
+We will implement gatherers for the schemaUrl and scope attributes when instrumentations start
+implementing them.

instrumentation-docs/readme.md

@@ -5,6 +5,7 @@
 
 package io.opentelemetry.instrumentation.docs;
 
+import io.opentelemetry.instrumentation.docs.internal.InstrumentationEntity;
 import io.opentelemetry.instrumentation.docs.utils.FileManager;
 import io.opentelemetry.instrumentation.docs.utils.YamlHelper;
 import java.io.BufferedWriter;
@@ -26,6 +27,10 @@ public static void main(String[] args) {
     try (BufferedWriter writer =
         Files.newBufferedWriter(
             Paths.get("docs/instrumentation-list.yaml"), Charset.defaultCharset())) {
+      writer.write("# This file is generated and should not be manually edited.\n");
+      writer.write("# The structure and contents are a work in progress and subject to change.\n");
+      writer.write(
+          "# For more information see: https://github.com/open-telemetry/opentelemetry-java-instrumentation/issues/13468\n\n");
       YamlHelper.printInstrumentationList(entities, writer);
     } catch (IOException e) {
       logger.severe("Error writing instrumentation list: " + e.getMessage());

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

@@ -5,8 +5,11 @@
 
 package io.opentelemetry.instrumentation.docs;
 
-import static io.opentelemetry.instrumentation.docs.GradleParser.parseGradleFile;
+import static io.opentelemetry.instrumentation.docs.parsers.GradleParser.parseGradleFile;
 
+import io.opentelemetry.instrumentation.docs.internal.DependencyInfo;
+import io.opentelemetry.instrumentation.docs.internal.InstrumentationEntity;
+import io.opentelemetry.instrumentation.docs.internal.InstrumentationType;
 import io.opentelemetry.instrumentation.docs.utils.FileManager;
 import io.opentelemetry.instrumentation.docs.utils.InstrumentationPath;
 import io.opentelemetry.instrumentation.docs.utils.YamlHelper;
@@ -42,11 +45,12 @@ public static List<InstrumentationEntity> convertToEntities(List<Instrumentation
       if (!entityMap.containsKey(key)) {
         entityMap.put(
             key,
-            new InstrumentationEntity(
-                path.srcPath().replace("/javaagent", "").replace("/library", ""),
-                path.instrumentationName(),
-                path.namespace(),
-                path.group()));
+            new InstrumentationEntity.Builder()
+                .srcPath(path.srcPath().replace("/javaagent", "").replace("/library", ""))
+                .instrumentationName(path.instrumentationName())
+                .namespace(path.namespace())
+                .group(path.group())
+                .build());
       }
     }
 
@@ -80,15 +84,21 @@ void analyzeVersions(List<String> files, InstrumentationEntity entity) {
     Map<InstrumentationType, Set<String>> versions = new HashMap<>();
     for (String file : files) {
       String fileContents = fileSearch.readFileToString(file);
+      DependencyInfo results = null;
 
       if (file.contains("/javaagent/")) {
-        Set<String> results = parseGradleFile(fileContents, InstrumentationType.JAVAAGENT);
+        results = parseGradleFile(fileContents, InstrumentationType.JAVAAGENT);
         versions
             .computeIfAbsent(InstrumentationType.JAVAAGENT, k -> new HashSet<>())
-            .addAll(results);
+            .addAll(results.versions());
       } else if (file.contains("/library/")) {
-        Set<String> results = parseGradleFile(fileContents, InstrumentationType.LIBRARY);
-        versions.computeIfAbsent(InstrumentationType.LIBRARY, k -> new HashSet<>()).addAll(results);
+        results = parseGradleFile(fileContents, InstrumentationType.LIBRARY);
+        versions
+            .computeIfAbsent(InstrumentationType.LIBRARY, k -> new HashSet<>())
+            .addAll(results.versions());
+      }
+      if (results != null && results.minJavaVersionSupported() != null) {
+        entity.setMinJavaVersion(results.minJavaVersionSupported());
       }
     }
     entity.setTargetVersions(versions);

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

@@ -0,0 +1,14 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.docs.internal;
+
+import java.util.Set;
+
+/**
+ * This class is internal and is hence not for public use. Its APIs are unstable and can change at
+ * any time.
+ */
+public record DependencyInfo(Set<String> versions, Integer minJavaVersionSupported) {}