OpenTelemetry aws-sdk Instrumentation for Node.js

Share this post

Share on facebook
Share on twitter
Share on linkedin

Open Telemetry is a CNCF project, which, among other things, enables the collection of distributed traces.

Traces enable observability into a software system by representing the flow of calls between different components in a service, or between different services, as well as relevant data per operation.

Extracting trace data from a component is done by installing and setting up an Open Telemetry plugin that patch function calls and create span per operation.

AWS SDK

If your application’s backend is running Node.js on AWS, high chances that you are using the aws-sdk JS package, which exposes an API for communicating with the services offered by Amazon, such as S3, SQS, SNS, etc.

We can uncover significant insights by collecting trace data about those interactions. For example, grasping the full picture of how a service performs I/O or understanding the dependencies of services in the production environment.

Open Telemetry Plugin

The new plugin for aws-sdk is instrumenting this package, creating an open telemetry span for each request and response to AWS. Currently, version 2 of the sdk is supported. Version 3 support will be added in after its GA launch.

The plugin has a generic part that works immediately and uniformly for all services accessible by the SDK.

const { NodeTracerProvider } = require("@opentelemetry/node");

const provider = new NodeTracerProvider({
  plugins: {
    "aws-sdk": {
      enabled: true,
      path: "opentelemetry-plugin-aws-sdk",
    }
  }
});

Initialization example

Specific logic can be hooked internally (in the plugin level, always accessible to all users) or externally (custom configurable user behavior), which provides per-service semantic extensions where needed.

SQS Handling

SQS spans are created with additional attributes and processing spans, as specified in open telemetry Messaging System Specification.

example of SQS receiveMessage request

The above screenshot is an example trace from our production environment. The first span is SQS receiveMessage operation, followed by the underlying HTTP message used by the SDK to access AWS, followed by two messaging.operation = processing spans for the processing of the messages received from the queue.

Finally, messages are deleted from the queue with another call to aws-sdk deleteMessage() function (followed by the HTTP span used to communicate with AWS).

The OpenTelemetry aws-sdk instrumentation for Node.js is available here.


The plugin is released to the community with the hope it will provide significant value. It is planned to be extended and improved on the run, in order to instrument as many AWS services possible, in the best manner.

Community contributions and involvement are more than welcome 🙂

As always, this extension (and many others) was developed by Aspecto with ❤️

Spread the word

Share on facebook
Share on twitter
Share on linkedin

Try Aspecto Yourself

It takes only 2 minutes to install our SDK