diff --git a/instrumentation-docs/readme.md b/instrumentation-docs/readme.md index 7039779a1ef3..07ea48a3b921 100644 --- a/instrumentation-docs/readme.md +++ b/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: diff --git a/instrumentation-docs/src/main/java/io/opentelemetry/instrumentation/docs/DocGeneratorApplication.java b/instrumentation-docs/src/main/java/io/opentelemetry/instrumentation/docs/DocGeneratorApplication.java index 1b5d28a7ebad..0b35d6a3225f 100644 --- a/instrumentation-docs/src/main/java/io/opentelemetry/instrumentation/docs/DocGeneratorApplication.java +++ b/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 entities = new InstrumentationAnalyzer(fileManager).analyze(); + List 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()); } diff --git a/instrumentation-docs/src/main/java/io/opentelemetry/instrumentation/docs/InstrumentationAnalyzer.java b/instrumentation-docs/src/main/java/io/opentelemetry/instrumentation/docs/InstrumentationAnalyzer.java index d03270dedaa5..358c9ae729a4 100644 --- a/instrumentation-docs/src/main/java/io/opentelemetry/instrumentation/docs/InstrumentationAnalyzer.java +++ b/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 convertToEntities(List paths) { - Map entityMap = new HashMap<>(); + public static List convertToInstrumentationModules( + List paths) { + Map 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 convertToEntities(List(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 analyze() { + List analyze() { List paths = fileManager.getInstrumentationPaths(); - List entities = convertToEntities(paths); + List modules = convertToInstrumentationModules(paths); - for (InstrumentationEntity entity : entities) { - List gradleFiles = fileManager.findBuildGradleFiles(entity.getSrcPath()); - analyzeVersions(gradleFiles, entity); + for (InstrumentationModule module : modules) { + List 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 files, InstrumentationEntity entity) { + void analyzeVersions(List files, InstrumentationModule module) { Map> versions = new HashMap<>(); for (String file : files) { String fileContents = fileManager.readFileToString(file); @@ -95,9 +96,9 @@ void analyzeVersions(List 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); } } diff --git a/instrumentation-docs/src/main/java/io/opentelemetry/instrumentation/docs/internal/InstrumentationEntity.java b/instrumentation-docs/src/main/java/io/opentelemetry/instrumentation/docs/internal/InstrumentationModule.java similarity index 91% rename from instrumentation-docs/src/main/java/io/opentelemetry/instrumentation/docs/internal/InstrumentationEntity.java rename to instrumentation-docs/src/main/java/io/opentelemetry/instrumentation/docs/internal/InstrumentationModule.java index 45326ff5788a..ee89e9704b7d 100644 --- a/instrumentation-docs/src/main/java/io/opentelemetry/instrumentation/docs/internal/InstrumentationEntity.java +++ b/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. + * + *

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> targetVersio return this; } - public InstrumentationEntity build() { - return new InstrumentationEntity(this); + public InstrumentationModule build() { + return new InstrumentationModule(this); } } } diff --git a/instrumentation-docs/src/main/java/io/opentelemetry/instrumentation/docs/utils/YamlHelper.java b/instrumentation-docs/src/main/java/io/opentelemetry/instrumentation/docs/utils/YamlHelper.java index cc2518a7f28b..4d20af8a75bc 100644 --- a/instrumentation-docs/src/main/java/io/opentelemetry/instrumentation/docs/utils/YamlHelper.java +++ b/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 list, BufferedWriter writer) { + List list, BufferedWriter writer) { DumperOptions options = new DumperOptions(); options.setDefaultFlowStyle(DumperOptions.FlowStyle.BLOCK); @@ -55,29 +55,29 @@ public static void generateInstrumentationYaml( } } - private static Map getLibraryInstrumentations(List list) { - Map> libraryInstrumentations = + private static Map getLibraryInstrumentations(List list) { + Map> 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 output = new TreeMap<>(); libraryInstrumentations.forEach( - (group, entities) -> { + (group, modules) -> { List> instrumentations = new ArrayList<>(); - for (InstrumentationEntity entity : entities) { - Map entityMap = baseProperties(entity); + for (InstrumentationModule module : modules) { + Map moduleMap = baseProperties(module); Map 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 getLibraryInstrumentations(List getLibraryInstrumentations(List generateBaseYaml( - List list, InstrumentationClassification classification) { - List filtered = + List list, InstrumentationClassification classification) { + List filtered = list.stream() - .filter(entity -> entity.getMetadata().getClassification().equals(classification)) + .filter(module -> module.getMetadata().getClassification().equals(classification)) .toList(); List> instrumentations = new ArrayList<>(); - for (InstrumentationEntity entity : filtered) { - instrumentations.add(baseProperties(entity)); + for (InstrumentationModule module : filtered) { + instrumentations.add(baseProperties(module)); } Map newOutput = new TreeMap<>(); @@ -121,34 +121,34 @@ private static Map generateBaseYaml( return newOutput; } - private static Map baseProperties(InstrumentationEntity entity) { - Map entityMap = new LinkedHashMap<>(); - entityMap.put("name", entity.getInstrumentationName()); + private static Map baseProperties(InstrumentationModule module) { + Map 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 scopeMap = getScopeMap(entity); - entityMap.put("scope", scopeMap); - return entityMap; + Map scopeMap = getScopeMap(module); + moduleMap.put("scope", scopeMap); + return moduleMap; } - private static Map getScopeMap(InstrumentationEntity entity) { + private static Map getScopeMap(InstrumentationModule module) { Map scopeMap = new LinkedHashMap<>(); - scopeMap.put("name", entity.getScopeInfo().getName()); + scopeMap.put("name", module.getScopeInfo().getName()); return scopeMap; } diff --git a/instrumentation-docs/src/test/java/io/opentelemetry/instrumentation/docs/InstrumentationAnalyzerTest.java b/instrumentation-docs/src/test/java/io/opentelemetry/instrumentation/docs/InstrumentationAnalyzerTest.java index 98612bde5162..5598983febfe 100644 --- a/instrumentation-docs/src/test/java/io/opentelemetry/instrumentation/docs/InstrumentationAnalyzerTest.java +++ b/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 paths = Arrays.asList( new InstrumentationPath( @@ -39,32 +39,33 @@ void testConvertToEntities() { "spring", InstrumentationType.LIBRARY)); - List entities = InstrumentationAnalyzer.convertToEntities(paths); + List 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"); } } diff --git a/instrumentation-docs/src/test/java/io/opentelemetry/instrumentation/docs/utils/YamlHelperTest.java b/instrumentation-docs/src/test/java/io/opentelemetry/instrumentation/docs/utils/YamlHelperTest.java index 4b989dd052b3..224a5dc7700b 100644 --- a/instrumentation-docs/src/test/java/io/opentelemetry/instrumentation/docs/utils/YamlHelperTest.java +++ b/instrumentation-docs/src/test/java/io/opentelemetry/instrumentation/docs/utils/YamlHelperTest.java @@ -8,8 +8,8 @@ import static org.assertj.core.api.Assertions.assertThat; 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 io.opentelemetry.instrumentation.docs.internal.InstrumentationType; import java.io.BufferedWriter; import java.io.StringWriter; @@ -24,7 +24,7 @@ class YamlHelperTest { @Test void testPrintInstrumentationList() throws Exception { - List entities = new ArrayList<>(); + List modules = new ArrayList<>(); Map> targetVersions1 = new HashMap<>(); targetVersions1.put( InstrumentationType.JAVAAGENT, @@ -36,8 +36,8 @@ void testPrintInstrumentationList() throws Exception { InstrumentationClassification.LIBRARY.toString(), true); - entities.add( - new InstrumentationEntity.Builder() + modules.add( + new InstrumentationModule.Builder() .srcPath("instrumentation/spring/spring-web/spring-web-6.0") .instrumentationName("spring-web-6.0") .namespace("spring") @@ -52,8 +52,8 @@ void testPrintInstrumentationList() throws Exception { targetVersions2.put( InstrumentationType.LIBRARY, new HashSet<>(List.of("org.apache.struts:struts2-core:2.1.0"))); - entities.add( - new InstrumentationEntity.Builder() + modules.add( + new InstrumentationModule.Builder() .srcPath("instrumentation/struts/struts-2.3") .instrumentationName("struts-2.3") .namespace("struts") @@ -64,7 +64,7 @@ void testPrintInstrumentationList() throws Exception { StringWriter stringWriter = new StringWriter(); BufferedWriter writer = new BufferedWriter(stringWriter); - YamlHelper.generateInstrumentationYaml(entities, writer); + YamlHelper.generateInstrumentationYaml(modules, writer); writer.flush(); String expectedYaml = @@ -96,7 +96,7 @@ void testPrintInstrumentationList() throws Exception { @Test void testGenerateInstrumentationYamlSeparatesClassifications() throws Exception { - List entities = new ArrayList<>(); + List modules = new ArrayList<>(); Map> springTargetVersions = new HashMap<>(); springTargetVersions.put( InstrumentationType.JAVAAGENT, @@ -108,8 +108,8 @@ void testGenerateInstrumentationYamlSeparatesClassifications() throws Exception InstrumentationClassification.LIBRARY.toString(), false); - entities.add( - new InstrumentationEntity.Builder() + modules.add( + new InstrumentationModule.Builder() .srcPath("instrumentation/spring/spring-web/spring-web-6.0") .instrumentationName("spring-web-6.0") .namespace("spring") @@ -122,8 +122,8 @@ void testGenerateInstrumentationYamlSeparatesClassifications() throws Exception InstrumentationMetaData internalMetadata = new InstrumentationMetaData(null, InstrumentationClassification.INTERNAL.toString(), null); - entities.add( - new InstrumentationEntity.Builder() + modules.add( + new InstrumentationModule.Builder() .srcPath("instrumentation/internal/internal-application-logger") .instrumentationName("internal-application-logger") .namespace("internal") @@ -135,8 +135,8 @@ void testGenerateInstrumentationYamlSeparatesClassifications() throws Exception InstrumentationMetaData customMetadata = new InstrumentationMetaData(null, InstrumentationClassification.CUSTOM.toString(), null); - entities.add( - new InstrumentationEntity.Builder() + modules.add( + new InstrumentationModule.Builder() .srcPath("instrumentation/opentelemetry-external-annotations-1.0") .instrumentationName("opentelemetry-external-annotations") .namespace("opentelemetry-external-annotations") @@ -148,7 +148,7 @@ void testGenerateInstrumentationYamlSeparatesClassifications() throws Exception StringWriter stringWriter = new StringWriter(); BufferedWriter writer = new BufferedWriter(stringWriter); - YamlHelper.generateInstrumentationYaml(entities, writer); + YamlHelper.generateInstrumentationYaml(modules, writer); writer.flush(); String expectedYaml =