Exciting release!Introducing "safe npm". Learn more
Log inDemoInstall


Package Overview
File Explorer

Advanced tools


open telemetry instrumentation for the `aws-sdk` package


Version published
Weekly downloads
decreased by-51.92%

Weekly downloads



OpenTelemetry aws-sdk Instrumentation for Node.js

NPM version

This module provides automatic instrumentation for aws-sdk.


npm install --save opentelemetry-plugin-aws-sdk


To load this plugin, specify it in the Node Tracer's configuration:

const { NodeTracerProvider } = require("@opentelemetry/node"); const provider = new NodeTracerProvider({ plugins: { "aws-sdk": { enabled: true, // You may use a package name or absolute path to the file. path: "opentelemetry-plugin-aws-sdk", }, }, });

aws-sdk Plugin Options

aws-sdk plugin has few options available to choose from. You can set the following:

preRequestHookAwsSdkRequestCustomAttributeFunctionHook called before request send, which allow to add custom attributes to span.
responseHookAwsSdkResponseCustomAttributeFunctionHook for adding custom attributes when response is received from aws.
sqsProcessHookAwsSdkSqsProcessCustomAttributeFunctionHook called after starting sqs process span (for each sqs received message), which allow to add custom attributes to it.
suppressInternalInstrumentationbooleanMost aws operation use http request under the hood. If http instrumentation is enabled, each aws operation will also create an http/s child describing the communication with amazon servers. Setting the suppressInternalInstrumentationconfig value totrue` will cause the plugin to suppress instrumentation of underlying operations, effectively causing those http spans to be non-recordable.

Span Attributes

This plugin patch the internal Request object, which means that each sdk operation will create a single span with attributes from 3 sources:

Default attributes

Each span will have the following attributes:

Attribute NameTypeDescriptionExample
componentstringAlways equals "aws-sdk""aws-sdk"
aws.operationstringThe method name for the request.for SQS.sendMessage(...) the operation is "sendMessage"
aws.signature.versionstringAWS version of authentication signature on the request."v4"
aws.regionstringRegion name for the request"eu-west-1"
aws.service.apistringThe sdk class name for the service"SQS"
aws.service.identifierstringIdentifier for the service in the sdk"sqs"
aws.service.namestringAbbreviation name for the service"Amazon SQS"
aws.request.iduuidRequest unique id, as returned from aws on response"01234567-89ab-cdef-0123-456789abcdef"
aws.errorstringinformation about a service or networking error, as returned from AWS"UriParameterError: Expected uri parameter to have length >= 1, but found "" for params.Bucket"

Custom User Attributes

The plugin user can configure a preRequestHook function which will be called before each request, with the request object and the corrosponding span.
This hook can be used to add custom attributes to the span with any logic.
For example, user can add interesting attributes from the request.params, and write custom logic based on the service and operation. Usage example:

awsPluginConfig = { enabled: true, path: "opentelemetry-plugin-aws-sdk", preRequestHook: (span, request) => { if (span.attributes["aws.service.api"] === 's3') { span.setAttribute("s3.bucket.name", request.params["Bucket"]); } } };

Specific Service Logic

AWS contains dozens of services accessible with the JS SDK. For many services, the default attributes specified above are enough, but other services have specific trace semantic conventions, or need to inject/extract intra-process context, or set intra-process context correctly.

Specific service logic currently implemented for:

  • SQS

This plugin is a work in progress. We implemented some of the specific trace semantics for some of the services, and strive to support more services and extend the already supported services in the future. You can Open an Issue, or Submit a Pull Request if you want to contribute.

Potential Side Effects

The plugin is doing best effort to support the trace specification of open telemetry. For SQS, it involves defining new attributes on the Messages array, as well as on the manipulated types generated from this array (to set correct trace context for a single SQS message operation). Those properties are defined as non-enumerable properties, so they have minimum side effect on the app. They will, however, show when using the Object.getOwnPropertyDescriptors and Reflect.ownKeys functions on SQS Messages array and for each Message in the array.

This extension (and many others) was developed by Aspecto with ❤️



Last updated on 02 Feb 2021

Did you know?

Socket installs a Github app to automatically flag issues on every pull request and report the health of your dependencies. Find out what is inside your node modules and prevent malicious activity before you update the dependencies.

Install Socket
support@socket.devSocket SOC 2 Logo


  • Package Issues
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc