Instrumenting Node.js code in Amazon Lambda - Amazon Lambda
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Instrumenting Node.js code in Amazon Lambda

Lambda integrates with Amazon X-Ray to help you trace, debug, and optimize Lambda applications. You can use X-Ray to trace a request as it traverses resources in your application, which may include Lambda functions and other Amazon services.

To send tracing data to X-Ray, you can use one of two SDK libraries:

Each of the SDKs offer ways to send your telemetry data to the X-Ray service. You can then use X-Ray to view, filter, and gain insights into your application's performance metrics to identify issues and opportunities for optimization.


The X-Ray and Powertools for Amazon Lambda SDKs are part of a tightly integrated instrumentation solution offered by Amazon. The ADOT Lambda Layers are part of an industry-wide standard for tracing instrumentation that collect more data in general, but may not be suited for all use cases. You can implement end-to-end tracing in X-Ray using either solution. To learn more about choosing between them, see Choosing between the Amazon Distro for Open Telemetry and X-Ray SDKs.

Using ADOT to instrument your Node.js functions

ADOT provides fully managed Lambda layers that package everything you need to collect telemetry data using the OTel SDK. By consuming this layer, you can instrument your Lambda functions without having to modify any function code. You can also configure your layer to do custom initialization of OTel. For more information, see Custom configuration for the ADOT Collector on Lambda in the ADOT documentation.

For Node.js runtimes, you can add the Amazon managed Lambda layer for ADOT Javascript to automatically instrument your functions. For detailed instructions on how to add this layer, see Amazon Distro for OpenTelemetry Lambda Support for JavaScript in the ADOT documentation.

Using the X-Ray SDK to instrument your Node.js functions

To record details about calls that your Lambda function makes to other resources in your application, you can also use the Amazon X-Ray SDK for Node.js. To get the SDK, add the aws-xray-sdk-core package to your application's dependencies.

Example blank-nodejs/package.json
{ "name": "blank-nodejs", "version": "1.0.0", "private": true, "devDependencies": { "jest": "29.7.0" }, "dependencies": { "@aws-sdk/client-lambda": "3.345.0", "aws-xray-sdk-core": "3.5.3" }, "scripts": { "test": "jest" } }

To instrument Amazon SDK clients in the Amazon SDK for JavaScript v3, wrap the client instance with the captureAWSv3Client method.

Example blank-nodejs/function/index.js – Tracing an Amazon SDK client
const AWSXRay = require('aws-xray-sdk-core'); const { LambdaClient, GetAccountSettingsCommand } = require('@aws-sdk/client-lambda'); // Create client outside of handler to reuse const lambda = AWSXRay.captureAWSv3Client(new LambdaClient()); // Handler exports.handler = async function(event, context) { event.Records.forEach(record => { ...

The Lambda runtime sets some environment variables to configure the X-Ray SDK. For example, Lambda sets AWS_XRAY_CONTEXT_MISSING to LOG_ERROR to avoid throwing runtime errors from the X-Ray SDK. To set a custom context missing strategy, override the environment variable in your function configuration to have no value, and then you can set the context missing strategy programmatically.

Example initialization code
const AWSXRay = require('aws-xray-sdk-core'); // Configure the context missing strategy to do nothing AWSXRay.setContextMissingStrategy(() => {});

For more information, see Use Lambda environment variables to configure values in code.

After you add the correct dependencies and make the necessary code changes, activate tracing in your function's configuration via the Lambda console or the API.

Activating tracing with the Lambda console

To toggle active tracing on your Lambda function with the console, follow these steps:

To turn on active tracing
  1. Open the Functions page of the Lambda console.

  2. Choose a function.

  3. Choose Configuration and then choose Monitoring and operations tools.

  4. Choose Edit.

  5. Under X-Ray, toggle on Active tracing.

  6. Choose Save.

Activating tracing with the Lambda API

Configure tracing on your Lambda function with the Amazon CLI or Amazon SDK, use the following API operations:

The following example Amazon CLI command enables active tracing on a function named my-function.

aws lambda update-function-configuration \ --function-name my-function \ --tracing-config Mode=Active

Tracing mode is part of the version-specific configuration when you publish a version of your function. You can't change the tracing mode on a published version.

Activating tracing with Amazon CloudFormation

To activate tracing on an AWS::Lambda::Function resource in an Amazon CloudFormation template, use the TracingConfig property.

Example function-inline.yml – Tracing configuration
Resources: function: Type: AWS::Lambda::Function Properties: TracingConfig: Mode: Active ...

For an Amazon Serverless Application Model (Amazon SAM) AWS::Serverless::Function resource, use the Tracing property.

Example template.yml – Tracing configuration
Resources: function: Type: AWS::Serverless::Function Properties: Tracing: Active ...

Interpreting an X-Ray trace

Your function needs permission to upload trace data to X-Ray. When you activate tracing in the Lambda console, Lambda adds the required permissions to your function's execution role. Otherwise, add the AWSXRayDaemonWriteAccess policy to the execution role.

After you've configured active tracing, you can observe specific requests through your application. The X-Ray service graph shows information about your application and all its components. The following image demonstrates an application with two functions. The primary function processes events and sometimes returns errors. The second function at the top processes errors that appear in the first's log group and uses the Amazon SDK to call X-Ray, Amazon Simple Storage Service (Amazon S3), and Amazon CloudWatch Logs.

A diagram that shows two separate applications and their respective service maps in X-Ray

X-Ray doesn't trace all requests to your application. X-Ray applies a sampling algorithm to ensure that tracing is efficient, while still providing a representative sample of all requests. The sampling rate is 1 request per second and 5 percent of additional requests.


You cannot configure the X-Ray sampling rate for your functions.

In X-Ray, a trace records information about a request that is processed by one or more services. Lambda records 2 segments per trace, which creates two nodes on the service graph. The following image highlights these two nodes:

An X-Ray service map with a single function.

The first node on the left represents the Lambda service, which receives the invocation request. The second node represents your specific Lambda function. The following example shows a trace with these two segments. Both are named my-function, but one has an origin of AWS::Lambda and the other has an origin of AWS::Lambda::Function. If the AWS::Lambda segment shows an error, the Lambda service had an issue. If the AWS::Lambda::Function segment shows an error, your function had an issue.

An X-Ray trace that shows latency across each subsegment of a specific Lambda invocation.

This example expands the AWS::Lambda::Function segment to show its three subsegments:

  • Initialization – Represents time spent loading your function and running initialization code. This subsegment only appears for the first event that each instance of your function processes.

  • Invocation – Represents the time spent running your handler code.

  • Overhead – Represents the time the Lambda runtime spends preparing to handle the next event.

You can also instrument HTTP clients, record SQL queries, and create custom subsegments with annotations and metadata. For more information, see the Amazon X-Ray SDK for Node.js in the Amazon X-Ray Developer Guide.


You can use X-Ray tracing for free each month up to a certain limit as part of the Amazon Free Tier. Beyond that threshold, X-Ray charges for trace storage and retrieval. For more information, see Amazon X-Ray pricing.

Storing runtime dependencies in a layer (X-Ray SDK)

If you use the X-Ray SDK to instrument Amazon SDK clients your function code, your deployment package can become quite large. To avoid uploading runtime dependencies every time you update your function code, package the X-Ray SDK in a Lambda layer.

The following example shows an AWS::Serverless::LayerVersion resource that stores the Amazon X-Ray SDK for Node.js.

Example template.yml – Dependencies layer
Resources: function: Type: AWS::Serverless::Function Properties: CodeUri: function/. Tracing: Active Layers: - !Ref libs ... libs: Type: AWS::Serverless::LayerVersion Properties: LayerName: blank-nodejs-lib Description: Dependencies for the blank sample app. ContentUri: lib/. CompatibleRuntimes: - nodejs16.x

With this configuration, you update the library layer only if you change your runtime dependencies. Since the function deployment package contains only your code, this can help reduce upload times.

Creating a layer for dependencies requires build changes to generate the layer archive prior to deployment. For a working example, see the blank-nodejs sample application.