feat: add @aws-sdk/client-dynamodb instrumentation

.ci/scripts/test.sh

@@ -213,7 +213,7 @@ elif [[ -n "${TAV_MODULE}" ]]; then
     memcached)
       DOCKER_COMPOSE_FILE=docker-compose-memcached.yml
       ;;
-    aws-sdk|@aws-sdk/client-s3)
+    aws-sdk|@aws-sdk/client-s3|@aws-sdk/client-dynamodb)
       DOCKER_COMPOSE_FILE=docker-compose-localstack.yml
       ;;
     *)

.ci/tav.json

@@ -4,6 +4,7 @@
   "modules": [
     "@apollo/server",
     "@aws-sdk/client-s3",
+    "@aws-sdk/client-dynamodb",
     "@elastic/elasticsearch",
     "@hapi/hapi",
     "@opentelemetry/api",

.tav.yml

@@ -512,13 +512,12 @@ aws-sdk:
     - node test/instrumentation/modules/aws-sdk/sqs.test.js
     - node test/instrumentation/modules/aws-sdk/dynamodb.test.js
 
+# For all AWS-SDK clients want this version range:
+#   versions: '>=3.15.0 <4'
+# However, @awk-sdk/client-* releases *very* frequently (almost every day) and there
+# is no need to test *all* those releases. Instead we statically list a subset
+# of versions to test.
 '@aws-sdk/client-s3':
-  # We want this version range:
-  #   versions: '>=3.15.0 <4'
-  # However, @awk-sdk/client-s3 releases *very* frequently (almost every day) and there
-  # is no need to test *all* those releases. Instead we statically list a subset
-  # of versions to test.
-  #
   # Maintenance note: This should be updated periodically using:
   #   node ./dev-utils/tav-versions.js @aws-sdk/client-s3 ">=3.15.0 <4"
   #
@@ -528,6 +527,16 @@ aws-sdk:
     - node test/instrumentation/modules/@aws-sdk/client-s3.test.js
   node: '>=14'
 
+'@aws-sdk/client-dynamodb':
+  # Maintenance note: This should be updated periodically using:
+  #   node ./dev-utils/tav-versions.js @aws-sdk/client-dynamodb ">=3.15.0 <4"
+  #
+  # Test v3.15.0, every N=41 of 210 releases, and current latest.
+  versions: '3.15.0 || 3.53.0 || 3.154.0 || 3.216.0 || 3.294.0 || 3.360.0 || 3.370.0 || >3.370.0 <4'
+  commands:
+    - node test/instrumentation/modules/@aws-sdk/client-s3.test.js
+  node: '>=14'
+
 # - [email protected] added its diagnostics_channel support.
 # - In [email protected] the `request.origin` property was added, which we need
 #   in the 'undici:request:create' diagnostic message.

CHANGELOG.asciidoc

@@ -40,6 +40,9 @@ Notes:
 [float]
 ===== Features
 
+* Add support for `@aws-sdk/client-dynamodb`, one of the AWS SDK v3 clients.
+  ({pull}XXX[#XXXX])
+
 [float]
 ===== Bug fixes
 

docs/supported-technologies.asciidoc

@@ -114,6 +114,7 @@ The Node.js agent will automatically instrument the following modules to give yo
 |Module |Version |Note
 |https://www.npmjs.com/package/aws-sdk[aws-sdk] |>=2.858.0 <3 |Will instrument SQS send/receive/delete messages, all S3 methods, all DynamoDB methods, and the SNS publish method
 |https://www.npmjs.com/package/@aws-sdk/client-s3[@aws-sdk/client-s3] |>=3.15.0 <4 |Will instrument all S3 methods
+|https://www.npmjs.com/package/@aws-sdk/client-dynamodb[@aws-sdk/client-dynamodb] |>=3.15.0 <4 |Will instrument all DynamoDB methods
 |https://www.npmjs.com/package/cassandra-driver[cassandra-driver] |>=3.0.0 <5 |Will instrument all queries
 |https://www.npmjs.com/package/elasticsearch[elasticsearch] |>=8.0.0 |Will instrument all queries
 |https://www.npmjs.com/package/@elastic/elasticsearch[@elastic/elasticsearch] |>=7.0.0 <9.0.0 |Will instrument all queries

lib/instrumentation/modules/@aws-sdk/client-dynamodb.js

@@ -0,0 +1,151 @@
+/*
+ * Copyright Elasticsearch B.V. and other contributors where applicable.
+ * Licensed under the BSD 2-Clause License; you may not use this file except in
+ * compliance with the BSD 2-Clause License.
+ */
+
+'use strict';
+
+const constants = require('../../../constants');
+const NAME = 'DynamoDB';
+const TYPE = 'db';
+const SUBTYPE = 'dynamodb';
+const elasticAPMStash = Symbol('elasticAPMStash');
+
+/**
+ * Returns middlewares to instrument an S3Client instance
+ *
+ * @param {import('@aws-sdk/client-dynamodb').DynamoDBClient} client
+ * @param {any} agent
+ * @returns {import('./smithy-client').AWSMiddlewareEntry[]}
+ */
+function dynamoDBMiddlewareFactory(client, agent) {
+  return [
+    {
+      middleware: (next, context) => async (args) => {
+        // Ensure there is a span from the wrapped `client.send()`.
+        const span = agent._instrumentation.currSpan();
+        if (!span || !(span.type === TYPE && span.subtype === SUBTYPE)) {
+          return await next(args);
+        }
+
+        const input = args.input;
+        const table = input && input.TableName;
+        // The given span comes with the operation name and we need to
+        // add the table if applies
+        if (table) {
+          span.name += ' ' + table;
+        }
+
+        let err;
+        let result;
+        let response;
+        let statusCode;
+        try {
+          result = await next(args);
+          response = result && result.response;
+          statusCode = response && response.statusCode;
+        } catch (ex) {
+          // Save the error for use in `finally` below, but re-throw it to
+          // not impact code flow.
+          err = ex;
+
+          // This code path happens with a GetObject conditional request
+          // that returns a 304 Not Modified.
+          statusCode = err && err.$metadata && err.$metadata.httpStatusCode;
+          throw ex;
+        } finally {
+          if (statusCode) {
+            span._setOutcomeFromHttpStatusCode(statusCode);
+          } else {
+            span._setOutcomeFromErrorCapture(constants.OUTCOME_FAILURE);
+          }
+          if (err && (!statusCode || statusCode >= 400)) {
+            agent.captureError(err, { skipOutcome: true });
+          }
+
+          // TODO: something related to region?
+          const config = client.config;
+          const region = await config.region();
+
+          // Set the db context
+          const dbContext = { type: SUBTYPE }; // dynamodb
+          if (region) {
+            dbContext.instance = region;
+          }
+          if (input && input.KeyConditionExpression) {
+            dbContext.statement = input.KeyConditionExpression;
+          }
+          span.setDbContext(dbContext);
+
+          // Set destination context
+          const destContext = {};
+          if (context[elasticAPMStash]) {
+            destContext.address = context[elasticAPMStash].hostname;
+            destContext.port = context[elasticAPMStash].port;
+          }
+          if (region) {
+            destContext.service = { resource: `dynamodb/${region}` };
+            destContext.cloud = { region };
+          }
+          span._setDestinationContext(destContext);
+
+          // TODO: review spec and add OTel attributes
+          // https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/semantic_conventions/trace/instrumentation/aws-sdk.yml#L435
+          // OTel attributes
+          // const otelAttrs = span._getOTelAttributes()
+
+          // otelAttrs['aws.dynamodb.system'] = 'dynamodb'
+          // otelAttrs['aws.dynamodb.operation'] = span.action
+          // if (table) {
+          //   otelAttrs['aws.dynamodb.table_names'] = table
+          // }
+          // if (input && input.Select) {
+          //   otelAttrs['aws.dynamodb.select'] = input.Select
+          // }
+          // if (input && input.ProjectionExpression) {
+          //   otelAttrs['aws.dynamodb.projection'] = input.ProjectionExpression
+          // }
+          // // TODO: check result for consumed_capacity
+          // if (result && result.ConsumedCapacity) {
+          //   otelAttrs['aws.dynamodb.consumed_capacity'] = JSON.stringify(result.ConsumedCapacity)
+          // }
+
+          span.end();
+        }
+
+        return result;
+      },
+      options: { step: 'initialize', priority: 'high', name: 'elasticAPMSpan' },
+    },
+    {
+      middleware: (next, context) => async (args) => {
+        const req = args.request;
+        let port = req.port;
+
+        // Resolve port for HTTP(S) protocols
+        if (port === undefined) {
+          if (req.protocol === 'https:') {
+            port = 443;
+          } else if (req.protocol === 'http:') {
+            port = 80;
+          }
+        }
+
+        context[elasticAPMStash] = {
+          hostname: req.hostname,
+          port,
+        };
+        return next(args);
+      },
+      options: { step: 'finalizeRequest', name: 'elasticAPMHTTPInfo' },
+    },
+  ];
+}
+
+module.exports = {
+  DYNAMODB_NAME: NAME,
+  DYNAMODB_TYPE: TYPE,
+  DYNAMODB_SUBTYPE: SUBTYPE,
+  dynamoDBMiddlewareFactory,
+};

lib/instrumentation/modules/@smithy/smithy-client.js

@@ -15,6 +15,12 @@ const {
   S3_SUBTYPE,
   s3MiddlewareFactory,
 } = require('../@aws-sdk/client-s3');
+const {
+  DYNAMODB_NAME,
+  DYNAMODB_TYPE,
+  DYNAMODB_SUBTYPE,
+  dynamoDBMiddlewareFactory,
+} = require('../@aws-sdk/client-dynamodb');
 
 /**
  * We do alias them to a local type
@@ -56,6 +62,12 @@ const clientsConfig = {
     SUBTYPE: S3_SUBTYPE,
     factory: s3MiddlewareFactory,
   },
+  DynamoDBClient: {
+    NAME: DYNAMODB_NAME,
+    TYPE: DYNAMODB_TYPE,
+    SUBTYPE: DYNAMODB_SUBTYPE,
+    factory: dynamoDBMiddlewareFactory,
+  },
 };
 
 module.exports = function (mod, agent, { name, version, enabled }) {