feat(instr-aws-sdk): support db semconv migration for dynamodb (#3312)

This adds support for using `OTEL_SEMCONV_STABILITY_OPT_IN` for controlled migration to stable `db.*` semconv. The `db.*` attributes are controlled by the `database[dup]` token.

Refs: #2953

Author: JamieDanielson

packages/instrumentation-aws-sdk/README.md

@@ -49,7 +49,7 @@ registerInstrumentations({
 aws-sdk instrumentation has few options available to choose from. You can set the following:
 
 | Options                                   | Type                                     | Description                                                                                                                                                                     |
-|-------------------------------------------|------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| ----------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `preRequestHook`                          | `AwsSdkRequestCustomAttributeFunction`   | Hook called before request send, which allow to add custom attributes to span.                                                                                                  |
 | `responseHook`                            | `AwsSdkResponseCustomAttributeFunction`  | Hook for adding custom attributes when response is received from aws.                                                                                                           |
 | `exceptionHook`                           | `AwsSdkExceptionCustomAttributeFunction` | Hook for adding custom attributes when exception is received from aws.                                                                                                          |
@@ -62,7 +62,7 @@ aws-sdk instrumentation has few options available to choose from. You can set th
 The instrumentations are collecting the following attributes:
 
 | Attribute Name | Type   | Description                                                                                                                                                                                                                                                                                         | Example                     |
-|----------------|--------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------|
+| -------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
 | `rpc.system`   | string | Always equals "aws-api"                                                                                                                                                                                                                                                                             |                             |
 | `rpc.method`   | string | The name of the operation corresponding to the request, as returned by the AWS SDK. If the SDK does not provide a way to retrieve a name, the name of the command SHOULD be used, removing the suffix `Command` if present, resulting in a PascalCase name with no spaces.                          | `PutObject`                 |
 | `rpc.service`  | string | The name of the service to which a request is made, as returned by the AWS SDK. If the SDK does not provide a away to retrieve a name, the name of the SDK's client interface for a service SHOULD be used, removing the suffix `Client` if present, resulting in a PascalCase name with no spaces. | `S3`, `DynamoDB`, `Route53` |
@@ -111,7 +111,7 @@ This package emits telemetry using a mix of Semantic Convention versions. While
 Attributes collected (this list is currently not exhaustive):
 
 | Attribute                                        | Short Description                                                                              | Service  |
-|--------------------------------------------------|------------------------------------------------------------------------------------------------|----------|
+| ------------------------------------------------ | ---------------------------------------------------------------------------------------------- | -------- |
 | `http.status_code` / `http.response.status_code` | (aws-sdk) HTTP response status code. See "HTTP Semantic Convention migration" note below.      |          |
 | `rpc.method`                                     | The name of the (logical) method being called.                                                 |          |
 | `rpc.service`                                    | The full (logical) name of the service being called.                                           |          |
@@ -138,10 +138,10 @@ Attributes collected (this list is currently not exhaustive):
 | `aws.dynamodb.table_count`                       | The number of items in the `TableNames` response parameter.                                    | dynamodb |
 | `aws.dynamodb.table_names`                       | The keys in the `RequestItems` object field.                                                   | dynamodb |
 | `aws.dynamodb.total_segments`                    | The value of the `TotalSegments` request parameter.                                            | dynamodb |
-| `db.name`                                        | The name of the database being accessed.                                                       | dynamodb |
-| `db.operation`                                   | The name of the operation being executed.                                                      | dynamodb |
-| `db.statement`                                   | The database statement being executed.                                                         | dynamodb |
-| `db.system`                                      | An identifier for the database management system (DBMS) product being used.                    | dynamodb |
+| `db.name` / `db.namespace`                       | The name of the database (TableName). See "Database Semantic Convention migration" note below. | dynamodb |
+| `db.operation` / `db.operation.name`             | The name of the operation. See "Database Semantic Convention migration" note below.            | dynamodb |
+| `db.statement` / `db.query.text`                 | The database statement. See "Database Semantic Convention migration" note below.               | dynamodb |
+| `db.system` / `db.system.name`                   | Database system identifier. See "Database Semantic Convention migration" note below.           | dynamodb |
 | `faas.execution`                                 | The execution ID of the current function execution.                                            | lambda   |
 | `faas.invoked_name`                              | The name of the invoked function.                                                              | lambda   |
 | `faas.invoked_provider`                          | The cloud provider of the invoked function.                                                    | lambda   |
@@ -177,6 +177,30 @@ For this instrumentation, the only impacted attributes are as follows:
 
 See the [HTTP semconv migration plan for OpenTelemetry JS instrumentations](https://github.com/open-telemetry/opentelemetry-js/issues/5646) for more details.
 
+### Database Semantic Convention migration
+
+Database semantic conventions (semconv) were stabilized in v1.33.0, and a [migration process](https://opentelemetry.io/docs/specs/semconv/non-normative/db-migration/)
+was defined. For DynamoDB operations, `instrumentation-aws-sdk` emits database-related
+attributes. The `OTEL_SEMCONV_STABILITY_OPT_IN` environment variable can be used to
+customize which database semantic conventions are used.
+
+To select which semconv version(s) is emitted from this instrumentation, use the
+`OTEL_SEMCONV_STABILITY_OPT_IN` environment variable.
+
+- `database`: emit the new (stable) v1.33.0+ semantics
+- `database/dup`: emit **both** the old v1.7.0 and the new (stable) v1.33.0+ semantics
+- By default, if `OTEL_SEMCONV_STABILITY_OPT_IN` includes neither of the above tokens, the old v1.7.0 semconv is used.
+
+For DynamoDB instrumentation, the impacted attributes are as follows:
+
+| v1.7.0 semconv | v1.33.0 semconv     | Short Description                                 |
+| -------------- | ------------------- | ------------------------------------------------- |
+| `db.system`    | `db.system.name`    | Database system identifier                        |
+| `db.name`      | `db.namespace`      | The database name (TableName for DynamoDB)        |
+| `db.operation` | `db.operation.name` | The name of the operation being executed          |
+| `db.statement` | `db.query.text`     | The database statement (if serializer configured) |
+
+See the [database migration guide](https://opentelemetry.io/docs/specs/semconv/non-normative/db-migration/) for details.
 
 ## Useful links
 

packages/instrumentation-aws-sdk/src/aws-sdk.ts

@@ -73,14 +73,19 @@ export class AwsInstrumentation extends InstrumentationBase<AwsSdkInstrumentatio
   // need declare since initialized in callbacks from super constructor
   declare private servicesExtensions: ServicesExtensions;
 
-  private _semconvStability: SemconvStability;
+  private _httpSemconvStability: SemconvStability;
+  private _dbSemconvStability: SemconvStability;
 
   constructor(config: AwsSdkInstrumentationConfig = {}) {
     super(PACKAGE_NAME, PACKAGE_VERSION, config);
-    this._semconvStability = semconvStabilityFromStr(
+    this._httpSemconvStability = semconvStabilityFromStr(
       'http',
       process.env.OTEL_SEMCONV_STABILITY_OPT_IN
     );
+    this._dbSemconvStability = semconvStabilityFromStr(
+      'database',
+      process.env.OTEL_SEMCONV_STABILITY_OPT_IN
+    );
   }
 
   protected init(): InstrumentationModuleDefinition[] {
@@ -373,7 +378,8 @@ export class AwsInstrumentation extends InstrumentationBase<AwsSdkInstrumentatio
         const requestMetadata = self.servicesExtensions.requestPreSpanHook(
           normalizedRequest,
           self.getConfig(),
-          self._diag
+          self._diag,
+          self._dbSemconvStability
         );
         const startTime = hrTime();
         const span = self._startAwsV3Span(normalizedRequest, requestMetadata);
@@ -415,10 +421,10 @@ export class AwsInstrumentation extends InstrumentationBase<AwsSdkInstrumentatio
                   const httpStatusCode =
                     response.output?.$metadata?.httpStatusCode;
                   if (httpStatusCode) {
-                    if (self._semconvStability & SemconvStability.OLD) {
+                    if (self._httpSemconvStability & SemconvStability.OLD) {
                       span.setAttribute(ATTR_HTTP_STATUS_CODE, httpStatusCode);
                     }
-                    if (self._semconvStability & SemconvStability.STABLE) {
+                    if (self._httpSemconvStability & SemconvStability.STABLE) {
                       span.setAttribute(
                         ATTR_HTTP_RESPONSE_STATUS_CODE,
                         httpStatusCode
@@ -462,10 +468,10 @@ export class AwsInstrumentation extends InstrumentationBase<AwsSdkInstrumentatio
 
                   const httpStatusCode = err?.$metadata?.httpStatusCode;
                   if (httpStatusCode) {
-                    if (self._semconvStability & SemconvStability.OLD) {
+                    if (self._httpSemconvStability & SemconvStability.OLD) {
                       span.setAttribute(ATTR_HTTP_STATUS_CODE, httpStatusCode);
                     }
-                    if (self._semconvStability & SemconvStability.STABLE) {
+                    if (self._httpSemconvStability & SemconvStability.STABLE) {
                       span.setAttribute(
                         ATTR_HTTP_RESPONSE_STATUS_CODE,
                         httpStatusCode

packages/instrumentation-aws-sdk/src/semconv.ts

@@ -563,9 +563,20 @@ export const ATTR_RPC_SYSTEM = 'rpc.system' as const;
  * Amazon DynamoDB
  *
  * @experimental This enum value is experimental and is subject to breaking changes in minor releases of `@opentelemetry/semantic-conventions`.
+ *
+ * @deprecated Replaced by `DB_SYSTEM_NAME_VALUE_DYNAMODB`.
  */
 export const DB_SYSTEM_VALUE_DYNAMODB = 'dynamodb' as const;
 
+/**
+ * Enum value "dynamodb" for attribute ATTR_DB_SYSTEM_NAME.
+ *
+ * Amazon DynamoDB
+ *
+ * @experimental This enum value is experimental and is subject to breaking changes in minor releases of `@opentelemetry/semantic-conventions`.
+ */
+export const DB_SYSTEM_NAME_VALUE_DYNAMODB = 'dynamodb' as const;
+
 /**
  * Enum value "chat" for attribute {@link ATTR_GEN_AI_OPERATION_NAME}.
  *

packages/instrumentation-aws-sdk/src/services/ServiceExtension.ts

@@ -22,6 +22,7 @@ import {
   SpanKind,
   Tracer,
 } from '@opentelemetry/api';
+import { SemconvStability } from '@opentelemetry/instrumentation';
 import {
   AwsSdkInstrumentationConfig,
   NormalizedRequest,
@@ -45,7 +46,8 @@ export interface ServiceExtension {
   requestPreSpanHook: (
     request: NormalizedRequest,
     config: AwsSdkInstrumentationConfig,
-    diag: DiagLogger
+    diag: DiagLogger,
+    dbSemconvStability?: SemconvStability
   ) => RequestMetadata;
 
   // called before request is sent, and after span is started

packages/instrumentation-aws-sdk/src/services/ServicesExtensions.ts

@@ -14,6 +14,7 @@
  * limitations under the License.
  */
 import { Tracer, Span, DiagLogger, Meter, HrTime } from '@opentelemetry/api';
+import { SemconvStability } from '@opentelemetry/instrumentation';
 import { ServiceExtension, RequestMetadata } from './ServiceExtension';
 import { SqsServiceExtension } from './sqs';
 import {
@@ -52,14 +53,20 @@ export class ServicesExtensions implements ServiceExtension {
   requestPreSpanHook(
     request: NormalizedRequest,
     config: AwsSdkInstrumentationConfig,
-    diag: DiagLogger
+    diag: DiagLogger,
+    dbSemconvStability?: SemconvStability
   ): RequestMetadata {
     const serviceExtension = this.services.get(request.serviceName);
     if (!serviceExtension)
       return {
         isIncoming: false,
       };
-    return serviceExtension.requestPreSpanHook(request, config, diag);
+    return serviceExtension.requestPreSpanHook(
+      request,
+      config,
+      diag,
+      dbSemconvStability
+    );
   }
 
   requestPostSpanHook(request: NormalizedRequest) {

packages/instrumentation-aws-sdk/src/services/dynamodb.ts

@@ -20,6 +20,13 @@ import {
   SpanKind,
   Tracer,
 } from '@opentelemetry/api';
+import { SemconvStability } from '@opentelemetry/instrumentation';
+import {
+  ATTR_DB_NAMESPACE,
+  ATTR_DB_OPERATION_NAME,
+  ATTR_DB_QUERY_TEXT,
+  ATTR_DB_SYSTEM_NAME,
+} from '@opentelemetry/semantic-conventions';
 import { RequestMetadata, ServiceExtension } from './ServiceExtension';
 import {
   ATTR_AWS_DYNAMODB_ATTRIBUTE_DEFINITIONS,
@@ -47,6 +54,7 @@ import {
   ATTR_DB_OPERATION,
   ATTR_DB_STATEMENT,
   ATTR_DB_SYSTEM,
+  DB_SYSTEM_NAME_VALUE_DYNAMODB,
   DB_SYSTEM_VALUE_DYNAMODB,
 } from '../semconv';
 import {
@@ -63,18 +71,33 @@ export class DynamodbServiceExtension implements ServiceExtension {
   requestPreSpanHook(
     normalizedRequest: NormalizedRequest,
     config: AwsSdkInstrumentationConfig,
-    diag: DiagLogger
+    diag: DiagLogger,
+    dbSemconvStability?: SemconvStability
   ): RequestMetadata {
     const spanKind: SpanKind = SpanKind.CLIENT;
     let spanName: string | undefined;
     const isIncoming = false;
     const operation = normalizedRequest.commandName;
+    const tableName = normalizedRequest.commandInput?.TableName;
 
-    const spanAttributes: Attributes = {
-      [ATTR_DB_SYSTEM]: DB_SYSTEM_VALUE_DYNAMODB,
-      [ATTR_DB_NAME]: normalizedRequest.commandInput?.TableName,
-      [ATTR_DB_OPERATION]: operation,
-    };
+    const spanAttributes: Attributes = {};
+
+    if (
+      dbSemconvStability === undefined ||
+      dbSemconvStability & SemconvStability.OLD
+    ) {
+      spanAttributes[ATTR_DB_SYSTEM] = DB_SYSTEM_VALUE_DYNAMODB;
+      spanAttributes[ATTR_DB_NAME] = tableName;
+      spanAttributes[ATTR_DB_OPERATION] = operation;
+    }
+    if (
+      dbSemconvStability !== undefined &&
+      dbSemconvStability & SemconvStability.STABLE
+    ) {
+      spanAttributes[ATTR_DB_SYSTEM_NAME] = DB_SYSTEM_NAME_VALUE_DYNAMODB;
+      spanAttributes[ATTR_DB_NAMESPACE] = tableName;
+      spanAttributes[ATTR_DB_OPERATION_NAME] = operation;
+    }
 
     if (config.dynamoDBStatementSerializer) {
       try {
@@ -84,7 +107,18 @@ export class DynamodbServiceExtension implements ServiceExtension {
         );
 
         if (typeof sanitizedStatement === 'string') {
-          spanAttributes[ATTR_DB_STATEMENT] = sanitizedStatement;
+          if (
+            dbSemconvStability === undefined ||
+            dbSemconvStability & SemconvStability.OLD
+          ) {
+            spanAttributes[ATTR_DB_STATEMENT] = sanitizedStatement;
+          }
+          if (
+            dbSemconvStability !== undefined &&
+            dbSemconvStability & SemconvStability.STABLE
+          ) {
+            spanAttributes[ATTR_DB_QUERY_TEXT] = sanitizedStatement;
+          }
         }
       } catch (err) {
         diag.error('failed to sanitize DynamoDB statement', err);