diff --git a/docs/instrumentation-list.yaml b/docs/instrumentation-list.yaml index 323c468552..35d0b86e9b 100644 --- a/docs/instrumentation-list.yaml +++ b/docs/instrumentation-list.yaml @@ -638,11 +638,6 @@ libraries: target_versions: javaagent: - javax.ws.rs:javax.ws.rs-api:[,] - - name: jaxrs-client-1.1 - source_path: instrumentation/jaxrs-client/jaxrs-client-1.1 - scope: - name: io.opentelemetry.jaxrs-client-1.1 - target_versions: {} - name: jaxrs-3.0-resteasy-6.0 source_path: instrumentation/jaxrs/jaxrs-3.0/jaxrs-3.0-resteasy-6.0 minimum_java_version: 11 @@ -675,11 +670,6 @@ libraries: target_versions: javaagent: - javax.xml.ws:jaxws-api:[2.0,] - - name: jaxws-2.0-metro-2.2 - source_path: instrumentation/jaxws/jaxws-2.0-metro-2.2 - scope: - name: io.opentelemetry.jaxws-2.0-metro-2.2 - target_versions: {} - name: jaxws-cxf-3.0 source_path: instrumentation/jaxws/jaxws-cxf-3.0 scope: @@ -694,11 +684,6 @@ libraries: target_versions: javaagent: - org.apache.axis2:axis2-jaxws:[1.6.0,) - - name: jaxws-2.0-cxf-3.0 - source_path: instrumentation/jaxws/jaxws-2.0-cxf-3.0 - scope: - name: io.opentelemetry.jaxws-2.0-cxf-3.0 - target_versions: {} - name: jaxws-metro-2.2 source_path: instrumentation/jaxws/jaxws-metro-2.2 scope: @@ -979,12 +964,10 @@ libraries: source_path: instrumentation/liberty/liberty-dispatcher-20.0 scope: name: io.opentelemetry.liberty-dispatcher-20.0 - target_versions: {} - name: liberty-20.0 source_path: instrumentation/liberty/liberty-20.0 scope: name: io.opentelemetry.liberty-20.0 - target_versions: {} log4j: - name: log4j-context-data-2.7 source_path: instrumentation/log4j/log4j-context-data/log4j-context-data-2.7 @@ -1175,7 +1158,6 @@ libraries: source_path: instrumentation/payara scope: name: io.opentelemetry.payara - target_versions: {} pekko: - name: pekko-actor-1.0 source_path: instrumentation/pekko/pekko-actor-1.0 @@ -1380,7 +1362,6 @@ libraries: source_path: instrumentation/resources scope: name: io.opentelemetry.resources - target_versions: {} restlet: - name: restlet-1.1 source_path: instrumentation/restlet/restlet-1.1 @@ -1432,12 +1413,10 @@ libraries: minimum_java_version: 17 scope: name: io.opentelemetry.runtime-telemetry-java17 - target_versions: {} - name: runtime-telemetry-java8 source_path: instrumentation/runtime-telemetry/runtime-telemetry-java8 scope: name: io.opentelemetry.runtime-telemetry-java8 - target_versions: {} rxjava: - name: rxjava-1.0 source_path: instrumentation/rxjava/rxjava-1.0 @@ -1530,7 +1509,6 @@ libraries: source_path: instrumentation/spring/spring-boot-resources scope: name: io.opentelemetry.spring-boot-resources - target_versions: {} - name: spring-batch-3.0 disabled_by_default: true source_path: instrumentation/spring/spring-batch-3.0 @@ -1635,7 +1613,6 @@ libraries: source_path: instrumentation/spring/spring-webmvc/spring-webmvc-5.3 scope: name: io.opentelemetry.spring-webmvc-5.3 - target_versions: {} - name: spring-core-2.0 source_path: instrumentation/spring/spring-core-2.0 minimum_java_version: 17 @@ -1893,6 +1870,10 @@ internal: source_path: instrumentation/internal/internal-application-logger scope: name: io.opentelemetry.internal-application-logger + target_versions: + javaagent: + - org.springframework.boot:spring-boot:[1.2.0,) + - org.slf4j:slf4j-api:[1.4.0,) - name: internal-class-loader source_path: instrumentation/internal/internal-class-loader scope: @@ -1909,6 +1890,9 @@ internal: source_path: instrumentation/opentelemetry-instrumentation-api scope: name: io.opentelemetry.opentelemetry-instrumentation-api + target_versions: + javaagent: + - io.opentelemetry.instrumentation:opentelemetry-instrumentation-api:[1.14.0-alpha,) - name: opentelemetry-api-1.37 source_path: instrumentation/opentelemetry-api/opentelemetry-api-1.37 scope: @@ -1949,6 +1933,15 @@ internal: source_path: instrumentation/internal/internal-url-class-loader scope: name: io.opentelemetry.internal-url-class-loader +- name: opentelemetry-extension-kotlin-1.0 + description: | + Our Kotlin coroutine instrumentation relies on a shaded copy of the opentelemetry-extension-kotlin library. This can cause conflicts when the application itself also uses opentelemetry-extension-kotlin, because the shaded and unshaded versions store the OpenTelemetry context under different keys. To resolve this issue, this instrumentation modifies the application's copy of opentelemetry-extension-kotlin so that it delegates to the shaded version bundled within the agent. + source_path: instrumentation/opentelemetry-extension-kotlin-1.0 + scope: + name: io.opentelemetry.opentelemetry-extension-kotlin-1.0 + target_versions: + javaagent: + - io.opentelemetry:opentelemetry-extension-kotlin:[0.17.0,) - name: opentelemetry-api-1.4 source_path: instrumentation/opentelemetry-api/opentelemetry-api-1.4 scope: @@ -1957,28 +1950,49 @@ internal: source_path: instrumentation/opentelemetry-api/opentelemetry-api-1.0 scope: name: io.opentelemetry.opentelemetry-api-1.0 + target_versions: + javaagent: + - io.opentelemetry:opentelemetry-api:[0.17.0,) custom: - name: external-annotations + description: | + The external-annotations instrumentation acts as a "shim" that automatically instruments methods annotated with custom or third-party tracing annotations. This is particularly useful if you have existing annotations (such as a custom @Trace or third-party annotation) that you want to leverage with OpenTelemetry. At runtime, this module recognizes those annotations and applies the appropriate OpenTelemetry instrumentation logic, including span creation and context propagation. Covers many common vendor annotations by default, and additional annotations can be targeted using the configuration property "otel.instrumentation.external-annotations.include". source_path: instrumentation/external-annotations scope: name: io.opentelemetry.external-annotations + target_versions: + javaagent: + - Java 8+ - name: opentelemetry-extension-annotations-1.0 + description: | + Instruments methods annotated with OpenTelemetry extension annotations, such as @WithSpan and @SpanAttribute. source_path: instrumentation/opentelemetry-extension-annotations-1.0 scope: name: io.opentelemetry.opentelemetry-extension-annotations-1.0 + target_versions: + javaagent: + - io.opentelemetry:opentelemetry-extension-annotations:[0.16.0,) - name: opentelemetry-instrumentation-annotations-1.16 + description: | + Instruments methods annotated with OpenTelemetry instrumentation annotations, such as @WithSpan and @SpanAttribute. source_path: instrumentation/opentelemetry-instrumentation-annotations-1.16 scope: name: io.opentelemetry.opentelemetry-instrumentation-annotations-1.16 + target_versions: + javaagent: + - io.opentelemetry:opentelemetry-instrumentation-annotations:(,) - name: jmx-metrics + description: | + Collects and reports metrics exposed through Java Management Extensions (JMX). It can be configured to extract JVM and application-level telemetry data from JMX MBeans such as memory usage, thread counts, and garbage collection statistics, and translate these measurements into OpenTelemetry metrics. source_path: instrumentation/jmx-metrics scope: name: io.opentelemetry.jmx-metrics - name: methods + description: | + Provides a flexible way to capture telemetry at the method level in JVM applications. By weaving instrumentation into targeted methods at runtime based on the "otel.instrumentation.methods.include" configuration property, it measures entry and exit points, execution duration and exception occurrences. The resulting data is automatically translated into OpenTelemetry traces. source_path: instrumentation/methods scope: name: io.opentelemetry.methods -- name: opentelemetry-extension-kotlin-1.0 - source_path: instrumentation/opentelemetry-extension-kotlin-1.0 - scope: - name: io.opentelemetry.opentelemetry-extension-kotlin-1.0 + target_versions: + javaagent: + - Java 8+ 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 4d20af8a75..e1f58dae58 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 @@ -14,6 +14,7 @@ import java.util.LinkedHashMap; import java.util.List; import java.util.Map; import java.util.TreeMap; +import java.util.logging.Logger; import java.util.stream.Collectors; import org.yaml.snakeyaml.DumperOptions; import org.yaml.snakeyaml.TypeDescription; @@ -21,6 +22,8 @@ import org.yaml.snakeyaml.Yaml; public class YamlHelper { + private static final Logger logger = Logger.getLogger(YamlHelper.class.getName()); + private static final Yaml metaDataYaml = new Yaml(); static { @@ -73,22 +76,7 @@ public class YamlHelper { (group, modules) -> { List> instrumentations = new ArrayList<>(); for (InstrumentationModule module : modules) { - Map moduleMap = baseProperties(module); - - Map targetVersions = new TreeMap<>(); - if (module.getTargetVersions() != null && !module.getTargetVersions().isEmpty()) { - module - .getTargetVersions() - .forEach( - (type, versions) -> { - if (!versions.isEmpty()) { - targetVersions.put(type.toString(), new ArrayList<>(versions)); - } - }); - } - moduleMap.put("target_versions", targetVersions); - - instrumentations.add(moduleMap); + instrumentations.add(baseProperties(module)); } output.put(group, instrumentations); }); @@ -143,6 +131,24 @@ public class YamlHelper { Map scopeMap = getScopeMap(module); moduleMap.put("scope", scopeMap); + + Map targetVersions = new TreeMap<>(); + if (module.getTargetVersions() != null && !module.getTargetVersions().isEmpty()) { + module + .getTargetVersions() + .forEach( + (type, versions) -> { + if (!versions.isEmpty()) { + targetVersions.put(type.toString(), new ArrayList<>(versions)); + } + }); + } + if (targetVersions.isEmpty()) { + logger.info("No Target versions found for " + module.getInstrumentationName()); + } else { + moduleMap.put("target_versions", targetVersions); + } + return moduleMap; } 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 224a5dc770..13a33a585d 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 @@ -97,10 +97,8 @@ class YamlHelperTest { @Test void testGenerateInstrumentationYamlSeparatesClassifications() throws Exception { List modules = new ArrayList<>(); - Map> springTargetVersions = new HashMap<>(); - springTargetVersions.put( - InstrumentationType.JAVAAGENT, - new HashSet<>(List.of("org.springframework:spring-web:[6.0.0,)"))); + Map> springTargetVersions = + Map.of(InstrumentationType.JAVAAGENT, Set.of("org.springframework:spring-web:[6.0.0,)")); InstrumentationMetaData springMetadata = new InstrumentationMetaData( @@ -135,6 +133,11 @@ class YamlHelperTest { InstrumentationMetaData customMetadata = new InstrumentationMetaData(null, InstrumentationClassification.CUSTOM.toString(), null); + Map> externalAnnotationsVersions = + Map.of( + InstrumentationType.JAVAAGENT, + Set.of("io.opentelemetry:opentelemetry-extension-annotations:[0.16.0,)")); + modules.add( new InstrumentationModule.Builder() .srcPath("instrumentation/opentelemetry-external-annotations-1.0") @@ -142,7 +145,7 @@ class YamlHelperTest { .namespace("opentelemetry-external-annotations") .group("opentelemetry-external-annotations") .metadata(customMetadata) - .targetVersions(new HashMap<>()) + .targetVersions(externalAnnotationsVersions) .build()); StringWriter stringWriter = new StringWriter(); @@ -174,6 +177,9 @@ class YamlHelperTest { source_path: instrumentation/opentelemetry-external-annotations-1.0 scope: name: io.opentelemetry.opentelemetry-external-annotations + target_versions: + javaagent: + - io.opentelemetry:opentelemetry-extension-annotations:[0.16.0,) """; assertThat(expectedYaml).isEqualTo(stringWriter.toString()); diff --git a/instrumentation/external-annotations/README.md b/instrumentation/external-annotations/README.md index 5dae19d769..2bbe1092fb 100644 --- a/instrumentation/external-annotations/README.md +++ b/instrumentation/external-annotations/README.md @@ -1,5 +1,13 @@ # Settings for the external annotations instrumentation +The external-annotations instrumentation acts as a "shim" that automatically instruments methods +annotated with custom or third-party tracing annotations. This is particularly useful if you have +existing annotations (such as a custom @Trace or third-party annotation) that you want to leverage +with OpenTelemetry. At runtime, this module recognizes those annotations and applies the appropriate +OpenTelemetry instrumentation logic, including span creation and context propagation. Covers many +common vendor annotations by default, and additional annotations can be targeted using the +configuration property "otel.instrumentation.external-annotations.include". + | System property | Type | Default | Description | | ----------------------------------------------------------- | ------ | ------------------- | --------------------------------------------------------------------------------------------------------- | | `otel.instrumentation.external-annotations.include` | String | Default annotations | Configuration for trace annotations, in the form of a pattern that matches `'package.Annotation$Name;*'`. | diff --git a/instrumentation/external-annotations/metadata.yaml b/instrumentation/external-annotations/metadata.yaml index 14a45327b4..5e9578e705 100644 --- a/instrumentation/external-annotations/metadata.yaml +++ b/instrumentation/external-annotations/metadata.yaml @@ -1 +1,9 @@ classification: custom +description: > + The external-annotations instrumentation acts as a "shim" that automatically instruments methods + annotated with custom or third-party tracing annotations. This is particularly useful if you have + existing annotations (such as a custom @Trace or third-party annotation) that you want to leverage + with OpenTelemetry. At runtime, this module recognizes those annotations and applies the + appropriate OpenTelemetry instrumentation logic, including span creation and context propagation. + Covers many common vendor annotations by default, and additional annotations can be targeted using + the configuration property "otel.instrumentation.external-annotations.include". diff --git a/instrumentation/jmx-metrics/metadata.yaml b/instrumentation/jmx-metrics/metadata.yaml index 14a45327b4..34f5b4213a 100644 --- a/instrumentation/jmx-metrics/metadata.yaml +++ b/instrumentation/jmx-metrics/metadata.yaml @@ -1 +1,6 @@ classification: custom +description: > + Collects and reports metrics exposed through Java Management Extensions (JMX). It can be + configured to extract JVM and application-level telemetry data from JMX MBeans such as memory + usage, thread counts, and garbage collection statistics, and translate these measurements into + OpenTelemetry metrics. diff --git a/instrumentation/methods/README.md b/instrumentation/methods/README.md index 7ecc008ab6..950567e890 100644 --- a/instrumentation/methods/README.md +++ b/instrumentation/methods/README.md @@ -1,5 +1,10 @@ # Settings for the methods instrumentation +Provides a flexible way to capture telemetry at the method level in JVM applications. By weaving +instrumentation into targeted methods at runtime based on the "otel.instrumentation.methods.include" +configuration property, it measures entry and exit points, execution duration and exception +occurrences. The resulting data is automatically translated into OpenTelemetry traces. + | System property | Type | Default | Description | | -------------------------------------- | ------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `otel.instrumentation.methods.include` | String | None | List of methods to include for tracing. For more information, see [Creating spans around methods with `otel.instrumentation.methods.include`][cs]. | diff --git a/instrumentation/methods/metadata.yaml b/instrumentation/methods/metadata.yaml index 14a45327b4..0c9b2bb733 100644 --- a/instrumentation/methods/metadata.yaml +++ b/instrumentation/methods/metadata.yaml @@ -1 +1,7 @@ classification: custom +description: > + Provides a flexible way to capture telemetry at the method level in JVM applications. By weaving + instrumentation into targeted methods at runtime based on the + "otel.instrumentation.methods.include" configuration property, it measures entry and exit points, + execution duration and exception occurrences. The resulting data is automatically translated into + OpenTelemetry traces. diff --git a/instrumentation/opentelemetry-extension-annotations-1.0/README.md b/instrumentation/opentelemetry-extension-annotations-1.0/README.md index f36aec9fc6..62b2ff2705 100644 --- a/instrumentation/opentelemetry-extension-annotations-1.0/README.md +++ b/instrumentation/opentelemetry-extension-annotations-1.0/README.md @@ -1,5 +1,8 @@ # Settings for the OpenTelemetry Extension Annotations integration +Instruments methods annotated with OpenTelemetry extension annotations, such as @WithSpan and +@SpanAttribute. + | Environment variable | Type | Default | Description | | ---------------------------------------------------------------- | ------ | ------- | --------------------------------------------------------------------------------- | | `otel.instrumentation.opentelemetry-annotations.exclude-methods` | String | | All methods to be excluded from auto-instrumentation by annotation-based advices. | diff --git a/instrumentation/opentelemetry-extension-annotations-1.0/metadata.yaml b/instrumentation/opentelemetry-extension-annotations-1.0/metadata.yaml index 14a45327b4..cd1c92c278 100644 --- a/instrumentation/opentelemetry-extension-annotations-1.0/metadata.yaml +++ b/instrumentation/opentelemetry-extension-annotations-1.0/metadata.yaml @@ -1 +1,4 @@ classification: custom +description: > + Instruments methods annotated with OpenTelemetry extension annotations, such as @WithSpan + and @SpanAttribute. diff --git a/instrumentation/opentelemetry-extension-kotlin-1.0/README.md b/instrumentation/opentelemetry-extension-kotlin-1.0/README.md new file mode 100644 index 0000000000..a8e8659e17 --- /dev/null +++ b/instrumentation/opentelemetry-extension-kotlin-1.0/README.md @@ -0,0 +1,8 @@ +# OpenTelemetry Kotlin Extension Instrumentation + +Our Kotlin coroutine instrumentation relies on a shaded copy of the `opentelemetry-extension-kotlin` +library. This can cause conflicts when the application itself also uses +`opentelemetry-extension-kotlin`, because the shaded and unshaded versions store the OpenTelemetry +context under different keys. To resolve this issue, this instrumentation modifies the application's +copy of `opentelemetry-extension-kotlin` so that it delegates to the shaded version bundled within +the agent. diff --git a/instrumentation/opentelemetry-extension-kotlin-1.0/metadata.yaml b/instrumentation/opentelemetry-extension-kotlin-1.0/metadata.yaml index 14a45327b4..f2c98a07d4 100644 --- a/instrumentation/opentelemetry-extension-kotlin-1.0/metadata.yaml +++ b/instrumentation/opentelemetry-extension-kotlin-1.0/metadata.yaml @@ -1 +1,8 @@ -classification: custom +classification: internal +description: > + Our Kotlin coroutine instrumentation relies on a shaded copy of the opentelemetry-extension-kotlin + library. This can cause conflicts when the application itself also uses + opentelemetry-extension-kotlin, because the shaded and unshaded versions store the OpenTelemetry + context under different keys. To resolve this issue, this instrumentation modifies the + application's copy of opentelemetry-extension-kotlin so that it delegates to the shaded version + bundled within the agent. diff --git a/instrumentation/opentelemetry-instrumentation-annotations-1.16/README.md b/instrumentation/opentelemetry-instrumentation-annotations-1.16/README.md index 33bec5e257..aa7476f0a5 100644 --- a/instrumentation/opentelemetry-instrumentation-annotations-1.16/README.md +++ b/instrumentation/opentelemetry-instrumentation-annotations-1.16/README.md @@ -1,5 +1,8 @@ # Settings for the OpenTelemetry Instrumentation Annotations integration +Instruments methods annotated with OpenTelemetry instrumentation annotations, such as @WithSpan and +@SpanAttribute. + | Environment variable | Type | Default | Description | | -------------------------------------------------------------------------------- | ------ | ------- | --------------------------------------------------------------------------------- | | `otel.instrumentation.opentelemetry-instrumentation-annotations.exclude-methods` | String | | All methods to be excluded from auto-instrumentation by annotation-based advices. | diff --git a/instrumentation/opentelemetry-instrumentation-annotations-1.16/metadata.yaml b/instrumentation/opentelemetry-instrumentation-annotations-1.16/metadata.yaml index 14a45327b4..c7da9704cc 100644 --- a/instrumentation/opentelemetry-instrumentation-annotations-1.16/metadata.yaml +++ b/instrumentation/opentelemetry-instrumentation-annotations-1.16/metadata.yaml @@ -1 +1,4 @@ classification: custom +description: > + Instruments methods annotated with OpenTelemetry instrumentation annotations, such as @WithSpan + and @SpanAttribute.