Deprecate DbClientCommonAttributesGetter (#15139)

Author: trask

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

@@ -6,15 +6,22 @@
 package io.opentelemetry.instrumentation.api.incubator.semconv.db;
 
 import static io.opentelemetry.instrumentation.api.internal.AttributesExtractorUtil.internalSet;
+import static io.opentelemetry.semconv.DbAttributes.DB_NAMESPACE;
 import static io.opentelemetry.semconv.DbAttributes.DB_OPERATION_NAME;
 import static io.opentelemetry.semconv.DbAttributes.DB_QUERY_SUMMARY;
 import static io.opentelemetry.semconv.DbAttributes.DB_QUERY_TEXT;
+import static io.opentelemetry.semconv.DbAttributes.DB_RESPONSE_STATUS_CODE;
+import static io.opentelemetry.semconv.DbAttributes.DB_SYSTEM_NAME;
+import static io.opentelemetry.semconv.ErrorAttributes.ERROR_TYPE;
 
 import io.opentelemetry.api.common.AttributeKey;
 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;
 
 /**
  * Extractor of <a
@@ -25,12 +32,18 @@
  * attribute extraction from request/response objects.
  */
 public final class DbClientAttributesExtractor<REQUEST, RESPONSE>
-    extends DbClientCommonAttributesExtractor<
-        REQUEST, RESPONSE, DbClientAttributesGetter<REQUEST, RESPONSE>> {
+    implements AttributesExtractor<REQUEST, RESPONSE>, SpanKeyProvider {
 
   // copied from DbIncubatingAttributes
+  private static final AttributeKey<String> DB_NAME = AttributeKey.stringKey("db.name");
+  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 =
+      AttributeKey.stringKey("db.connection_string");
   private static final AttributeKey<String> DB_STATEMENT = AttributeKey.stringKey("db.statement");
-  static final AttributeKey<String> DB_OPERATION = AttributeKey.stringKey("db.operation");
+  private static final AttributeKey<String> DB_OPERATION = AttributeKey.stringKey("db.operation");
+
+  private final DbClientAttributesGetter<REQUEST, RESPONSE> getter;
 
   /** Creates the database client attributes extractor with default configuration. */
   public static <REQUEST, RESPONSE> AttributesExtractor<REQUEST, RESPONSE> create(
@@ -39,21 +52,71 @@ public static <REQUEST, RESPONSE> AttributesExtractor<REQUEST, RESPONSE> create(
   }
 
   DbClientAttributesExtractor(DbClientAttributesGetter<REQUEST, RESPONSE> getter) {
-    super(getter);
+    this.getter = getter;
   }
 
+  @SuppressWarnings("deprecation") // until old db semconv are dropped
   @Override
   public void onStart(AttributesBuilder attributes, Context parentContext, REQUEST request) {
-    super.onStart(attributes, parentContext, request);
+    onStartCommon(attributes, getter, request);
+  }
 
+  @SuppressWarnings("deprecation") // until old db semconv are dropped
+  static <REQUEST, RESPONSE> void onStartCommon(
+      AttributesBuilder attributes,
+      DbClientAttributesGetter<REQUEST, RESPONSE> getter,
+      REQUEST request) {
     if (SemconvStability.emitStableDatabaseSemconv()) {
+      internalSet(
+          attributes,
+          DB_SYSTEM_NAME,
+          SemconvStability.stableDbSystemName(getter.getDbSystem(request)));
+      internalSet(attributes, DB_NAMESPACE, getter.getDbNamespace(request));
       internalSet(attributes, DB_QUERY_TEXT, getter.getDbQueryText(request));
       internalSet(attributes, DB_OPERATION_NAME, getter.getDbOperationName(request));
       internalSet(attributes, DB_QUERY_SUMMARY, getter.getDbQuerySummary(request));
     }
     if (SemconvStability.emitOldDatabaseSemconv()) {
+      internalSet(attributes, DB_SYSTEM, getter.getDbSystem(request));
+      internalSet(attributes, DB_USER, getter.getUser(request));
+      internalSet(attributes, DB_NAME, getter.getDbNamespace(request));
+      internalSet(attributes, DB_CONNECTION_STRING, getter.getConnectionString(request));
       internalSet(attributes, DB_STATEMENT, getter.getDbQueryText(request));
       internalSet(attributes, DB_OPERATION, getter.getDbOperationName(request));
     }
   }
+
+  @Override
+  public void onEnd(
+      AttributesBuilder attributes,
+      Context context,
+      REQUEST request,
+      @Nullable RESPONSE response,
+      @Nullable Throwable error) {
+    onEndCommon(attributes, getter, response, error);
+  }
+
+  static <REQUEST, RESPONSE> void onEndCommon(
+      AttributesBuilder attributes,
+      DbClientAttributesGetter<REQUEST, RESPONSE> getter,
+      @Nullable RESPONSE response,
+      @Nullable Throwable error) {
+    if (SemconvStability.emitStableDatabaseSemconv()) {
+      if (error != null) {
+        internalSet(attributes, ERROR_TYPE, error.getClass().getName());
+      }
+      if (error != null || response != null) {
+        internalSet(attributes, DB_RESPONSE_STATUS_CODE, getter.getResponseStatus(response, error));
+      }
+    }
+  }
+
+  /**
+   * This method is internal and is hence not for public use. Its API is unstable and can change at
+   * any time.
+   */
+  @Override
+  public SpanKey internalGetSpanKey() {
+    return SpanKey.DB_CLIENT;
+  }
 }

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

@@ -18,6 +18,7 @@
  * from the attribute methods, but implement as many as possible for best compliance with the
  * OpenTelemetry specification.
  */
+@SuppressWarnings("deprecation") // extending deprecated interface for backward compatibility
 public interface DbClientAttributesGetter<REQUEST, RESPONSE>
     extends DbClientCommonAttributesGetter<REQUEST, RESPONSE> {
 

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

@@ -7,7 +7,12 @@
 
 import javax.annotation.Nullable;
 
-/** An interface for getting attributes common to database clients. */
+/**
+ * An interface for getting attributes common to database clients.
+ *
+ * @deprecated Use {@link DbClientAttributesGetter} instead.
+ */
+@Deprecated
 public interface DbClientCommonAttributesGetter<REQUEST, RESPONSE> {
 
   String getDbSystem(REQUEST request);

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

@@ -16,9 +16,12 @@
 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 io.opentelemetry.semconv.AttributeKeyTemplate;
 import java.util.Collection;
 import java.util.Map;
+import javax.annotation.Nullable;
 
 /**
  * Extractor of <a
@@ -31,8 +34,7 @@
  * statement parameters are removed.
  */
 public final class SqlClientAttributesExtractor<REQUEST, RESPONSE>
-    extends DbClientCommonAttributesExtractor<
-        REQUEST, RESPONSE, SqlClientAttributesGetter<REQUEST, RESPONSE>> {
+    implements AttributesExtractor<REQUEST, RESPONSE>, SpanKeyProvider {
 
   // copied from DbIncubatingAttributes
   private static final AttributeKey<String> DB_OPERATION = AttributeKey.stringKey("db.operation");
@@ -57,6 +59,7 @@ public static <REQUEST, RESPONSE> SqlClientAttributesExtractorBuilder<REQUEST, R
 
   private static final String SQL_CALL = "CALL";
 
+  private final SqlClientAttributesGetter<REQUEST, RESPONSE> getter;
   private final AttributeKey<String> oldSemconvTableAttribute;
   private final boolean statementSanitizationEnabled;
   private final boolean captureQueryParameters;
@@ -66,23 +69,18 @@ public static <REQUEST, RESPONSE> SqlClientAttributesExtractorBuilder<REQUEST, R
       AttributeKey<String> oldSemconvTableAttribute,
       boolean statementSanitizationEnabled,
       boolean captureQueryParameters) {
-    super(getter);
+    this.getter = getter;
     this.oldSemconvTableAttribute = oldSemconvTableAttribute;
     // capturing query parameters disables statement sanitization
     this.statementSanitizationEnabled = !captureQueryParameters && statementSanitizationEnabled;
     this.captureQueryParameters = captureQueryParameters;
   }
 
+  @SuppressWarnings("deprecation") // until old db semconv are dropped
   @Override
   public void onStart(AttributesBuilder attributes, Context parentContext, REQUEST request) {
-    super.onStart(attributes, parentContext, request);
-
     Collection<String> rawQueryTexts = getter.getRawQueryTexts(request);
 
-    if (rawQueryTexts.isEmpty()) {
-      return;
-    }
-
     Long batchSize = getter.getBatchSize(request);
     boolean isBatch = batchSize != null && batchSize > 1;
 
@@ -118,7 +116,7 @@ public void onStart(AttributesBuilder attributes, Context parentContext, REQUEST
         if (!SQL_CALL.equals(operation)) {
           internalSet(attributes, DB_COLLECTION_NAME, sanitizedStatement.getMainIdentifier());
         }
-      } else {
+      } else if (rawQueryTexts.size() > 1) {
         MultiQuery multiQuery =
             MultiQuery.analyze(getter.getRawQueryTexts(request), statementSanitizationEnabled);
         internalSet(attributes, DB_QUERY_TEXT, join("; ", multiQuery.getStatements()));
@@ -136,6 +134,11 @@ public void onStart(AttributesBuilder attributes, Context parentContext, REQUEST
 
     Map<String, String> queryParameters = getter.getQueryParameters(request);
     setQueryParameters(attributes, isBatch, queryParameters);
+
+    // calling this last so explicit getDbOperationName(), getDbCollectionName(),
+    // getDbQueryText(), and getDbQuerySummary() implementations can override
+    // the parsed values from above
+    DbClientAttributesExtractor.onStartCommon(attributes, getter, request);
   }
 
   private void setQueryParameters(
@@ -160,4 +163,23 @@ private static String join(String delimiter, Collection<String> collection) {
     }
     return builder.toString();
   }
+
+  @Override
+  public void onEnd(
+      AttributesBuilder attributes,
+      Context context,
+      REQUEST request,
+      @Nullable RESPONSE response,
+      @Nullable Throwable error) {
+    DbClientAttributesExtractor.onEndCommon(attributes, getter, response, error);
+  }
+
+  /**
+   * This method is internal and is hence not for public use. Its API is unstable and can change at
+   * any time.
+   */
+  @Override
+  public SpanKey internalGetSpanKey() {
+    return SpanKey.DB_CLIENT;
+  }
 }

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

@@ -22,10 +22,40 @@
  * OpenTelemetry specification.
  */
 public interface SqlClientAttributesGetter<REQUEST, RESPONSE>
-    extends DbClientCommonAttributesGetter<REQUEST, RESPONSE> {
+    extends DbClientAttributesGetter<REQUEST, RESPONSE> {
 
   /**
-   * Get the raw SQL query texts. The values returned by this method is later sanitized by the
+   * SqlClientAttributesExtractor will try to populate db.operation.name based on {@link
+   * #getRawQueryTexts(REQUEST)}, but this can be used to explicitly provide the operation name.
+   */
+  @Override
+  @Nullable
+  default String getDbOperationName(REQUEST request) {
+    return null;
+  }
+
+  /**
+   * SqlClientAttributesExtractor will try to populate db.query.text based on {@link
+   * #getRawQueryTexts(REQUEST)}, but this can be used to explicitly provide the query text.
+   */
+  @Override
+  @Nullable
+  default String getDbQueryText(REQUEST request) {
+    return null;
+  }
+
+  /**
+   * SqlClientAttributesExtractor will try to populate db.query.summary based on {@link
+   * #getRawQueryTexts(REQUEST)}, but this can be used to explicitly provide the query summary.
+   */
+  @Override
+  @Nullable
+  default String getDbQuerySummary(REQUEST request) {
+    return null;
+  }
+
+  /**
+   * Get the raw SQL query texts. The values returned by this method are later sanitized by the
    * {@link SqlClientAttributesExtractor} before being set as span attribute.
    *
    * <p>If {@code request} is not a batch query, then this method should return a collection with a