Rename InstrumentationEntity to InstrumentationModule

instrumentation-docs/readme.md

@@ -10,8 +10,8 @@ Run the doc generator:
 
 ## Instrumentation Hierarchy
 
-An "InstrumentationEntity" represents a module that that targets specific code in a
-framework/library/technology. Each entity will have a name, a namespace, and a group.
+An "InstrumentationModule" represents a module that that targets specific code in a
+framework/library/technology. Each module will have a name, a namespace, and a group.
 
 Using these structures as examples:
 

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

@@ -5,7 +5,7 @@
 
 package io.opentelemetry.instrumentation.docs;
 
-import io.opentelemetry.instrumentation.docs.internal.InstrumentationEntity;
+import io.opentelemetry.instrumentation.docs.internal.InstrumentationModule;
 import io.opentelemetry.instrumentation.docs.utils.FileManager;
 import io.opentelemetry.instrumentation.docs.utils.YamlHelper;
 import java.io.BufferedWriter;
@@ -22,7 +22,7 @@ public class DocGeneratorApplication {
 
   public static void main(String[] args) {
     FileManager fileManager = new FileManager("instrumentation/");
-    List<InstrumentationEntity> entities = new InstrumentationAnalyzer(fileManager).analyze();
+    List<InstrumentationModule> modules = new InstrumentationAnalyzer(fileManager).analyze();
 
     try (BufferedWriter writer =
         Files.newBufferedWriter(
@@ -31,7 +31,7 @@ public static void main(String[] args) {
       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.generateInstrumentationYaml(entities, writer);
+      YamlHelper.generateInstrumentationYaml(modules, writer);
     } catch (IOException e) {
       logger.severe("Error writing instrumentation list: " + e.getMessage());
     }

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

@@ -8,7 +8,7 @@
 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.InstrumentationModule;
 import io.opentelemetry.instrumentation.docs.internal.InstrumentationType;
 import io.opentelemetry.instrumentation.docs.utils.FileManager;
 import io.opentelemetry.instrumentation.docs.utils.InstrumentationPath;
@@ -29,20 +29,21 @@ class InstrumentationAnalyzer {
   }
 
   /**
-   * Converts a list of {@link InstrumentationPath} into a list of {@link InstrumentationEntity},
+   * Converts a list of {@link InstrumentationPath} into a list of {@link InstrumentationModule},
    *
    * @param paths the list of {@link InstrumentationPath} objects to be converted
-   * @return a list of {@link InstrumentationEntity} objects with aggregated types
+   * @return a list of {@link InstrumentationModule} objects with aggregated types
    */
-  public static List<InstrumentationEntity> convertToEntities(List<InstrumentationPath> paths) {
-    Map<String, InstrumentationEntity> entityMap = new HashMap<>();
+  public static List<InstrumentationModule> convertToInstrumentationModules(
+      List<InstrumentationPath> paths) {
+    Map<String, InstrumentationModule> moduleMap = new HashMap<>();
 
     for (InstrumentationPath path : paths) {
       String key = path.group() + ":" + path.namespace() + ":" + path.instrumentationName();
-      if (!entityMap.containsKey(key)) {
-        entityMap.put(
+      if (!moduleMap.containsKey(key)) {
+        moduleMap.put(
             key,
-            new InstrumentationEntity.Builder()
+            new InstrumentationModule.Builder()
                 .srcPath(path.srcPath().replace("/javaagent", "").replace("/library", ""))
                 .instrumentationName(path.instrumentationName())
                 .namespace(path.namespace())
@@ -51,33 +52,33 @@ public static List<InstrumentationEntity> convertToEntities(List<Instrumentation
       }
     }
 
-    return new ArrayList<>(entityMap.values());
+    return new ArrayList<>(moduleMap.values());
   }
 
   /**
-   * Analyzes the given root directory to find all instrumentation paths and then analyze them.
-   * Extracts version information from each instrumentation's build.gradle file. Extracts
+   * Traverses the given root directory to find all instrumentation paths and then analyzes them.
+   * Extracts version information from each instrumentation's build.gradle file, and other
    * information from metadata.yaml files.
    *
-   * @return a list of {@link InstrumentationEntity}
+   * @return a list of {@link InstrumentationModule}
    */
-  List<InstrumentationEntity> analyze() {
+  List<InstrumentationModule> analyze() {
     List<InstrumentationPath> paths = fileManager.getInstrumentationPaths();
-    List<InstrumentationEntity> entities = convertToEntities(paths);
+    List<InstrumentationModule> modules = convertToInstrumentationModules(paths);
 
-    for (InstrumentationEntity entity : entities) {
-      List<String> gradleFiles = fileManager.findBuildGradleFiles(entity.getSrcPath());
-      analyzeVersions(gradleFiles, entity);
+    for (InstrumentationModule module : modules) {
+      List<String> gradleFiles = fileManager.findBuildGradleFiles(module.getSrcPath());
+      analyzeVersions(gradleFiles, module);
 
-      String metadataFile = fileManager.getMetaDataFile(entity.getSrcPath());
+      String metadataFile = fileManager.getMetaDataFile(module.getSrcPath());
       if (metadataFile != null) {
-        entity.setMetadata(YamlHelper.metaDataParser(metadataFile));
+        module.setMetadata(YamlHelper.metaDataParser(metadataFile));
       }
     }
-    return entities;
+    return modules;
   }
 
-  void analyzeVersions(List<String> files, InstrumentationEntity entity) {
+  void analyzeVersions(List<String> files, InstrumentationModule module) {
     Map<InstrumentationType, Set<String>> versions = new HashMap<>();
     for (String file : files) {
       String fileContents = fileManager.readFileToString(file);
@@ -95,9 +96,9 @@ void analyzeVersions(List<String> files, InstrumentationEntity entity) {
             .addAll(results.versions());
       }
       if (results != null && results.minJavaVersionSupported() != null) {
-        entity.setMinJavaVersion(results.minJavaVersionSupported());
+        module.setMinJavaVersion(results.minJavaVersionSupported());
       }
     }
-    entity.setTargetVersions(versions);
+    module.setTargetVersions(versions);
   }
 }

instrumentation-docs/src/main/java/io/opentelemetry/instrumentation/docs/internal/InstrumentationEntity.java → instrumentation-docs/src/main/java/io/opentelemetry/instrumentation/docs/internal/InstrumentationModule.java

@@ -14,10 +14,12 @@
 import javax.annotation.Nullable;
 
 /**
- * This class is internal and is hence not for public use. Its APIs are unstable and can change at
- * any time.
+ * Represents an instrumentation module and all associated metadata.
+ *
+ * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
+ * at any time.
  */
-public class InstrumentationEntity {
+public class InstrumentationModule {
   private final String srcPath;
   private final String instrumentationName;
   private final String namespace;
@@ -34,7 +36,7 @@ public class InstrumentationEntity {
    * This class is internal and is hence not for public use. Its APIs are unstable and can change at
    * any time.
    */
-  public InstrumentationEntity(Builder builder) {
+  public InstrumentationModule(Builder builder) {
     requireNonNull(builder.srcPath, "srcPath required");
     requireNonNull(builder.instrumentationName, "instrumentationName required");
     requireNonNull(builder.namespace, "namespace required");
@@ -155,8 +157,8 @@ public Builder targetVersions(Map<InstrumentationType, Set<String>> targetVersio
       return this;
     }
 
-    public InstrumentationEntity build() {
-      return new InstrumentationEntity(this);
+    public InstrumentationModule build() {
+      return new InstrumentationModule(this);
     }
   }
 }

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

@@ -6,8 +6,8 @@
 package io.opentelemetry.instrumentation.docs.utils;
 
 import io.opentelemetry.instrumentation.docs.internal.InstrumentationClassification;
-import io.opentelemetry.instrumentation.docs.internal.InstrumentationEntity;
 import io.opentelemetry.instrumentation.docs.internal.InstrumentationMetaData;
+import io.opentelemetry.instrumentation.docs.internal.InstrumentationModule;
 import java.io.BufferedWriter;
 import java.util.ArrayList;
 import java.util.LinkedHashMap;
@@ -33,7 +33,7 @@ public class YamlHelper {
   }
 
   public static void generateInstrumentationYaml(
-      List<InstrumentationEntity> list, BufferedWriter writer) {
+      List<InstrumentationModule> list, BufferedWriter writer) {
     DumperOptions options = new DumperOptions();
     options.setDefaultFlowStyle(DumperOptions.FlowStyle.BLOCK);
 
@@ -55,29 +55,29 @@ public static void generateInstrumentationYaml(
     }
   }
 
-  private static Map<String, Object> getLibraryInstrumentations(List<InstrumentationEntity> list) {
-    Map<String, List<InstrumentationEntity>> libraryInstrumentations =
+  private static Map<String, Object> getLibraryInstrumentations(List<InstrumentationModule> list) {
+    Map<String, List<InstrumentationModule>> libraryInstrumentations =
         list.stream()
             .filter(
-                entity ->
-                    entity
+                module ->
+                    module
                         .getMetadata()
                         .getClassification()
                         .equals(InstrumentationClassification.LIBRARY))
             .collect(
                 Collectors.groupingBy(
-                    InstrumentationEntity::getGroup, TreeMap::new, Collectors.toList()));
+                    InstrumentationModule::getGroup, TreeMap::new, Collectors.toList()));
 
     Map<String, Object> output = new TreeMap<>();
     libraryInstrumentations.forEach(
-        (group, entities) -> {
+        (group, modules) -> {
           List<Map<String, Object>> instrumentations = new ArrayList<>();
-          for (InstrumentationEntity entity : entities) {
-            Map<String, Object> entityMap = baseProperties(entity);
+          for (InstrumentationModule module : modules) {
+            Map<String, Object> moduleMap = baseProperties(module);
 
             Map<String, Object> targetVersions = new TreeMap<>();
-            if (entity.getTargetVersions() != null && !entity.getTargetVersions().isEmpty()) {
-              entity
+            if (module.getTargetVersions() != null && !module.getTargetVersions().isEmpty()) {
+              module
                   .getTargetVersions()
                   .forEach(
                       (type, versions) -> {
@@ -86,9 +86,9 @@ private static Map<String, Object> getLibraryInstrumentations(List<Instrumentati
                         }
                       });
             }
-            entityMap.put("target_versions", targetVersions);
+            moduleMap.put("target_versions", targetVersions);
 
-            instrumentations.add(entityMap);
+            instrumentations.add(moduleMap);
           }
           output.put(group, instrumentations);
         });
@@ -102,15 +102,15 @@ private static Map<String, Object> getLibraryInstrumentations(List<Instrumentati
   }
 
   private static Map<String, Object> generateBaseYaml(
-      List<InstrumentationEntity> list, InstrumentationClassification classification) {
-    List<InstrumentationEntity> filtered =
+      List<InstrumentationModule> list, InstrumentationClassification classification) {
+    List<InstrumentationModule> filtered =
         list.stream()
-            .filter(entity -> entity.getMetadata().getClassification().equals(classification))
+            .filter(module -> module.getMetadata().getClassification().equals(classification))
             .toList();
 
     List<Map<String, Object>> instrumentations = new ArrayList<>();
-    for (InstrumentationEntity entity : filtered) {
-      instrumentations.add(baseProperties(entity));
+    for (InstrumentationModule module : filtered) {
+      instrumentations.add(baseProperties(module));
     }
 
     Map<String, Object> newOutput = new TreeMap<>();
@@ -121,34 +121,34 @@ private static Map<String, Object> generateBaseYaml(
     return newOutput;
   }
 
-  private static Map<String, Object> baseProperties(InstrumentationEntity entity) {
-    Map<String, Object> entityMap = new LinkedHashMap<>();
-    entityMap.put("name", entity.getInstrumentationName());
+  private static Map<String, Object> baseProperties(InstrumentationModule module) {
+    Map<String, Object> moduleMap = new LinkedHashMap<>();
+    moduleMap.put("name", module.getInstrumentationName());
 
-    if (entity.getMetadata() != null) {
-      if (entity.getMetadata().getDescription() != null) {
-        entityMap.put("description", entity.getMetadata().getDescription());
+    if (module.getMetadata() != null) {
+      if (module.getMetadata().getDescription() != null) {
+        moduleMap.put("description", module.getMetadata().getDescription());
       }
 
-      if (entity.getMetadata().getDisabledByDefault()) {
-        entityMap.put("disabled_by_default", entity.getMetadata().getDisabledByDefault());
+      if (module.getMetadata().getDisabledByDefault()) {
+        moduleMap.put("disabled_by_default", module.getMetadata().getDisabledByDefault());
       }
     }
 
-    entityMap.put("source_path", entity.getSrcPath());
+    moduleMap.put("source_path", module.getSrcPath());
 
-    if (entity.getMinJavaVersion() != null) {
-      entityMap.put("minimum_java_version", entity.getMinJavaVersion());
+    if (module.getMinJavaVersion() != null) {
+      moduleMap.put("minimum_java_version", module.getMinJavaVersion());
     }
 
-    Map<String, Object> scopeMap = getScopeMap(entity);
-    entityMap.put("scope", scopeMap);
-    return entityMap;
+    Map<String, Object> scopeMap = getScopeMap(module);
+    moduleMap.put("scope", scopeMap);
+    return moduleMap;
   }
 
-  private static Map<String, Object> getScopeMap(InstrumentationEntity entity) {
+  private static Map<String, Object> getScopeMap(InstrumentationModule module) {
     Map<String, Object> scopeMap = new LinkedHashMap<>();
-    scopeMap.put("name", entity.getScopeInfo().getName());
+    scopeMap.put("name", module.getScopeInfo().getName());
     return scopeMap;
   }
 

instrumentation-docs/src/test/java/io/opentelemetry/instrumentation/docs/InstrumentationAnalyzerTest.java

@@ -7,7 +7,7 @@
 
 import static org.assertj.core.api.Assertions.assertThat;
 
-import io.opentelemetry.instrumentation.docs.internal.InstrumentationEntity;
+import io.opentelemetry.instrumentation.docs.internal.InstrumentationModule;
 import io.opentelemetry.instrumentation.docs.internal.InstrumentationType;
 import io.opentelemetry.instrumentation.docs.utils.InstrumentationPath;
 import java.util.Arrays;
@@ -17,7 +17,7 @@
 class InstrumentationAnalyzerTest {
 
   @Test
-  void testConvertToEntities() {
+  void testConvertToInstrumentationModule() {
     List<InstrumentationPath> paths =
         Arrays.asList(
             new InstrumentationPath(
@@ -39,32 +39,33 @@ void testConvertToEntities() {
                 "spring",
                 InstrumentationType.LIBRARY));
 
-    List<InstrumentationEntity> entities = InstrumentationAnalyzer.convertToEntities(paths);
+    List<InstrumentationModule> modules =
+        InstrumentationAnalyzer.convertToInstrumentationModules(paths);
 
-    assertThat(entities.size()).isEqualTo(2);
+    assertThat(modules.size()).isEqualTo(2);
 
-    InstrumentationEntity log4jEntity =
-        entities.stream()
+    InstrumentationModule log4jModule =
+        modules.stream()
             .filter(e -> e.getInstrumentationName().equals("log4j-appender-2.17"))
             .findFirst()
             .orElse(null);
 
-    assertThat(log4jEntity.getNamespace()).isEqualTo("log4j");
-    assertThat(log4jEntity.getGroup()).isEqualTo("log4j");
-    assertThat(log4jEntity.getSrcPath()).isEqualTo("instrumentation/log4j/log4j-appender-2.17");
-    assertThat(log4jEntity.getScopeInfo().getName())
+    assertThat(log4jModule.getNamespace()).isEqualTo("log4j");
+    assertThat(log4jModule.getGroup()).isEqualTo("log4j");
+    assertThat(log4jModule.getSrcPath()).isEqualTo("instrumentation/log4j/log4j-appender-2.17");
+    assertThat(log4jModule.getScopeInfo().getName())
         .isEqualTo("io.opentelemetry.log4j-appender-2.17");
 
-    InstrumentationEntity springEntity =
-        entities.stream()
+    InstrumentationModule springModule =
+        modules.stream()
             .filter(e -> e.getInstrumentationName().equals("spring-web"))
             .findFirst()
             .orElse(null);
 
-    assertThat(springEntity).isNotNull();
-    assertThat(springEntity.getNamespace()).isEqualTo("spring");
-    assertThat(springEntity.getGroup()).isEqualTo("spring");
-    assertThat(springEntity.getSrcPath()).isEqualTo("instrumentation/spring/spring-web");
-    assertThat(springEntity.getScopeInfo().getName()).isEqualTo("io.opentelemetry.spring-web");
+    assertThat(springModule).isNotNull();
+    assertThat(springModule.getNamespace()).isEqualTo("spring");
+    assertThat(springModule.getGroup()).isEqualTo("spring");
+    assertThat(springModule.getSrcPath()).isEqualTo("instrumentation/spring/spring-web");
+    assertThat(springModule.getScopeInfo().getName()).isEqualTo("io.opentelemetry.spring-web");
   }
 }