NPM package - CJS

In this guide you will learn how to set up the @sentry/aws-serverless SDK for AWS Lambda functions running in CommonJS (CJS) mode. We recommend starting the SDK automatically via environment variables so that you only have to make minimal code changes to your lambda function. If you need more control over the SDK setup, you can also initialize the SDK in in code.

However, you need to modify your code and deploy the Sentry dependencies alongside your function code. If you're looking for the most simple way to set up Sentry, you might want to use the Lambda Layer instead.

1. Prerequisites

Before you begin, make sure you have the following:

• You have a lambda function that is running in CommonJS (CJS) mode, using require syntax.
• You're able to deploy dependencies (i.e. node_modules) alongside your function code to AWS Lambda.

2. Install

In addition to capturing errors, you can monitor interactions between multiple services or applications by enabling tracing. You can also collect and analyze performance profiles from real users with profiling.

Select which Sentry features you'd like to install in addition to Error Monitoring to get the corresponding installation and configuration instructions below.

Install the @sentry/aws-serverless SDK using a package manager of your choice:

npm install @sentry/aws-serverless

npm install @sentry/aws-serverless @sentry/profiling-node

3. Wrap your handler

Add the Sentry.wrapHandler wrapper around your function handler to automatically catch errors and performance data:

const Sentry = require("@sentry/aws-serverless");

exports.handler = Sentry.wrapHandler(async (event, context) => {
  // Your handler code
});

4. Set Environment Variables

To initialize and configure the SDK, you need to set the following environment variables in your AWS Lambda function configuration:

NODE_OPTIONS="-r @sentry/aws-serverless/awslambda-auto"
SENTRY_DSN="https://examplePublicKey@o0.ingest.sentry.io/0"
#  performance
SENTRY_TRACES_SAMPLE_RATE="1.0"
#  performance

To set environment variables, navigate to your Lambda function, select Configuration, then Environment variables:

That's it - make sure to re-deploy your function and you're all set!

Alternative: Initialize the SDK in Code

To further customize the SDK setup, you can also manually initialize the SDK in your lambda function. You need to initialize the SDK in a separate file and load it before your function starts. The benefit of this installation method is that you can fully customize your Sentry SDK setup in a Sentry.init call.

1. Install

Follow steps 1 and 2 above to install the SDK NPM package in your project.

2. Initialize the SDK

Create a new file, for example instrument.js to initialize the SDK:

const Sentry = require("@sentry/aws-serverless");
//  profiling
const { nodeProfilingIntegration } = require("@sentry/profiling-node");

//  profiling
Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",

  // Adds request headers and IP for users, for more info visit:
  // https://docs.sentry.io/platforms/javascript/guides/aws-lambda/configuration/options/#sendDefaultPii
  sendDefaultPii: true,

  //  profiling
  integrations: [nodeProfilingIntegration()],
  //  profiling

  //  performance
  // Add Tracing by setting tracesSampleRate and adding integration
  // Set tracesSampleRate to 1.0 to capture 100% of transactions
  // We recommend adjusting this value in production
  // Learn more at
  // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate
  tracesSampleRate: 1.0,
  //  performance
  //  profiling

  // Set sampling rate for profiling - this is relative to tracesSampleRate
  profilesSampleRate: 1.0,
  //  profiling
});

3. Wrap your handler

Add the Sentry.wrapHandler wrapper around your function handler to automatically catch errors and performance data:

const Sentry = require("@sentry/aws-serverless");

exports.handler = Sentry.wrapHandler(async (event, context) => {
  // Your handler code
});

4. Load the SDK

To load the SDK before your function starts, you need to preload the instrument.js by setting the NODE_OPTIONS environment variable:

NODE_OPTIONS="--require ./instrument.js"

To set environment variables, navigate to your Lambda function, select Configuration, then Environment variables:

That's it - make sure to re-deploy your function and you're all set!

Using the v7 SDK

The instructions above are written for the latest SDK version. In SDK versions prior to version 8, the @sentry/aws-serverless package was called @sentry/serverless. If you are using an older version, you can follow this guide but replace the package with @sentry/serverless.