Implement stable database semantic conventions

instrumentation-api-incubator/build.gradle.kts

@@ -24,6 +24,41 @@ dependencies {
   testImplementation("io.opentelemetry.semconv:opentelemetry-semconv-incubating")
 }
 
+testing {
+  suites {
+    val testStableDatabaseSemconv by registering(JvmTestSuite::class) {
+      dependencies {
+        implementation(project())
+        implementation(project(":testing-common"))
+        implementation("io.opentelemetry:opentelemetry-sdk")
+        implementation("io.opentelemetry:opentelemetry-sdk-testing")
+      }
+      targets {
+        all {
+          testTask.configure {
+            jvmArgs("-Dotel.semconv-stability.opt-in=database")
+          }
+        }
+      }
+    }
+    val testBothDatabaseSemconv by registering(JvmTestSuite::class) {
+      dependencies {
+        implementation(project())
+        implementation(project(":testing-common"))
+        implementation("io.opentelemetry:opentelemetry-sdk")
+        implementation("io.opentelemetry:opentelemetry-sdk-testing")
+      }
+      targets {
+        all {
+          testTask.configure {
+            jvmArgs("-Dotel.semconv-stability.opt-in=database/dup")
+          }
+        }
+      }
+    }
+  }
+}
+
 tasks {
   // exclude auto-generated code
   named<Checkstyle>("checkstyleMain") {
@@ -40,4 +75,8 @@ tasks {
   sourcesJar {
     dependsOn("generateJflex")
   }
+
+  check {
+    dependsOn(testing.suites)
+  }
 }

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

@@ -11,6 +11,7 @@
 import io.opentelemetry.api.common.AttributesBuilder;
 import io.opentelemetry.context.Context;
 import io.opentelemetry.instrumentation.api.instrumenter.AttributesExtractor;
+import io.opentelemetry.instrumentation.api.internal.SemconvStability;
 
 /**
  * Extractor of <a
@@ -26,7 +27,11 @@ public final class DbClientAttributesExtractor<REQUEST, RESPONSE>
 
   // copied from DbIncubatingAttributes
   private static final AttributeKey<String> DB_STATEMENT = AttributeKey.stringKey("db.statement");
+  private static final AttributeKey<String> DB_QUERY_TEXT = AttributeKey.stringKey("db.query.text");
+
   private static final AttributeKey<String> DB_OPERATION = AttributeKey.stringKey("db.operation");
+  private static final AttributeKey<String> DB_OPERATION_NAME =
+      AttributeKey.stringKey("db.operation.name");
 
   /** Creates the database client attributes extractor with default configuration. */
   public static <REQUEST, RESPONSE> AttributesExtractor<REQUEST, RESPONSE> create(
@@ -38,11 +43,18 @@ public static <REQUEST, RESPONSE> AttributesExtractor<REQUEST, RESPONSE> create(
     super(getter);
   }
 
+  @SuppressWarnings("deprecation") // until old db semconv are dropped
   @Override
   public void onStart(AttributesBuilder attributes, Context parentContext, REQUEST request) {
     super.onStart(attributes, parentContext, request);
 
-    internalSet(attributes, DB_STATEMENT, getter.getStatement(request));
-    internalSet(attributes, DB_OPERATION, getter.getOperation(request));
+    if (SemconvStability.emitStableDatabaseSemconv()) {
+      internalSet(attributes, DB_QUERY_TEXT, getter.getDbQueryText(request));
+      internalSet(attributes, DB_OPERATION_NAME, getter.getDbOperationName(request));
+    }
+    if (SemconvStability.emitOldDatabaseSemconv()) {
+      internalSet(attributes, DB_STATEMENT, getter.getStatement(request));
+      internalSet(attributes, DB_OPERATION, getter.getOperation(request));
+    }
   }
 }

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

@@ -20,9 +20,23 @@
  */
 public interface DbClientAttributesGetter<REQUEST> extends DbClientCommonAttributesGetter<REQUEST> {
 
+  /**
+   * @deprecated Use {@link #getDbQueryText(REQUEST)} instead.
+   */
+  @Deprecated
   @Nullable
   String getStatement(REQUEST request);
 
+  @Nullable
+  String getDbQueryText(REQUEST request);
+
+  /**
+   * @deprecated Use {@link #getDbOperationName(REQUEST)} instead.
+   */
+  @Deprecated
   @Nullable
   String getOperation(REQUEST request);
+
+  @Nullable
+  String getDbOperationName(REQUEST request);
 }

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

@@ -11,6 +11,7 @@
 import io.opentelemetry.api.common.AttributesBuilder;
 import io.opentelemetry.context.Context;
 import io.opentelemetry.instrumentation.api.instrumenter.AttributesExtractor;
+import io.opentelemetry.instrumentation.api.internal.SemconvStability;
 import io.opentelemetry.instrumentation.api.internal.SpanKey;
 import io.opentelemetry.instrumentation.api.internal.SpanKeyProvider;
 import javax.annotation.Nullable;
@@ -21,6 +22,7 @@ abstract class DbClientCommonAttributesExtractor<
 
   // copied from DbIncubatingAttributes
   private static final AttributeKey<String> DB_NAME = AttributeKey.stringKey("db.name");
+  private static final AttributeKey<String> DB_NAMESPACE = AttributeKey.stringKey("db.namespace");
   private static final AttributeKey<String> DB_SYSTEM = AttributeKey.stringKey("db.system");
   private static final AttributeKey<String> DB_USER = AttributeKey.stringKey("db.user");
   private static final AttributeKey<String> DB_CONNECTION_STRING =
@@ -32,12 +34,18 @@ abstract class DbClientCommonAttributesExtractor<
     this.getter = getter;
   }
 
+  @SuppressWarnings("deprecation") // until old db semconv are dropped
   @Override
   public void onStart(AttributesBuilder attributes, Context parentContext, REQUEST request) {
+    if (SemconvStability.emitStableDatabaseSemconv()) {
+      internalSet(attributes, DB_NAMESPACE, getter.getDbNamespace(request));
+    }
+    if (SemconvStability.emitOldDatabaseSemconv()) {
+      internalSet(attributes, DB_USER, getter.getUser(request));
+      internalSet(attributes, DB_NAME, getter.getName(request));
+      internalSet(attributes, DB_CONNECTION_STRING, getter.getConnectionString(request));
+    }
     internalSet(attributes, DB_SYSTEM, getter.getSystem(request));
-    internalSet(attributes, DB_USER, getter.getUser(request));
-    internalSet(attributes, DB_NAME, getter.getName(request));
-    internalSet(attributes, DB_CONNECTION_STRING, getter.getConnectionString(request));
   }
 
   @Override

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

@@ -10,15 +10,28 @@
 /** An interface for getting attributes common to database clients. */
 public interface DbClientCommonAttributesGetter<REQUEST> {
 
+  @Deprecated
   @Nullable
   String getSystem(REQUEST request);
 
+  @Nullable
+  String getDbSystem(REQUEST request);
+
+  @Deprecated
   @Nullable
   String getUser(REQUEST request);
 
+  /**
+   * @deprecated Use {@link #getDbNamespace(Object)} instead.
+   */
+  @Deprecated
   @Nullable
   String getName(REQUEST request);
 
+  @Nullable
+  String getDbNamespace(REQUEST request);
+
+  @Deprecated
   @Nullable
   String getConnectionString(REQUEST request);
 }

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

@@ -13,8 +13,9 @@ public abstract class DbClientSpanNameExtractor<REQUEST> implements SpanNameExtr
    * Returns a {@link SpanNameExtractor} that constructs the span name according to DB semantic
    * conventions: {@code <db.operation> <db.name>}.
    *
-   * @see DbClientAttributesGetter#getOperation(Object) used to extract {@code <db.operation>}.
-   * @see DbClientAttributesGetter#getName(Object) used to extract {@code <db.name>}.
+   * @see DbClientAttributesGetter#getDbOperationName(Object) used to extract {@code
+   *     <db.operation.name>}.
+   * @see DbClientAttributesGetter#getDbNamespace(Object) used to extract {@code <db.namespace>}.
    */
   public static <REQUEST> SpanNameExtractor<REQUEST> create(
       DbClientAttributesGetter<REQUEST> getter) {
@@ -25,8 +26,8 @@ public static <REQUEST> SpanNameExtractor<REQUEST> create(
    * Returns a {@link SpanNameExtractor} that constructs the span name according to DB semantic
    * conventions: {@code <db.operation> <db.name>.<identifier>}.
    *
-   * @see SqlStatementInfo#getOperation() used to extract {@code <db.operation>}.
-   * @see DbClientAttributesGetter#getName(Object) used to extract {@code <db.name>}.
+   * @see SqlStatementInfo#getOperation() () used to extract {@code <db.operation>}.
+   * @see DbClientAttributesGetter#getDbNamespace(Object) used to extract {@code <db.namespace>}.
    * @see SqlStatementInfo#getMainIdentifier() used to extract {@code <db.table>} or stored
    *     procedure name.
    */
@@ -72,8 +73,8 @@ private GenericDbClientSpanNameExtractor(DbClientAttributesGetter<REQUEST> gette
 
     @Override
     public String extract(REQUEST request) {
-      String dbName = getter.getName(request);
-      String operation = getter.getOperation(request);
+      String dbName = getter.getDbNamespace(request);
+      String operation = getter.getDbOperationName(request);
       return computeSpanName(dbName, operation, null);
     }
   }
@@ -92,8 +93,8 @@ private SqlClientSpanNameExtractor(SqlClientAttributesGetter<REQUEST> getter) {
 
     @Override
     public String extract(REQUEST request) {
-      String dbName = getter.getName(request);
-      SqlStatementInfo sanitizedStatement = sanitizer.sanitize(getter.getRawStatement(request));
+      String dbName = getter.getDbNamespace(request);
+      SqlStatementInfo sanitizedStatement = sanitizer.sanitize(getter.getRawQueryText(request));
       return computeSpanName(
           dbName, sanitizedStatement.getOperation(), sanitizedStatement.getMainIdentifier());
     }

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

@@ -11,6 +11,7 @@
 import io.opentelemetry.api.common.AttributesBuilder;
 import io.opentelemetry.context.Context;
 import io.opentelemetry.instrumentation.api.instrumenter.AttributesExtractor;
+import io.opentelemetry.instrumentation.api.internal.SemconvStability;
 
 /**
  * Extractor of <a
@@ -19,7 +20,7 @@
  *
  * <p>It sets the same set of attributes as {@link DbClientAttributesExtractor} plus an additional
  * <code>db.sql.table</code> attribute. The raw SQL statements returned by the {@link
- * SqlClientAttributesGetter#getRawStatement(Object)} method are sanitized before use, all statement
+ * SqlClientAttributesGetter#getRawQueryText(Object)} method are sanitized before use, all statement
  * parameters are removed.
  */
 public final class SqlClientAttributesExtractor<REQUEST, RESPONSE>
@@ -28,7 +29,10 @@ public final class SqlClientAttributesExtractor<REQUEST, RESPONSE>
 
   // copied from DbIncubatingAttributes
   private static final AttributeKey<String> DB_OPERATION = AttributeKey.stringKey("db.operation");
+  private static final AttributeKey<String> DB_OPERATION_NAME =
+      AttributeKey.stringKey("db.operation.name");
   private static final AttributeKey<String> DB_STATEMENT = AttributeKey.stringKey("db.statement");
+  private static final AttributeKey<String> DB_QUERY_TEXT = AttributeKey.stringKey("db.query.text");
 
   /** Creates the SQL client attributes extractor with default configuration. */
   public static <REQUEST, RESPONSE> AttributesExtractor<REQUEST, RESPONSE> create(
@@ -61,18 +65,30 @@ public static <REQUEST, RESPONSE> SqlClientAttributesExtractorBuilder<REQUEST, R
     this.statementSanitizationEnabled = statementSanitizationEnabled;
   }
 
+  @SuppressWarnings("deprecation") // until old semconv are dropped
   @Override
   public void onStart(AttributesBuilder attributes, Context parentContext, REQUEST request) {
     super.onStart(attributes, parentContext, request);
 
-    String rawStatement = getter.getRawStatement(request);
+    String rawStatement =
+        SemconvStability.emitStableDatabaseSemconv()
+            ? getter.getRawQueryText(request)
+            : getter.getRawStatement(request);
     SqlStatementInfo sanitizedStatement = sanitizer.sanitize(rawStatement);
     String operation = sanitizedStatement.getOperation();
-    internalSet(
-        attributes,
-        DB_STATEMENT,
-        statementSanitizationEnabled ? sanitizedStatement.getFullStatement() : rawStatement);
-    internalSet(attributes, DB_OPERATION, operation);
+    if (SemconvStability.emitStableDatabaseSemconv()) {
+      internalSet(
+          attributes,
+          DB_QUERY_TEXT,
+          statementSanitizationEnabled ? sanitizedStatement.getFullStatement() : rawStatement);
+      internalSet(attributes, DB_OPERATION_NAME, operation);
+    } else if (SemconvStability.emitOldDatabaseSemconv()) {
+      internalSet(
+          attributes,
+          DB_STATEMENT,
+          statementSanitizationEnabled ? sanitizedStatement.getFullStatement() : rawStatement);
+      internalSet(attributes, DB_OPERATION, operation);
+    }
     if (!SQL_CALL.equals(operation)) {
       internalSet(attributes, dbTableAttribute, sanitizedStatement.getMainIdentifier());
     }

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

@@ -24,7 +24,13 @@ public interface SqlClientAttributesGetter<REQUEST>
   /**
    * Get the raw SQL statement. The value returned by this method is later sanitized by the {@link
    * SqlClientAttributesExtractor} before being set as span attribute.
+   *
+   * @deprecated Use {@link #getRawQueryText(Object)} instead.
    */
+  @Deprecated
   @Nullable
   String getRawStatement(REQUEST request);
+
+  @Nullable
+  String getRawQueryText(REQUEST request);
 }