From 9ee58fcaccb3c499a9387df79f50e3317703464d Mon Sep 17 00:00:00 2001 From: Jay DeLuca Date: Thu, 17 Apr 2025 19:40:46 -0400 Subject: [PATCH 1/6] executor description --- instrumentation/executors/metadata.yaml | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 instrumentation/executors/metadata.yaml diff --git a/instrumentation/executors/metadata.yaml b/instrumentation/executors/metadata.yaml new file mode 100644 index 000000000000..b0a75d3baeb6 --- /dev/null +++ b/instrumentation/executors/metadata.yaml @@ -0,0 +1,6 @@ +description: > + The executor instrumentation ensures that context is automatically carried across threads by + wrapping common Java executors (e.g., Executor, ExecutorService, ForkJoinPool). When a task is + submitted, the current context is captured and bound to the task. Then, when the task eventually + runs, even if it’s on a different thread, the instrumentation reactivates that context, enabling + consistent correlation across concurrent and asynchronous workflows. From 5b6f3862545bd293e22a138d91f250b9169a2253 Mon Sep 17 00:00:00 2001 From: Jay DeLuca Date: Sat, 19 Apr 2025 21:00:21 -0400 Subject: [PATCH 2/6] add configuration to metadata, add more descriptions --- docs/instrumentation-list.yaml | 38 ++++++++++ instrumentation-docs/build.gradle.kts | 1 + instrumentation-docs/readme.md | 7 ++ .../docs/DocGeneratorApplication.java | 69 ++++++++++++++++++- .../docs/InstrumentationAnalyzer.java | 3 +- .../docs/internal/ConfigurationOption.java | 15 ++++ .../internal/InstrumentationMetaData.java | 25 ++++++- .../docs/utils/YamlHelper.java | 33 +++++---- .../docs/utils/YamlHelperTest.java | 68 +++++++++++++++--- .../cassandra/cassandra-3.0/metadata.yaml | 7 ++ .../cassandra/cassandra-4.0/metadata.yaml | 7 ++ .../cassandra/cassandra-4.4/metadata.yaml | 7 ++ .../clickhouse-client-0.5/metadata.yaml | 4 ++ instrumentation/jdbc/metadata.yaml | 16 +++++ 14 files changed, 275 insertions(+), 25 deletions(-) create mode 100644 instrumentation-docs/src/main/java/io/opentelemetry/instrumentation/docs/internal/ConfigurationOption.java create mode 100644 instrumentation/cassandra/cassandra-3.0/metadata.yaml create mode 100644 instrumentation/cassandra/cassandra-4.0/metadata.yaml create mode 100644 instrumentation/cassandra/cassandra-4.4/metadata.yaml diff --git a/docs/instrumentation-list.yaml b/docs/instrumentation-list.yaml index 35d0b86e9b3b..7cbd943f7ddc 100644 --- a/docs/instrumentation-list.yaml +++ b/docs/instrumentation-list.yaml @@ -239,13 +239,21 @@ libraries: - org.apache.camel:camel-core:[2.19,3) cassandra: - name: cassandra-4.0 + description: | + Instruments the Cassandra database client, providing database client spans and metrics for Cassandra queries. source_path: instrumentation/cassandra/cassandra-4.0 scope: name: io.opentelemetry.cassandra-4.0 target_versions: javaagent: - com.datastax.oss:java-driver-core:[4.0,4.4) + configurations: + - name: otel.instrumentation.common.db-statement-sanitizer.enabled + description: Enables or disables statement sanitization for database queries. + default: 'true' - name: cassandra-4.4 + description: | + Instruments the Cassandra database client, providing database client spans and metrics for Cassandra queries. source_path: instrumentation/cassandra/cassandra-4.4 scope: name: io.opentelemetry.cassandra-4.4 @@ -254,13 +262,23 @@ libraries: - com.datastax.oss:java-driver-core:[4.4,] library: - com.datastax.oss:java-driver-core:4.4.0 + configurations: + - name: otel.instrumentation.common.db-statement-sanitizer.enabled + description: Enables or disables statement sanitization for database queries. + default: 'true' - name: cassandra-3.0 + description: | + Instruments the Cassandra database client, providing database client spans and metrics for Cassandra queries. source_path: instrumentation/cassandra/cassandra-3.0 scope: name: io.opentelemetry.cassandra-3.0 target_versions: javaagent: - com.datastax.cassandra:cassandra-driver-core:[3.0,4.0) + configurations: + - name: otel.instrumentation.common.db-statement-sanitizer.enabled + description: Enables or disables statement sanitization for database queries. + default: 'true' clickhouse: - name: clickhouse-client-0.5 description: Instruments the V1 ClickHouseClient, providing database client spans @@ -271,6 +289,10 @@ libraries: target_versions: javaagent: - com.clickhouse.client:clickhouse-client:[0.5.0,) + configurations: + - name: otel.instrumentation.common.db-statement-sanitizer.enabled + description: Enables or disables statement sanitization for database queries. + default: 'true' couchbase: - name: couchbase-3.1.6 source_path: instrumentation/couchbase/couchbase-3.1.6 @@ -382,6 +404,8 @@ libraries: - org.elasticsearch:elasticsearch:[5.3.0,6.0.0) executors: - name: executors + description: | + The executor instrumentation ensures that context is automatically carried across threads by wrapping common Java executors (e.g., Executor, ExecutorService, ForkJoinPool). When a task is submitted, the current context is captured and bound to the task. Then, when the task eventually runs, even if it’s on a different thread, the instrumentation reactivates that context, enabling consistent correlation across concurrent and asynchronous workflows. source_path: instrumentation/executors scope: name: io.opentelemetry.executors @@ -708,6 +732,8 @@ libraries: - org.jboss.logmanager:jboss-logmanager:[1.1.0.GA,) jdbc: - name: jdbc + description: | + Traces JDBC operations such as statements, batches, commits, and rollbacks by injecting byte‑code into JDBC drivers and common connection‑pool proxies. Each call produces a span named after the SQL verb, enriched with standard DB client attributes (system, database, operation, sanitized statement, peer address) and error details if an exception occurs. disabled_by_default: true source_path: instrumentation/jdbc scope: @@ -715,6 +741,18 @@ libraries: target_versions: javaagent: - Java 8+ + configurations: + - name: otel.instrumentation.jdbc.statement-sanitizer.enabled + description: Enables or disables statement sanitization for database queries. + Takes precedent to otel.instrumentation.common.db-statement-sanitizer.enabled. + default: 'true' + - name: otel.instrumentation.common.db-statement-sanitizer.enabled + description: Enables or disables statement sanitization for database queries. + default: 'true' + - name: otel.instrumentation.common.peer-service-mapping + description: Used to specify a mapping from host names or IP addresses to peer + services. + default: '' jedis: - name: jedis-1.4 source_path: instrumentation/jedis/jedis-1.4 diff --git a/instrumentation-docs/build.gradle.kts b/instrumentation-docs/build.gradle.kts index 786807dfe18f..9c4e190e9dda 100644 --- a/instrumentation-docs/build.gradle.kts +++ b/instrumentation-docs/build.gradle.kts @@ -8,6 +8,7 @@ otelJava { dependencies { implementation("org.yaml:snakeyaml:2.4") + implementation("com.fasterxml.jackson.dataformat:jackson-dataformat-yaml:2.18.2") implementation("io.opentelemetry:opentelemetry-sdk-common") testImplementation(enforcedPlatform("org.junit:junit-bom:5.12.2")) diff --git a/instrumentation-docs/readme.md b/instrumentation-docs/readme.md index 07ea48a3b921..c36451b4a819 100644 --- a/instrumentation-docs/readme.md +++ b/instrumentation-docs/readme.md @@ -67,6 +67,9 @@ public class SpringWebInstrumentationModule extends InstrumentationModule * 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}` +* configurations settings + * List of settings that are available for the instrumentation module + * Each setting has a name, description, and default value ## Methodology @@ -81,6 +84,10 @@ As of now, the following fields are supported, all of which are optional: description: "Instruments..." # Description of the instrumentation module disabled_by_default: true # Defaults to `false` classification: internal # instrumentation classification: library | internal | custom +configurations: + - name: otel.instrumentation.common.db-statement-sanitizer.enabled + description: Enables or disables statement sanitization for database queries. + default: true ``` ### Gradle File Derived Information 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 0b35d6a3225f..44a38ab8bea9 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,6 +5,9 @@ package io.opentelemetry.instrumentation.docs; +import static java.util.Locale.Category.FORMAT; + +import com.fasterxml.jackson.core.JsonProcessingException; import io.opentelemetry.instrumentation.docs.internal.InstrumentationModule; import io.opentelemetry.instrumentation.docs.utils.FileManager; import io.opentelemetry.instrumentation.docs.utils.YamlHelper; @@ -14,13 +17,16 @@ import java.nio.file.Files; import java.nio.file.Paths; import java.util.List; +import java.util.Locale; +import java.util.TreeMap; import java.util.logging.Logger; +import java.util.stream.Collectors; public class DocGeneratorApplication { private static final Logger logger = Logger.getLogger(DocGeneratorApplication.class.getName()); - public static void main(String[] args) { + public static void main(String[] args) throws JsonProcessingException { FileManager fileManager = new FileManager("instrumentation/"); List modules = new InstrumentationAnalyzer(fileManager).analyze(); @@ -35,6 +41,67 @@ public static void main(String[] args) { } catch (IOException e) { logger.severe("Error writing instrumentation list: " + e.getMessage()); } + + printStats(modules); + } + + private static void printStats(List modules) { + List metadata = + modules.stream().filter(m -> m.getMetadata() != null).toList(); + + long withDescriptions = + metadata.stream() + .filter( + m -> + m.getMetadata().getDescription() != null + && !m.getMetadata().getDescription().isEmpty()) + .count(); + + long withConfigurations = + metadata.stream().filter(m -> !m.getMetadata().getConfigurations().isEmpty()).count(); + + String stats = + String.format( + Locale.getDefault(FORMAT), + """ + ----------------------------------- + Analysis Summary: + Total Modules: %d + By classification: + %s + metadata.yaml contents: + %s + %s + """, + modules.size(), + getClassificationStats(modules), + getPercentage("descriptions", withDescriptions, modules.size()), + getPercentage("configurations", withConfigurations, modules.size())); + + logger.info(stats); + } + + private static String getClassificationStats(List modules) { + return modules.stream() + .collect( + Collectors.groupingBy( + m -> m.getMetadata().getClassification(), TreeMap::new, Collectors.toList())) + .entrySet() + .stream() + .map( + entry -> + String.format( + Locale.getDefault(FORMAT), "\t%s: %d", entry.getKey(), entry.getValue().size())) + .collect(Collectors.joining("\n")); + } + + private static String getPercentage(String label, long numerator, long denominator) { + return label + + ": " + + numerator + + " (" + + String.format(Locale.getDefault(FORMAT), "%.2f", (double) numerator / denominator * 100) + + "%)"; } private DocGeneratorApplication() {} 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 358c9ae729a4..e47f5b14e357 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 @@ -7,6 +7,7 @@ import static io.opentelemetry.instrumentation.docs.parsers.GradleParser.parseGradleFile; +import com.fasterxml.jackson.core.JsonProcessingException; import io.opentelemetry.instrumentation.docs.internal.DependencyInfo; import io.opentelemetry.instrumentation.docs.internal.InstrumentationModule; import io.opentelemetry.instrumentation.docs.internal.InstrumentationType; @@ -62,7 +63,7 @@ public static List convertToInstrumentationModules( * * @return a list of {@link InstrumentationModule} */ - List analyze() { + List analyze() throws JsonProcessingException { List paths = fileManager.getInstrumentationPaths(); List modules = convertToInstrumentationModules(paths); diff --git a/instrumentation-docs/src/main/java/io/opentelemetry/instrumentation/docs/internal/ConfigurationOption.java b/instrumentation-docs/src/main/java/io/opentelemetry/instrumentation/docs/internal/ConfigurationOption.java new file mode 100644 index 000000000000..f5f8dbf3399a --- /dev/null +++ b/instrumentation-docs/src/main/java/io/opentelemetry/instrumentation/docs/internal/ConfigurationOption.java @@ -0,0 +1,15 @@ +/* + * Copyright The OpenTelemetry Authors + * SPDX-License-Identifier: Apache-2.0 + */ + +package io.opentelemetry.instrumentation.docs.internal; + +import com.fasterxml.jackson.annotation.JsonProperty; + +/** + * This class is internal and is hence not for public use. Its APIs are unstable and can change at + * any time. + */ +public record ConfigurationOption( + String name, String description, @JsonProperty("default") String defaultValue) {} diff --git a/instrumentation-docs/src/main/java/io/opentelemetry/instrumentation/docs/internal/InstrumentationMetaData.java b/instrumentation-docs/src/main/java/io/opentelemetry/instrumentation/docs/internal/InstrumentationMetaData.java index 4ab81c8c8f15..48cd0dbd61c3 100644 --- a/instrumentation-docs/src/main/java/io/opentelemetry/instrumentation/docs/internal/InstrumentationMetaData.java +++ b/instrumentation-docs/src/main/java/io/opentelemetry/instrumentation/docs/internal/InstrumentationMetaData.java @@ -5,6 +5,9 @@ package io.opentelemetry.instrumentation.docs.internal; +import com.fasterxml.jackson.annotation.JsonProperty; +import java.util.Collections; +import java.util.List; import java.util.Objects; import javax.annotation.Nonnull; import javax.annotation.Nullable; @@ -15,16 +18,26 @@ */ public class InstrumentationMetaData { @Nullable private String description; - @Nullable private Boolean disabledByDefault; + + @JsonProperty("disabled_by_default") + @Nullable + private Boolean disabledByDefault; + private String classification; + private List configurations = Collections.emptyList(); + public InstrumentationMetaData() {} public InstrumentationMetaData( - String description, String classification, Boolean disabledByDefault) { + String description, + String classification, + Boolean disabledByDefault, + List configurations) { this.classification = classification; this.disabledByDefault = disabledByDefault; this.description = description; + this.configurations = Objects.requireNonNullElse(configurations, Collections.emptyList()); } @Nullable @@ -54,4 +67,12 @@ public void setClassification(@Nullable String classification) { public void setDisabledByDefault(@Nullable Boolean disabledByDefault) { this.disabledByDefault = disabledByDefault; } + + public List getConfigurations() { + return configurations; + } + + public void setConfigurations(@Nullable List configurations) { + this.configurations = Objects.requireNonNullElse(configurations, Collections.emptyList()); + } } 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 e1f58dae58a6..c0121e355a2f 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 @@ -5,6 +5,10 @@ package io.opentelemetry.instrumentation.docs.utils; +import com.fasterxml.jackson.core.JsonProcessingException; +import com.fasterxml.jackson.databind.ObjectMapper; +import com.fasterxml.jackson.dataformat.yaml.YAMLFactory; +import io.opentelemetry.instrumentation.docs.internal.ConfigurationOption; import io.opentelemetry.instrumentation.docs.internal.InstrumentationClassification; import io.opentelemetry.instrumentation.docs.internal.InstrumentationMetaData; import io.opentelemetry.instrumentation.docs.internal.InstrumentationModule; @@ -17,23 +21,13 @@ import java.util.logging.Logger; import java.util.stream.Collectors; import org.yaml.snakeyaml.DumperOptions; -import org.yaml.snakeyaml.TypeDescription; 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 { - TypeDescription customDescriptor = new TypeDescription(InstrumentationMetaData.class); - customDescriptor.substituteProperty( - "disabled_by_default", Boolean.class, "getDisabledByDefault", "setDisabledByDefault"); - customDescriptor.substituteProperty( - "classification", String.class, "getClassification", "setClassification"); - metaDataYaml.addTypeDescription(customDescriptor); - } + private static final ObjectMapper mapper = new ObjectMapper(new YAMLFactory()); public static void generateInstrumentationYaml( List list, BufferedWriter writer) { @@ -149,6 +143,18 @@ private static Map baseProperties(InstrumentationModule module) moduleMap.put("target_versions", targetVersions); } + if (module.getMetadata() != null && !module.getMetadata().getConfigurations().isEmpty()) { + List> configurations = new ArrayList<>(); + for (ConfigurationOption configuration : module.getMetadata().getConfigurations()) { + Map conf = new LinkedHashMap<>(); + conf.put("name", configuration.name()); + conf.put("description", configuration.description()); + conf.put("default", configuration.defaultValue()); + configurations.add(conf); + } + moduleMap.put("configurations", configurations); + } + return moduleMap; } @@ -158,8 +164,9 @@ private static Map getScopeMap(InstrumentationModule module) { return scopeMap; } - public static InstrumentationMetaData metaDataParser(String input) { - return metaDataYaml.loadAs(input, InstrumentationMetaData.class); + public static InstrumentationMetaData metaDataParser(String input) + throws JsonProcessingException { + return mapper.readValue(input, InstrumentationMetaData.class); } private YamlHelper() {} 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 13a33a585d3b..73118efa8947 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 @@ -7,6 +7,8 @@ import static org.assertj.core.api.Assertions.assertThat; +import com.fasterxml.jackson.core.JsonProcessingException; +import io.opentelemetry.instrumentation.docs.internal.ConfigurationOption; import io.opentelemetry.instrumentation.docs.internal.InstrumentationClassification; import io.opentelemetry.instrumentation.docs.internal.InstrumentationMetaData; import io.opentelemetry.instrumentation.docs.internal.InstrumentationModule; @@ -34,7 +36,8 @@ void testPrintInstrumentationList() throws Exception { new InstrumentationMetaData( "Spring Web 6.0 instrumentation", InstrumentationClassification.LIBRARY.toString(), - true); + true, + null); modules.add( new InstrumentationModule.Builder() @@ -104,7 +107,12 @@ void testGenerateInstrumentationYamlSeparatesClassifications() throws Exception new InstrumentationMetaData( "Spring Web 6.0 instrumentation", InstrumentationClassification.LIBRARY.toString(), - false); + false, + List.of( + new ConfigurationOption( + "otel.instrumentation.spring-web-6.0.enabled", + "Enables or disables Spring Web 6.0 instrumentation.", + "true"))); modules.add( new InstrumentationModule.Builder() @@ -118,7 +126,8 @@ void testGenerateInstrumentationYamlSeparatesClassifications() throws Exception .build()); InstrumentationMetaData internalMetadata = - new InstrumentationMetaData(null, InstrumentationClassification.INTERNAL.toString(), null); + new InstrumentationMetaData( + null, InstrumentationClassification.INTERNAL.toString(), null, null); modules.add( new InstrumentationModule.Builder() @@ -131,7 +140,8 @@ void testGenerateInstrumentationYamlSeparatesClassifications() throws Exception .build()); InstrumentationMetaData customMetadata = - new InstrumentationMetaData(null, InstrumentationClassification.CUSTOM.toString(), null); + new InstrumentationMetaData( + null, InstrumentationClassification.CUSTOM.toString(), null, null); Map> externalAnnotationsVersions = Map.of( @@ -167,6 +177,10 @@ void testGenerateInstrumentationYamlSeparatesClassifications() throws Exception target_versions: javaagent: - org.springframework:spring-web:[6.0.0,) + configurations: + - name: otel.instrumentation.spring-web-6.0.enabled + description: Enables or disables Spring Web 6.0 instrumentation. + default: 'true' internal: - name: internal-application-logger source_path: instrumentation/internal/internal-application-logger @@ -186,43 +200,81 @@ void testGenerateInstrumentationYamlSeparatesClassifications() throws Exception } @Test - void testMetadataParser() { + void testMetadataParser() throws JsonProcessingException { String input = """ description: test description classification: internal disabled_by_default: true + configurations: + - name: otel.instrumentation.common.db-statement-sanitizer.enabled + description: Enables or disables statement sanitization for database queries. + default: true """; InstrumentationMetaData metadata = YamlHelper.metaDataParser(input); + + ConfigurationOption config = metadata.getConfigurations().get(0); + assertThat(config.name()) + .isEqualTo("otel.instrumentation.common.db-statement-sanitizer.enabled"); + assertThat(config.description()) + .isEqualTo("Enables or disables statement sanitization for database queries."); + assertThat(config.defaultValue()).isEqualTo("true"); + assertThat(metadata.getClassification()).isEqualTo(InstrumentationClassification.INTERNAL); assertThat(metadata.getDescription()).isEqualTo("test description"); assertThat(metadata.getDisabledByDefault()).isEqualTo(true); } @Test - void testMetadataParserWithOnlyLibraryEntry() { + void testMetadataParserWithOnlyLibraryEntry() throws JsonProcessingException { String input = "classification: internal"; InstrumentationMetaData metadata = YamlHelper.metaDataParser(input); assertThat(metadata.getClassification()).isEqualTo(InstrumentationClassification.INTERNAL); assertThat(metadata.getDescription()).isNull(); assertThat(metadata.getDisabledByDefault()).isFalse(); + assertThat(metadata.getConfigurations()).isEmpty(); } @Test - void testMetadataParserWithOnlyDescription() { + void testMetadataParserWithOnlyDescription() throws JsonProcessingException { String input = "description: false"; InstrumentationMetaData metadata = YamlHelper.metaDataParser(input); assertThat(metadata.getClassification()).isEqualTo(InstrumentationClassification.LIBRARY); assertThat(metadata.getDisabledByDefault()).isFalse(); + assertThat(metadata.getConfigurations()).isEmpty(); } @Test - void testMetadataParserWithOnlyDisabledByDefault() { + void testMetadataParserWithOnlyDisabledByDefault() throws JsonProcessingException { String input = "disabled_by_default: true"; InstrumentationMetaData metadata = YamlHelper.metaDataParser(input); assertThat(metadata.getClassification()).isEqualTo(InstrumentationClassification.LIBRARY); assertThat(metadata.getDescription()).isNull(); assertThat(metadata.getDisabledByDefault()).isTrue(); + assertThat(metadata.getConfigurations()).isEmpty(); + } + + @Test + void testMetadataParserWithOnlyConfigurations() throws JsonProcessingException { + String input = + """ + configurations: + - name: otel.instrumentation.common.db-statement-sanitizer.enabled + description: Enables or disables statement sanitization for database queries. + default: true + """; + InstrumentationMetaData metadata = YamlHelper.metaDataParser(input); + ConfigurationOption config = metadata.getConfigurations().get(0); + + assertThat(metadata.getClassification()).isEqualTo(InstrumentationClassification.LIBRARY); + assertThat(metadata.getDescription()).isNull(); + assertThat(metadata.getDisabledByDefault()).isFalse(); + + assertThat(config.name()) + .isEqualTo("otel.instrumentation.common.db-statement-sanitizer.enabled"); + assertThat(config.description()) + .isEqualTo("Enables or disables statement sanitization for database queries."); + assertThat(config.defaultValue()).isEqualTo("true"); } } diff --git a/instrumentation/cassandra/cassandra-3.0/metadata.yaml b/instrumentation/cassandra/cassandra-3.0/metadata.yaml new file mode 100644 index 000000000000..f6913cceb65b --- /dev/null +++ b/instrumentation/cassandra/cassandra-3.0/metadata.yaml @@ -0,0 +1,7 @@ +description: > + Instruments the Cassandra database client, providing database client spans and metrics for + Cassandra queries. +configurations: + - name: otel.instrumentation.common.db-statement-sanitizer.enabled + description: Enables or disables statement sanitization for database queries. + default: true diff --git a/instrumentation/cassandra/cassandra-4.0/metadata.yaml b/instrumentation/cassandra/cassandra-4.0/metadata.yaml new file mode 100644 index 000000000000..f6913cceb65b --- /dev/null +++ b/instrumentation/cassandra/cassandra-4.0/metadata.yaml @@ -0,0 +1,7 @@ +description: > + Instruments the Cassandra database client, providing database client spans and metrics for + Cassandra queries. +configurations: + - name: otel.instrumentation.common.db-statement-sanitizer.enabled + description: Enables or disables statement sanitization for database queries. + default: true diff --git a/instrumentation/cassandra/cassandra-4.4/metadata.yaml b/instrumentation/cassandra/cassandra-4.4/metadata.yaml new file mode 100644 index 000000000000..f6913cceb65b --- /dev/null +++ b/instrumentation/cassandra/cassandra-4.4/metadata.yaml @@ -0,0 +1,7 @@ +description: > + Instruments the Cassandra database client, providing database client spans and metrics for + Cassandra queries. +configurations: + - name: otel.instrumentation.common.db-statement-sanitizer.enabled + description: Enables or disables statement sanitization for database queries. + default: true diff --git a/instrumentation/clickhouse-client-0.5/metadata.yaml b/instrumentation/clickhouse-client-0.5/metadata.yaml index 2b640cdc8e52..49880547a235 100644 --- a/instrumentation/clickhouse-client-0.5/metadata.yaml +++ b/instrumentation/clickhouse-client-0.5/metadata.yaml @@ -1 +1,5 @@ description: Instruments the V1 ClickHouseClient, providing database client spans and metrics. +configurations: + - name: otel.instrumentation.common.db-statement-sanitizer.enabled + description: Enables or disables statement sanitization for database queries. + default: true diff --git a/instrumentation/jdbc/metadata.yaml b/instrumentation/jdbc/metadata.yaml index 1aee203e711b..198cde7a3cd2 100644 --- a/instrumentation/jdbc/metadata.yaml +++ b/instrumentation/jdbc/metadata.yaml @@ -1 +1,17 @@ disabled_by_default: true +description: > + Traces JDBC operations such as statements, batches, commits, and rollbacks by injecting byte‑code + into JDBC drivers and common connection‑pool proxies. Each call produces a span named after the + SQL verb, enriched with standard DB client attributes (system, database, operation, sanitized + statement, peer address) and error details if an exception occurs. +configurations: + - name: otel.instrumentation.jdbc.statement-sanitizer.enabled + description: Enables or disables statement sanitization for database queries. Takes precedent to + otel.instrumentation.common.db-statement-sanitizer.enabled. + default: true + - name: otel.instrumentation.common.db-statement-sanitizer.enabled + description: Enables or disables statement sanitization for database queries. + default: true + - name: otel.instrumentation.common.peer-service-mapping + description: Used to specify a mapping from host names or IP addresses to peer services. + default: "" From f2721a69291aa460e3c8db1ce2a49878023c6d43 Mon Sep 17 00:00:00 2001 From: Jay DeLuca Date: Mon, 21 Apr 2025 17:11:18 -0400 Subject: [PATCH 3/6] code review updates, add more config optinos --- docs/instrumentation-list.yaml | 11 +++++++++-- instrumentation/executors/metadata.yaml | 15 +++++++++++---- instrumentation/jdbc/metadata.yaml | 7 +++---- 3 files changed, 23 insertions(+), 10 deletions(-) diff --git a/docs/instrumentation-list.yaml b/docs/instrumentation-list.yaml index 7cbd943f7ddc..f6132ebe7010 100644 --- a/docs/instrumentation-list.yaml +++ b/docs/instrumentation-list.yaml @@ -405,13 +405,20 @@ libraries: executors: - name: executors description: | - The executor instrumentation ensures that context is automatically carried across threads by wrapping common Java executors (e.g., Executor, ExecutorService, ForkJoinPool). When a task is submitted, the current context is captured and bound to the task. Then, when the task eventually runs, even if it’s on a different thread, the instrumentation reactivates that context, enabling consistent correlation across concurrent and asynchronous workflows. + The executor instrumentation ensures that context is automatically carried across threads by instrumenting common Java executors (e.g., Executor, ExecutorService, ForkJoinPool). When a task is submitted, the current context is captured and bound to the task. When the task eventually runs, the instrumentation reactivates that context, even if it’s on a different thread. source_path: instrumentation/executors scope: name: io.opentelemetry.executors target_versions: javaagent: - Java 8+ + configurations: + - name: otel.instrumentation.executors.include + description: List of Executor subclasses to be instrumented. + default: '' + - name: otel.instrumentation.executors.include-all + description: Whether to instrument all classes that implement the Executor interface. + default: 'false' finagle: - name: finagle-http-23.11 source_path: instrumentation/finagle-http-23.11 @@ -733,7 +740,7 @@ libraries: jdbc: - name: jdbc description: | - Traces JDBC operations such as statements, batches, commits, and rollbacks by injecting byte‑code into JDBC drivers and common connection‑pool proxies. Each call produces a span named after the SQL verb, enriched with standard DB client attributes (system, database, operation, sanitized statement, peer address) and error details if an exception occurs. + Traces JDBC operations, where instrumented calls produce spans named after the SQL verb, enriched with standard DB client attributes (system, database, operation, sanitized statement, peer address) and error details if an exception occurs. disabled_by_default: true source_path: instrumentation/jdbc scope: diff --git a/instrumentation/executors/metadata.yaml b/instrumentation/executors/metadata.yaml index b0a75d3baeb6..daee5bfcd20a 100644 --- a/instrumentation/executors/metadata.yaml +++ b/instrumentation/executors/metadata.yaml @@ -1,6 +1,13 @@ description: > The executor instrumentation ensures that context is automatically carried across threads by - wrapping common Java executors (e.g., Executor, ExecutorService, ForkJoinPool). When a task is - submitted, the current context is captured and bound to the task. Then, when the task eventually - runs, even if it’s on a different thread, the instrumentation reactivates that context, enabling - consistent correlation across concurrent and asynchronous workflows. + instrumenting common Java executors (e.g., Executor, ExecutorService, ForkJoinPool). When a task + is submitted, the current context is captured and bound to the task. When the task eventually + runs, the instrumentation reactivates that context, even if it’s on a different thread. + +configurations: + - name: otel.instrumentation.executors.include + description: List of Executor subclasses to be instrumented. + default: "" + - name: otel.instrumentation.executors.include-all + description: Whether to instrument all classes that implement the Executor interface. + default: false diff --git a/instrumentation/jdbc/metadata.yaml b/instrumentation/jdbc/metadata.yaml index 198cde7a3cd2..244b4f9e92ea 100644 --- a/instrumentation/jdbc/metadata.yaml +++ b/instrumentation/jdbc/metadata.yaml @@ -1,9 +1,8 @@ disabled_by_default: true description: > - Traces JDBC operations such as statements, batches, commits, and rollbacks by injecting byte‑code - into JDBC drivers and common connection‑pool proxies. Each call produces a span named after the - SQL verb, enriched with standard DB client attributes (system, database, operation, sanitized - statement, peer address) and error details if an exception occurs. + Traces JDBC operations, where instrumented calls produce spans named after the SQL verb, enriched + with standard DB client attributes (system, database, operation, sanitized statement, peer + address) and error details if an exception occurs. configurations: - name: otel.instrumentation.jdbc.statement-sanitizer.enabled description: Enables or disables statement sanitization for database queries. Takes precedent to From 863558a062a6c7a6b6673a9a328a66816d871353 Mon Sep 17 00:00:00 2001 From: Jay DeLuca Date: Fri, 25 Apr 2025 05:38:03 -0400 Subject: [PATCH 4/6] Update docs/instrumentation-list.yaml Co-authored-by: Lauri Tulmin --- docs/instrumentation-list.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/instrumentation-list.yaml b/docs/instrumentation-list.yaml index 7cbd943f7ddc..b3c591dfcce0 100644 --- a/docs/instrumentation-list.yaml +++ b/docs/instrumentation-list.yaml @@ -733,7 +733,7 @@ libraries: jdbc: - name: jdbc description: | - Traces JDBC operations such as statements, batches, commits, and rollbacks by injecting byte‑code into JDBC drivers and common connection‑pool proxies. Each call produces a span named after the SQL verb, enriched with standard DB client attributes (system, database, operation, sanitized statement, peer address) and error details if an exception occurs. + The JDBC instrumentation provides database client spans and metrics. Each call produces a span named after the SQL verb, enriched with standard DB client attributes (system, database, operation, sanitized statement, peer address) and error details if an exception occurs. disabled_by_default: true source_path: instrumentation/jdbc scope: From f5298a770e9c7853fc63ab80cf5fe9f1508f35bb Mon Sep 17 00:00:00 2001 From: Jay DeLuca Date: Fri, 25 Apr 2025 05:38:09 -0400 Subject: [PATCH 5/6] Update docs/instrumentation-list.yaml Co-authored-by: Lauri Tulmin --- docs/instrumentation-list.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/instrumentation-list.yaml b/docs/instrumentation-list.yaml index b3c591dfcce0..bc08bcd0200e 100644 --- a/docs/instrumentation-list.yaml +++ b/docs/instrumentation-list.yaml @@ -405,7 +405,7 @@ libraries: executors: - name: executors description: | - The executor instrumentation ensures that context is automatically carried across threads by wrapping common Java executors (e.g., Executor, ExecutorService, ForkJoinPool). When a task is submitted, the current context is captured and bound to the task. Then, when the task eventually runs, even if it’s on a different thread, the instrumentation reactivates that context, enabling consistent correlation across concurrent and asynchronous workflows. + The executor instrumentation ensures that context is automatically propagated when using common Java executors (e.g., ThreadPoolExecutor, ScheduledThreadPoolExecutor, ForkJoinPool). When a task is submitted, the current context is captured and bound to the task. Then, when the task eventually runs, even if it’s on a different thread, the instrumentation reactivates that context, enabling consistent correlation across concurrent and asynchronous workflows. source_path: instrumentation/executors scope: name: io.opentelemetry.executors From 00f12931c6b891b539f99746d6141b2c985f125a Mon Sep 17 00:00:00 2001 From: Jay DeLuca Date: Fri, 25 Apr 2025 05:42:58 -0400 Subject: [PATCH 6/6] code review updates --- docs/instrumentation-list.yaml | 18 +++++++++--------- instrumentation-docs/readme.md | 2 +- .../docs/utils/YamlHelperTest.java | 8 ++++---- .../cassandra/cassandra-3.0/metadata.yaml | 2 +- .../cassandra/cassandra-4.0/metadata.yaml | 2 +- .../cassandra/cassandra-4.4/metadata.yaml | 2 +- .../clickhouse-client-0.5/metadata.yaml | 2 +- instrumentation/executors/metadata.yaml | 9 +++++---- instrumentation/jdbc/metadata.yaml | 10 +++++----- 9 files changed, 28 insertions(+), 27 deletions(-) diff --git a/docs/instrumentation-list.yaml b/docs/instrumentation-list.yaml index f6132ebe7010..f5fe3ecf4075 100644 --- a/docs/instrumentation-list.yaml +++ b/docs/instrumentation-list.yaml @@ -249,7 +249,7 @@ libraries: - com.datastax.oss:java-driver-core:[4.0,4.4) configurations: - name: otel.instrumentation.common.db-statement-sanitizer.enabled - description: Enables or disables statement sanitization for database queries. + description: Enables statement sanitization for database queries. default: 'true' - name: cassandra-4.4 description: | @@ -264,7 +264,7 @@ libraries: - com.datastax.oss:java-driver-core:4.4.0 configurations: - name: otel.instrumentation.common.db-statement-sanitizer.enabled - description: Enables or disables statement sanitization for database queries. + description: Enables statement sanitization for database queries. default: 'true' - name: cassandra-3.0 description: | @@ -277,7 +277,7 @@ libraries: - com.datastax.cassandra:cassandra-driver-core:[3.0,4.0) configurations: - name: otel.instrumentation.common.db-statement-sanitizer.enabled - description: Enables or disables statement sanitization for database queries. + description: Enables statement sanitization for database queries. default: 'true' clickhouse: - name: clickhouse-client-0.5 @@ -291,7 +291,7 @@ libraries: - com.clickhouse.client:clickhouse-client:[0.5.0,) configurations: - name: otel.instrumentation.common.db-statement-sanitizer.enabled - description: Enables or disables statement sanitization for database queries. + description: Enables statement sanitization for database queries. default: 'true' couchbase: - name: couchbase-3.1.6 @@ -405,7 +405,7 @@ libraries: executors: - name: executors description: | - The executor instrumentation ensures that context is automatically carried across threads by instrumenting common Java executors (e.g., Executor, ExecutorService, ForkJoinPool). When a task is submitted, the current context is captured and bound to the task. When the task eventually runs, the instrumentation reactivates that context, even if it’s on a different thread. + The executor instrumentation ensures that context is automatically propagated when using common Java executors (e.g., ThreadPoolExecutor, ScheduledThreadPoolExecutor, ForkJoinPool). When a task is submitted, the current context is captured and bound to the task. Then, when the task eventually runs, even if it’s on a different thread, the instrumentation reactivates that context, enabling consistent correlation across concurrent and asynchronous workflows. source_path: instrumentation/executors scope: name: io.opentelemetry.executors @@ -740,7 +740,7 @@ libraries: jdbc: - name: jdbc description: | - Traces JDBC operations, where instrumented calls produce spans named after the SQL verb, enriched with standard DB client attributes (system, database, operation, sanitized statement, peer address) and error details if an exception occurs. + The JDBC instrumentation provides database client spans and metrics. Each call produces a span named after the SQL verb, enriched with standard DB client attributes (system, database, operation, sanitized statement, peer address) and error details if an exception occurs. disabled_by_default: true source_path: instrumentation/jdbc scope: @@ -750,11 +750,11 @@ libraries: - Java 8+ configurations: - name: otel.instrumentation.jdbc.statement-sanitizer.enabled - description: Enables or disables statement sanitization for database queries. - Takes precedent to otel.instrumentation.common.db-statement-sanitizer.enabled. + description: Enables statement sanitization for database queries. Takes precedent + to otel.instrumentation.common.db-statement-sanitizer.enabled. default: 'true' - name: otel.instrumentation.common.db-statement-sanitizer.enabled - description: Enables or disables statement sanitization for database queries. + description: Enables statement sanitization for database queries. default: 'true' - name: otel.instrumentation.common.peer-service-mapping description: Used to specify a mapping from host names or IP addresses to peer diff --git a/instrumentation-docs/readme.md b/instrumentation-docs/readme.md index c36451b4a819..287af44c8815 100644 --- a/instrumentation-docs/readme.md +++ b/instrumentation-docs/readme.md @@ -86,7 +86,7 @@ disabled_by_default: true # Defaults to `false` classification: internal # instrumentation classification: library | internal | custom configurations: - name: otel.instrumentation.common.db-statement-sanitizer.enabled - description: Enables or disables statement sanitization for database queries. + description: Enables statement sanitization for database queries. default: true ``` 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 73118efa8947..dd3248f902c9 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 @@ -208,7 +208,7 @@ void testMetadataParser() throws JsonProcessingException { disabled_by_default: true configurations: - name: otel.instrumentation.common.db-statement-sanitizer.enabled - description: Enables or disables statement sanitization for database queries. + description: Enables statement sanitization for database queries. default: true """; @@ -218,7 +218,7 @@ void testMetadataParser() throws JsonProcessingException { assertThat(config.name()) .isEqualTo("otel.instrumentation.common.db-statement-sanitizer.enabled"); assertThat(config.description()) - .isEqualTo("Enables or disables statement sanitization for database queries."); + .isEqualTo("Enables statement sanitization for database queries."); assertThat(config.defaultValue()).isEqualTo("true"); assertThat(metadata.getClassification()).isEqualTo(InstrumentationClassification.INTERNAL); @@ -261,7 +261,7 @@ void testMetadataParserWithOnlyConfigurations() throws JsonProcessingException { """ configurations: - name: otel.instrumentation.common.db-statement-sanitizer.enabled - description: Enables or disables statement sanitization for database queries. + description: Enables statement sanitization for database queries. default: true """; InstrumentationMetaData metadata = YamlHelper.metaDataParser(input); @@ -274,7 +274,7 @@ void testMetadataParserWithOnlyConfigurations() throws JsonProcessingException { assertThat(config.name()) .isEqualTo("otel.instrumentation.common.db-statement-sanitizer.enabled"); assertThat(config.description()) - .isEqualTo("Enables or disables statement sanitization for database queries."); + .isEqualTo("Enables statement sanitization for database queries."); assertThat(config.defaultValue()).isEqualTo("true"); } } diff --git a/instrumentation/cassandra/cassandra-3.0/metadata.yaml b/instrumentation/cassandra/cassandra-3.0/metadata.yaml index f6913cceb65b..d23ccb2d8c14 100644 --- a/instrumentation/cassandra/cassandra-3.0/metadata.yaml +++ b/instrumentation/cassandra/cassandra-3.0/metadata.yaml @@ -3,5 +3,5 @@ description: > Cassandra queries. configurations: - name: otel.instrumentation.common.db-statement-sanitizer.enabled - description: Enables or disables statement sanitization for database queries. + description: Enables statement sanitization for database queries. default: true diff --git a/instrumentation/cassandra/cassandra-4.0/metadata.yaml b/instrumentation/cassandra/cassandra-4.0/metadata.yaml index f6913cceb65b..d23ccb2d8c14 100644 --- a/instrumentation/cassandra/cassandra-4.0/metadata.yaml +++ b/instrumentation/cassandra/cassandra-4.0/metadata.yaml @@ -3,5 +3,5 @@ description: > Cassandra queries. configurations: - name: otel.instrumentation.common.db-statement-sanitizer.enabled - description: Enables or disables statement sanitization for database queries. + description: Enables statement sanitization for database queries. default: true diff --git a/instrumentation/cassandra/cassandra-4.4/metadata.yaml b/instrumentation/cassandra/cassandra-4.4/metadata.yaml index f6913cceb65b..d23ccb2d8c14 100644 --- a/instrumentation/cassandra/cassandra-4.4/metadata.yaml +++ b/instrumentation/cassandra/cassandra-4.4/metadata.yaml @@ -3,5 +3,5 @@ description: > Cassandra queries. configurations: - name: otel.instrumentation.common.db-statement-sanitizer.enabled - description: Enables or disables statement sanitization for database queries. + description: Enables statement sanitization for database queries. default: true diff --git a/instrumentation/clickhouse-client-0.5/metadata.yaml b/instrumentation/clickhouse-client-0.5/metadata.yaml index 49880547a235..7d7d861c1977 100644 --- a/instrumentation/clickhouse-client-0.5/metadata.yaml +++ b/instrumentation/clickhouse-client-0.5/metadata.yaml @@ -1,5 +1,5 @@ description: Instruments the V1 ClickHouseClient, providing database client spans and metrics. configurations: - name: otel.instrumentation.common.db-statement-sanitizer.enabled - description: Enables or disables statement sanitization for database queries. + description: Enables statement sanitization for database queries. default: true diff --git a/instrumentation/executors/metadata.yaml b/instrumentation/executors/metadata.yaml index daee5bfcd20a..a016bc70a899 100644 --- a/instrumentation/executors/metadata.yaml +++ b/instrumentation/executors/metadata.yaml @@ -1,8 +1,9 @@ description: > - The executor instrumentation ensures that context is automatically carried across threads by - instrumenting common Java executors (e.g., Executor, ExecutorService, ForkJoinPool). When a task - is submitted, the current context is captured and bound to the task. When the task eventually - runs, the instrumentation reactivates that context, even if it’s on a different thread. + The executor instrumentation ensures that context is automatically propagated when using common + Java executors (e.g., ThreadPoolExecutor, ScheduledThreadPoolExecutor, ForkJoinPool). When a task + is submitted, the current context is captured and bound to the task. Then, when the task + eventually runs, even if it’s on a different thread, the instrumentation reactivates that context, + enabling consistent correlation across concurrent and asynchronous workflows. configurations: - name: otel.instrumentation.executors.include diff --git a/instrumentation/jdbc/metadata.yaml b/instrumentation/jdbc/metadata.yaml index 244b4f9e92ea..e52ce68e1aef 100644 --- a/instrumentation/jdbc/metadata.yaml +++ b/instrumentation/jdbc/metadata.yaml @@ -1,15 +1,15 @@ disabled_by_default: true description: > - Traces JDBC operations, where instrumented calls produce spans named after the SQL verb, enriched - with standard DB client attributes (system, database, operation, sanitized statement, peer - address) and error details if an exception occurs. + The JDBC instrumentation provides database client spans and metrics. Each call produces a span + named after the SQL verb, enriched with standard DB client attributes (system, database, + operation, sanitized statement, peer address) and error details if an exception occurs. configurations: - name: otel.instrumentation.jdbc.statement-sanitizer.enabled - description: Enables or disables statement sanitization for database queries. Takes precedent to + description: Enables statement sanitization for database queries. Takes precedent to otel.instrumentation.common.db-statement-sanitizer.enabled. default: true - name: otel.instrumentation.common.db-statement-sanitizer.enabled - description: Enables or disables statement sanitization for database queries. + description: Enables statement sanitization for database queries. default: true - name: otel.instrumentation.common.peer-service-mapping description: Used to specify a mapping from host names or IP addresses to peer services.