Added JDBC db.query.parameter span attributes

instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/db/SqlClientAttributesExtractor.java

@@ -12,7 +12,9 @@
 import io.opentelemetry.context.Context;
 import io.opentelemetry.instrumentation.api.instrumenter.AttributesExtractor;
 import io.opentelemetry.instrumentation.api.internal.SemconvStability;
+import io.opentelemetry.semconv.AttributeKeyTemplate;
 import java.util.Collection;
+import java.util.Map;
 
 /**
  * Extractor of <a
@@ -38,6 +40,8 @@ public final class SqlClientAttributesExtractor<REQUEST, RESPONSE>
       AttributeKey.stringKey("db.collection.name");
   private static final AttributeKey<Long> DB_OPERATION_BATCH_SIZE =
       AttributeKey.longKey("db.operation.batch.size");
+  private static final AttributeKeyTemplate<String> DB_QUERY_PARAMETER =
+      AttributeKeyTemplate.stringKeyTemplate("db.query.parameter");
 
   /** Creates the SQL client attributes extractor with default configuration. */
   public static <REQUEST, RESPONSE> AttributesExtractor<REQUEST, RESPONSE> create(
@@ -58,14 +62,18 @@ public static <REQUEST, RESPONSE> SqlClientAttributesExtractorBuilder<REQUEST, R
 
   private final AttributeKey<String> oldSemconvTableAttribute;
   private final boolean statementSanitizationEnabled;
+  private final boolean captureQueryParameters;
 
   SqlClientAttributesExtractor(
       SqlClientAttributesGetter<REQUEST, RESPONSE> getter,
       AttributeKey<String> oldSemconvTableAttribute,
-      boolean statementSanitizationEnabled) {
+      boolean statementSanitizationEnabled,
+      boolean captureQueryParameters) {
     super(getter);
     this.oldSemconvTableAttribute = oldSemconvTableAttribute;
-    this.statementSanitizationEnabled = statementSanitizationEnabled;
+    // capturing query parameters disables statement sanitization
+    this.statementSanitizationEnabled = !captureQueryParameters && statementSanitizationEnabled;
+    this.captureQueryParameters = captureQueryParameters;
   }
 
   @Override
@@ -78,6 +86,9 @@ public void onStart(AttributesBuilder attributes, Context parentContext, REQUEST
       return;
     }
 
+    Long batchSize = getter.getBatchSize(request);
+    boolean isBatch = batchSize != null && batchSize > 1;
+
     if (SemconvStability.emitOldDatabaseSemconv()) {
       if (rawQueryTexts.size() == 1) { // for backcompat(?)
         String rawQueryText = rawQueryTexts.iterator().next();
@@ -95,8 +106,6 @@ public void onStart(AttributesBuilder attributes, Context parentContext, REQUEST
     }
 
     if (SemconvStability.emitStableDatabaseSemconv()) {
-      Long batchSize = getter.getBatchSize(request);
-      boolean isBatch = batchSize != null && batchSize > 1;
       if (isBatch) {
         internalSet(attributes, DB_OPERATION_BATCH_SIZE, batchSize);
       }
@@ -127,6 +136,20 @@ public void onStart(AttributesBuilder attributes, Context parentContext, REQUEST
         }
       }
     }
+
+    Map<String, String> queryParameters = getter.getQueryParameters(request);
+    setQueryParameters(attributes, isBatch, queryParameters);
+  }
+
+  private void setQueryParameters(
+      AttributesBuilder attributes, boolean isBatch, Map<String, String> queryParameters) {
+    if (captureQueryParameters && !isBatch && queryParameters != null) {
+      for (Map.Entry<String, String> entry : queryParameters.entrySet()) {
+        String key = entry.getKey();
+        String value = entry.getValue();
+        internalSet(attributes, DB_QUERY_PARAMETER.getAttributeKey(key), value);
+      }
+    }
   }
 
   // String.join is not available on android

instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/db/SqlClientAttributesExtractorBuilder.java

@@ -20,6 +20,7 @@ public final class SqlClientAttributesExtractorBuilder<REQUEST, RESPONSE> {
   final SqlClientAttributesGetter<REQUEST, RESPONSE> getter;
   AttributeKey<String> oldSemconvTableAttribute = DB_SQL_TABLE;
   boolean statementSanitizationEnabled = true;
+  boolean captureQueryParameters = false;
 
   SqlClientAttributesExtractorBuilder(SqlClientAttributesGetter<REQUEST, RESPONSE> getter) {
     this.getter = getter;
@@ -48,12 +49,27 @@ public SqlClientAttributesExtractorBuilder<REQUEST, RESPONSE> setStatementSaniti
     return this;
   }
 
+  /**
+   * Sets whether the query parameters should be captured as span attributes named {@code
+   * db.query.parameter.<key>}. Enabling this option disables the statement sanitization. Disabled
+   * by default.
+   *
+   * <p>WARNING: captured query parameters may contain sensitive information such as passwords,
+   * personally identifiable information or protected health info.
+   */
+  @CanIgnoreReturnValue
+  public SqlClientAttributesExtractorBuilder<REQUEST, RESPONSE> setCaptureQueryParameters(
+      boolean captureQueryParameters) {
+    this.captureQueryParameters = captureQueryParameters;
+    return this;
+  }
+
   /**
    * Returns a new {@link SqlClientAttributesExtractor} with the settings of this {@link
    * SqlClientAttributesExtractorBuilder}.
    */
   public AttributesExtractor<REQUEST, RESPONSE> build() {
     return new SqlClientAttributesExtractor<>(
-        getter, oldSemconvTableAttribute, statementSanitizationEnabled);
+        getter, oldSemconvTableAttribute, statementSanitizationEnabled, captureQueryParameters);
   }
 }

instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/db/SqlClientAttributesGetter.java

@@ -9,6 +9,8 @@
 import static java.util.Collections.singleton;
 
 import java.util.Collection;
+import java.util.Collections;
+import java.util.Map;
 import javax.annotation.Nullable;
 
 /**
@@ -66,4 +68,9 @@ default Collection<String> getRawQueryTexts(REQUEST request) {
   default Long getBatchSize(REQUEST request) {
     return null;
   }
+
+  // TODO: make this required to implement
+  default Map<String, String> getQueryParameters(REQUEST request) {
+    return Collections.emptyMap();
+  }
 }

instrumentation-api-incubator/src/test/java/io/opentelemetry/instrumentation/api/incubator/semconv/db/SqlClientAttributesExtractorTest.java

@@ -6,6 +6,7 @@
 package io.opentelemetry.instrumentation.api.incubator.semconv.db;
 
 import static io.opentelemetry.sdk.testing.assertj.OpenTelemetryAssertions.assertThat;
+import static io.opentelemetry.semconv.incubating.DbIncubatingAttributes.DB_QUERY_PARAMETER;
 import static java.util.Collections.emptySet;
 import static java.util.Collections.singleton;
 import static org.assertj.core.api.Assertions.entry;
@@ -62,6 +63,14 @@ public Long getBatchSize(Map<String, Object> map) {
       return read(map, "db.operation.batch.size", Long.class);
     }
 
+    @SuppressWarnings("unchecked")
+    @Override
+    public Map<String, String> getQueryParameters(Map<String, Object> map) {
+      Map<String, String> parameters =
+          (Map<String, String>) read(map, "db.query.parameter", Map.class);
+      return parameters != null ? parameters : Collections.emptyMap();
+    }
+
     protected String read(Map<String, Object> map, String key) {
       return read(map, key, String.class);
     }
@@ -387,4 +396,74 @@ void shouldIgnoreBatchSizeOne() {
 
     assertThat(endAttributes.build().isEmpty()).isTrue();
   }
+
+  @Test
+  void shouldExtractQueryParameters() {
+    // given
+    Map<String, Object> request = new HashMap<>();
+    request.put("db.name", "potatoes");
+    // a query with prepared parameters and parameters to sanitize
+    request.put(
+        "db.statement",
+        "SELECT col FROM table WHERE field1=? AND field2='A' AND field3=? AND field4=2");
+    // a prepared parameters map
+    Map<String, String> parameterMap = new HashMap<>();
+    parameterMap.put("0", "'a'");
+    parameterMap.put("1", "1");
+    request.put("db.query.parameter", parameterMap);
+
+    Context context = Context.root();
+
+    AttributesExtractor<Map<String, Object>, Void> underTest =
+        SqlClientAttributesExtractor.builder(new TestAttributesGetter())
+            .setCaptureQueryParameters(true)
+            .build();
+
+    // when
+    AttributesBuilder startAttributes = Attributes.builder();
+    underTest.onStart(startAttributes, context, request);
+
+    AttributesBuilder endAttributes = Attributes.builder();
+    underTest.onEnd(endAttributes, context, request, null, null);
+
+    String prefix = DB_QUERY_PARAMETER.getAttributeKey("").getKey();
+    Attributes queryParameterAttributes =
+        startAttributes.removeIf(attribute -> !attribute.getKey().startsWith(prefix)).build();
+
+    // then
+    assertThat(queryParameterAttributes)
+        .containsOnly(
+            entry(DB_QUERY_PARAMETER.getAttributeKey("0"), "'a'"),
+            entry(DB_QUERY_PARAMETER.getAttributeKey("1"), "1"));
+
+    assertThat(endAttributes.build().isEmpty()).isTrue();
+  }
+
+  @Test
+  void shouldNotExtractQueryParametersForBatch() {
+    // given
+    Map<String, Object> request = new HashMap<>();
+    request.put("db.name", "potatoes");
+    request.put("db.statements", singleton("INSERT INTO potato VALUES(?)"));
+    request.put("db.operation.batch.size", 2L);
+    request.put("db.query.parameter", Collections.singletonMap("0", "1"));
+
+    Context context = Context.root();
+
+    AttributesExtractor<Map<String, Object>, Void> underTest =
+        SqlClientAttributesExtractor.builder(new TestMultiAttributesGetter())
+            .setCaptureQueryParameters(true)
+            .build();
+
+    // when
+    AttributesBuilder startAttributes = Attributes.builder();
+    underTest.onStart(startAttributes, context, request);
+
+    AttributesBuilder endAttributes = Attributes.builder();
+    underTest.onEnd(endAttributes, context, request, null, null);
+
+    // then
+    assertThat(startAttributes.build()).doesNotContainKey(DB_QUERY_PARAMETER.getAttributeKey("0"));
+    assertThat(endAttributes.build().isEmpty()).isTrue();
+  }
 }

instrumentation/jdbc/README.md

@@ -1,6 +1,7 @@
 # Settings for the JDBC instrumentation
 
-| System property                                              | Type    | Default | Description                                                                              |
-|--------------------------------------------------------------|---------|---------|------------------------------------------------------------------------------------------|
-| `otel.instrumentation.jdbc.statement-sanitizer.enabled`      | Boolean | `true`  | Enables the DB statement sanitization.                                                   |
-| `otel.instrumentation.jdbc.experimental.transaction.enabled` | Boolean | `false` | Enables experimental instrumentation to create spans for COMMIT and ROLLBACK operations. |
+| System property                                              | Type    | Default | Description                                                                                                                                                                                                                                                                   |
+|--------------------------------------------------------------|---------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `otel.instrumentation.jdbc.statement-sanitizer.enabled`      | Boolean | `true`  | Enables the DB statement sanitization.                                                                                                                                                                                                                                        |
+| `otel.instrumentation.jdbc.capture-query-parameters`         | Boolean | `false` | Enable the capture of query parameters as span attributes. Enabling this option disables the statement sanitization. <p>WARNING: captured query parameters may contain sensitive information such as passwords, personally identifiable information or protected health info. |
+| `otel.instrumentation.jdbc.experimental.transaction.enabled` | Boolean | `false` | Enables experimental instrumentation to create spans for COMMIT and ROLLBACK operations.                                                                                                                                                                                      |

instrumentation/jdbc/javaagent/build.gradle.kts

@@ -65,13 +65,15 @@ tasks {
   test {
     filter {
       excludeTestsMatching("SlickTest")
+      excludeTestsMatching("PreparedStatementParametersTest")
     }
     jvmArgs("-Dotel.instrumentation.jdbc-datasource.enabled=true")
   }
 
   val testStableSemconv by registering(Test::class) {
     filter {
       excludeTestsMatching("SlickTest")
+      excludeTestsMatching("PreparedStatementParametersTest")
     }
     jvmArgs("-Dotel.instrumentation.jdbc-datasource.enabled=true")
     jvmArgs("-Dotel.semconv-stability.opt-in=database")
@@ -85,10 +87,18 @@ tasks {
     jvmArgs("-Dotel.semconv-stability.opt-in=database")
   }
 
+  val testCaptureParameters by registering(Test::class) {
+    filter {
+      includeTestsMatching("PreparedStatementParametersTest")
+    }
+    jvmArgs("-Dotel.instrumentation.jdbc.capture-query-parameters=true")
+  }
+
   check {
     dependsOn(testSlick)
     dependsOn(testStableSemconv)
     dependsOn(testSlickStableSemconv)
+    dependsOn(testCaptureParameters)
   }
 }
 

instrumentation/jdbc/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/jdbc/JdbcSingletons.java

@@ -25,13 +25,18 @@ public final class JdbcSingletons {
   private static final Instrumenter<DbRequest, Void> TRANSACTION_INSTRUMENTER;
   public static final Instrumenter<DataSource, DbInfo> DATASOURCE_INSTRUMENTER =
       createDataSourceInstrumenter(GlobalOpenTelemetry.get(), true);
+  public static final boolean CAPTURE_QUERY_PARAMETERS;
 
   static {
     JdbcNetworkAttributesGetter netAttributesGetter = new JdbcNetworkAttributesGetter();
     AttributesExtractor<DbRequest, Void> peerServiceExtractor =
         PeerServiceAttributesExtractor.create(
             netAttributesGetter, AgentCommonConfig.get().getPeerServiceResolver());
 
+    CAPTURE_QUERY_PARAMETERS =
+        AgentInstrumentationConfig.get()
+            .getBoolean("otel.instrumentation.jdbc.capture-query-parameters", false);
+
     STATEMENT_INSTRUMENTER =
         JdbcInstrumenterFactory.createStatementInstrumenter(
             GlobalOpenTelemetry.get(),
@@ -40,7 +45,8 @@ public final class JdbcSingletons {
             AgentInstrumentationConfig.get()
                 .getBoolean(
                     "otel.instrumentation.jdbc.statement-sanitizer.enabled",
-                    AgentCommonConfig.get().isStatementSanitizationEnabled()));
+                    AgentCommonConfig.get().isStatementSanitizationEnabled()),
+            CAPTURE_QUERY_PARAMETERS);
 
     TRANSACTION_INSTRUMENTER =
         JdbcInstrumenterFactory.createTransactionInstrumenter(