Node.js SDK

Serverless Dashboard, when Instrumentation is enabled on an AWS Lambda function, will hook into the AWS Lambda runtime environment and automatically report metrics, traces, spans, and events. To capture handled errors, warnings, and to set custom tags, the SDK library must be added and instrumented in your AWS Lambda function handler.

Key terms

  • An Event is an instance of an error, warning, or notice that is captured as a part of a Trace. Multiple events can be captured in a single trace.
  • A Captured Error is an instance of an error that is sent to Serverless Dashboard as an Event. It can be viewed in the Trace Explorer Details.
  • A Captured Warning is one instance of a string in Node.js that is sent to Serverless Dashboard as an Event, much like a Captured Error.
  • A Tag is a key/value-pair that can be set on the Trace or an individual Event, and sent to Serverless Dashboard. Tags can be viewed on the Trace Explorer Details.

Installation

Install the package

When Tracing is enabled in Serverless Dashboard, an AWS Lambda Layer is added to your AWS Lambda function with the @serverless/sdk package. While the AWS Lambda layer is added by Serverless Dashboard, it is possible for the layer to be removed temporarily if you deploy manually or with some infrastructure as code tools. As such, we recommend bundling the SDK with your handler to avoid unresolved references to the SDK.

npm install @serverless/sdk --save
# or
yarn add @serverless/sdk

Using a bundler

If you use a bundler, like esbuild, the AWS Lambda Layer for Serverless Dashboard will instrument native Node.js APIs like http and console, and APIs available on the runtime like the AWS SDK; however, if the handler bundles APIs, like express or the AWS SDK, then Serverless Dashboard will not be able to auto-instrument. To enable auto-instrumentation for these APIs, you will need to manually add the AWS-specific auto-instrumentation library and initiate auto-instrumentation.

Install the @serverless/aws-lambda-sdk package locally. This replaces the need for the @serverless/sdk package, so you do not need both.

npm install @serverless/aws-lambda-sdk --save
# or
yarn add @serverless/aws-lambda-sdk

Use the following methods to instrument the AWS client libraries and Express.js.

const express = require('express');
const serverlessSdk = require('@serverless/aws-lambda-sdk');

// Instrument AWS SDK v2
serverlessSdk.instrumentation.awsSdkV2.install(AWS);

// Instrument AWS SDK v3 client
serverlessSdk.instrumentation.awsSdkV3Client.install(client);

// Instruments Express.js
const expressApp = express();
// Ensure you install the SDK instrumentation before
// installing any express middleware
serverlessSdk.instrumentation.expressApp.install(expressApp);

Additionally, in some instrumentation cases, it's important to ensure that the bundler doesn't change the function names, as span names and tags are resolved from them. In esbuild this can be ensured with --keep-names option.

Enable Instrumentation

The SDK will merely generate the necessary Tags, Spans, and Events; however, you must Enable Instrumentation for each of your functions for Serverless Dashboard to ingest the data.

Usage

The package does not require any configuration as the credentials are automatically set on the AWS Lambda function environment variables when Tracing is enabled in Serverless Dashboard.

To use the Serverless SDK you must require the @serverless/sdk method in your AWS Lambda function handler.

const serverlessSdk = require('@serverless/sdk');

Capturing Errors

The most common use case for the Serverless SDK is to capture handled errors. There are two mechanisms for capturing handled errors.

Using captureError

try {
  // an error is thrown
} catch (ex) {
  serverlessSdk.captureError(ex);
}

Using console.error

try {
  // an error is thrown
} catch (ex) {
  console.error(ex);
}

The Serverless SDK automatically instruments the console.error method to capture errors. This makes instrumentation much easier as you may already be using console.error to display the errors.

This method can be used to capture Error objects, as well as any combination of strings. If only an Error object is provided, then the stack trace in Console will show the stack trace of the error object. If a string, or a combination of a string and Error, are provided, then the stack trace of the console.error will be captured.

Capturing Warnings

Using captureWarning

serverlessSdk.captureWarning('Something bad will happen soon');

Using console.warn

console.warn('My Warning');

The Serverless SDK automatically instruments the console.warn method to capture warnings. This makes instrumentation easier as you may already be using console.warn to display warnings.

This method only supports capturing strings.

We recommend avoiding using unique instance values for the strings. For example, if you need to include a userId, email, request ID, or any ID that may be unique to the individual invocation, we recommend using Tagging instead.

This method will capture the stack trace of the console.warn call so it is easy to identify in Serverless Dashboard.

Tagging

Setting Tags on the Trace

serverlessSdk.setTag('userId', 'bd86489cf036');

Using the setTag method will create Tags associated with the entire Trace. You'll be able to see the Tags on the Trace Details page in the Trace Explorer.

All Tags set with setTag are also inherited by all the Captured Errors and Captured Warnings.

Tag keys may only contain alphanumeric, ., -, and _ characters. Tag values may contain any string value. Invalid tag keys will not throw errors, instead, an SDK error will be made available in Trace Details.

Settings Tags with console.error and console.warn

serverlessSdk.setTag('userId', 'bd86489cf036');
console.warn('warning message');
console.error(new Error('some error'));

Using setTag sets the Tag values on both the Trace and all Captured Errors and Captured Warnings. Captured Errors and Captured Warnings can be created using the console.error and console.warn methods. Therefore, Tags set with setTag will apply to all Captured Errors and Captured Warnings created using console.error and console.warn.

Setting Tags on Captured Errors

serverlessSdk.captureError(ex, { tags: { userId: '1b8b4c6b4b14' } });

Tags can also be set on the individual error. If you previously set a Tag using setTag then the Tags set on captureError will override the Tags on the Captured Error, while keeping the Tag on the trace unmodified.

Tag keys on captureError are validated the same way as tag keys on setTag.

Setting Tags on Captured Warnings

serverlessSdk.captureWarning('warning message', { tags: { userId: 'eb661c69405c' } });

Tags can also be added on the individual Captured Warnings, just like Captured Errors.

Tag keys on captureWarning are validated the same way as tag keys on setTag.

Structured Logs with captureError and captureWarning

The captureWarning and captureError methods will send the content to Serverless Console in a binary format. To enable human-readability these methods will also output a structured-log JSON string, like the one shown below.

This string is easier to read, and can also be used with other tools like CloudWatch Log Insights to parse and search.

{
  "source": "serverlessSdk",
  "type": "ERROR_TYPE_CAUGHT_USER",
  "message": "User not found",
  "stackTrace": "...",
  "tags": {
    "userId": "eb661c69405c"
   }
}

To disable the output of the structured logs with captureError and captureWarning, set this environment variable in the runtime.

SLS_DISABLE_CAPTURED_EVENTS_STDOUT=true

Creating Custom Spans

Spans are part of the Trace that show when something started and stopped. Spans can be nested and they can contain Events. Spans are automatically created by the Serverless SDK for AWS and HTTP requests. These methods show you how you can create your own custom spans and nest them.

Create a Custom Span

const customSpan1 = serverlessSdk.createSpan('mySpan');
// do some work
customSpan1.close();

Creating a Custom Span with a callback

Instead of creating a span and stopping it using close(), you can also pass a callback method to createSpan to automatically start/stop the span when the callback starts/stops.

serverlessSdk.createSpan('mySpan', () => {
  // do some work
});

This also supports async callbacks.

serverlessSdk.createSpan('mySpan', async () => {
  // do some work
});

Creating Nested Spans

Spans can also be nested by calling the createSpan method on a Span.

const span1 = serverlessSdk.createSpan('span1');
const span2 = span1.createSpan('span2');
// do some work
span2.close();
// do additional work
span1.close();

Child spans must be stopped via close() before the parent Span is stopped. If a parent span is stopped, then all child spans will be stopped.

Setting a custom endpoint

When using a mono-lambda architecture, in which a single lambda function with a framework like Express.js is routed from a single API Gateway endpoint, the request on API Gateway is captured as a proxy endpoint. As a result, the request may appear as /{proxy+} instead of the intended path. The Serverless SDK automatically instruments frameworks like Express.js, KOA, etc. to capture the correct endpoint. This enables you to filter for HTTP requests using the inteded path.

In some cases, it may be necessary to manually set the endpoint. In such cases you can use the setEndpoint method to customize the endpoint path.

serverlessSdk.setEndpoint('/my/custom/endpoint');
Edit this page

Node.js SDK

Serverless Dashboard, when Instrumentation is enabled on an AWS Lambda function, will hook into the AWS Lambda runtime environment and automatically report metrics, traces, spans, and events. To capture handled errors, warnings, and to set custom tags, the SDK library must be added and instrumented in your AWS Lambda function handler.

Key terms

  • An Event is an instance of an error, warning, or notice that is captured as a part of a Trace. Multiple events can be captured in a single trace.
  • A Captured Error is an instance of an error that is sent to Serverless Dashboard as an Event. It can be viewed in the Trace Explorer Details.
  • A Captured Warning is one instance of a string in Node.js that is sent to Serverless Dashboard as an Event, much like a Captured Error.
  • A Tag is a key/value-pair that can be set on the Trace or an individual Event, and sent to Serverless Dashboard. Tags can be viewed on the Trace Explorer Details.

Installation

Install the package

When Tracing is enabled in Serverless Dashboard, an AWS Lambda Layer is added to your AWS Lambda function with the @serverless/sdk package. While the AWS Lambda layer is added by Serverless Dashboard, it is possible for the layer to be removed temporarily if you deploy manually or with some infrastructure as code tools. As such, we recommend bundling the SDK with your handler to avoid unresolved references to the SDK.

npm install @serverless/sdk --save
# or
yarn add @serverless/sdk

Using a bundler

If you use a bundler, like esbuild, the AWS Lambda Layer for Serverless Dashboard will instrument native Node.js APIs like http and console, and APIs available on the runtime like the AWS SDK; however, if the handler bundles APIs, like express or the AWS SDK, then Serverless Dashboard will not be able to auto-instrument. To enable auto-instrumentation for these APIs, you will need to manually add the AWS-specific auto-instrumentation library and initiate auto-instrumentation.

Install the @serverless/aws-lambda-sdk package locally. This replaces the need for the @serverless/sdk package, so you do not need both.

npm install @serverless/aws-lambda-sdk --save
# or
yarn add @serverless/aws-lambda-sdk

Use the following methods to instrument the AWS client libraries and Express.js.

const express = require('express');
const serverlessSdk = require('@serverless/aws-lambda-sdk');

// Instrument AWS SDK v2
serverlessSdk.instrumentation.awsSdkV2.install(AWS);

// Instrument AWS SDK v3 client
serverlessSdk.instrumentation.awsSdkV3Client.install(client);

// Instruments Express.js
const expressApp = express();
// Ensure you install the SDK instrumentation before
// installing any express middleware
serverlessSdk.instrumentation.expressApp.install(expressApp);

Additionally, in some instrumentation cases, it's important to ensure that the bundler doesn't change the function names, as span names and tags are resolved from them. In esbuild this can be ensured with --keep-names option.

Enable Instrumentation

The SDK will merely generate the necessary Tags, Spans, and Events; however, you must Enable Instrumentation for each of your functions for Serverless Dashboard to ingest the data.

Usage

The package does not require any configuration as the credentials are automatically set on the AWS Lambda function environment variables when Tracing is enabled in Serverless Dashboard.

To use the Serverless SDK you must require the @serverless/sdk method in your AWS Lambda function handler.

const serverlessSdk = require('@serverless/sdk');

Capturing Errors

The most common use case for the Serverless SDK is to capture handled errors. There are two mechanisms for capturing handled errors.

Using captureError

try {
  // an error is thrown
} catch (ex) {
  serverlessSdk.captureError(ex);
}

Using console.error

try {
  // an error is thrown
} catch (ex) {
  console.error(ex);
}

The Serverless SDK automatically instruments the console.error method to capture errors. This makes instrumentation much easier as you may already be using console.error to display the errors.

This method can be used to capture Error objects, as well as any combination of strings. If only an Error object is provided, then the stack trace in Console will show the stack trace of the error object. If a string, or a combination of a string and Error, are provided, then the stack trace of the console.error will be captured.

Capturing Warnings

Using captureWarning

serverlessSdk.captureWarning('Something bad will happen soon');

Using console.warn

console.warn('My Warning');

The Serverless SDK automatically instruments the console.warn method to capture warnings. This makes instrumentation easier as you may already be using console.warn to display warnings.

This method only supports capturing strings.

We recommend avoiding using unique instance values for the strings. For example, if you need to include a userId, email, request ID, or any ID that may be unique to the individual invocation, we recommend using Tagging instead.

This method will capture the stack trace of the console.warn call so it is easy to identify in Serverless Dashboard.

Tagging

Setting Tags on the Trace

serverlessSdk.setTag('userId', 'bd86489cf036');

Using the setTag method will create Tags associated with the entire Trace. You'll be able to see the Tags on the Trace Details page in the Trace Explorer.

All Tags set with setTag are also inherited by all the Captured Errors and Captured Warnings.

Tag keys may only contain alphanumeric, ., -, and _ characters. Tag values may contain any string value. Invalid tag keys will not throw errors, instead, an SDK error will be made available in Trace Details.

Settings Tags with console.error and console.warn

serverlessSdk.setTag('userId', 'bd86489cf036');
console.warn('warning message');
console.error(new Error('some error'));

Using setTag sets the Tag values on both the Trace and all Captured Errors and Captured Warnings. Captured Errors and Captured Warnings can be created using the console.error and console.warn methods. Therefore, Tags set with setTag will apply to all Captured Errors and Captured Warnings created using console.error and console.warn.

Setting Tags on Captured Errors

serverlessSdk.captureError(ex, { tags: { userId: '1b8b4c6b4b14' } });

Tags can also be set on the individual error. If you previously set a Tag using setTag then the Tags set on captureError will override the Tags on the Captured Error, while keeping the Tag on the trace unmodified.

Tag keys on captureError are validated the same way as tag keys on setTag.

Setting Tags on Captured Warnings

serverlessSdk.captureWarning('warning message', { tags: { userId: 'eb661c69405c' } });

Tags can also be added on the individual Captured Warnings, just like Captured Errors.

Tag keys on captureWarning are validated the same way as tag keys on setTag.

Structured Logs with captureError and captureWarning

The captureWarning and captureError methods will send the content to Serverless Console in a binary format. To enable human-readability these methods will also output a structured-log JSON string, like the one shown below.

This string is easier to read, and can also be used with other tools like CloudWatch Log Insights to parse and search.

{
  "source": "serverlessSdk",
  "type": "ERROR_TYPE_CAUGHT_USER",
  "message": "User not found",
  "stackTrace": "...",
  "tags": {
    "userId": "eb661c69405c"
   }
}

To disable the output of the structured logs with captureError and captureWarning, set this environment variable in the runtime.

SLS_DISABLE_CAPTURED_EVENTS_STDOUT=true

Creating Custom Spans

Spans are part of the Trace that show when something started and stopped. Spans can be nested and they can contain Events. Spans are automatically created by the Serverless SDK for AWS and HTTP requests. These methods show you how you can create your own custom spans and nest them.

Create a Custom Span

const customSpan1 = serverlessSdk.createSpan('mySpan');
// do some work
customSpan1.close();

Creating a Custom Span with a callback

Instead of creating a span and stopping it using close(), you can also pass a callback method to createSpan to automatically start/stop the span when the callback starts/stops.

serverlessSdk.createSpan('mySpan', () => {
  // do some work
});

This also supports async callbacks.

serverlessSdk.createSpan('mySpan', async () => {
  // do some work
});

Creating Nested Spans

Spans can also be nested by calling the createSpan method on a Span.

const span1 = serverlessSdk.createSpan('span1');
const span2 = span1.createSpan('span2');
// do some work
span2.close();
// do additional work
span1.close();

Child spans must be stopped via close() before the parent Span is stopped. If a parent span is stopped, then all child spans will be stopped.

Setting a custom endpoint

When using a mono-lambda architecture, in which a single lambda function with a framework like Express.js is routed from a single API Gateway endpoint, the request on API Gateway is captured as a proxy endpoint. As a result, the request may appear as /{proxy+} instead of the intended path. The Serverless SDK automatically instruments frameworks like Express.js, KOA, etc. to capture the correct endpoint. This enables you to filter for HTTP requests using the inteded path.

In some cases, it may be necessary to manually set the endpoint. In such cases you can use the setEndpoint method to customize the endpoint path.

serverlessSdk.setEndpoint('/my/custom/endpoint');