# NPM Package - ESM | Sentry for AWS Lambda

In this guide you will learn how to set up the `@sentry/aws-serverless` SDK for AWS Lambda functions running in EcmaScript Modules (ESM) 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](https://docs.sentry.io/platforms/javascript/guides/aws-lambda/install/esm-npm.md#alternative-initialize-the-sdk-in-code).

At this time, this guide shows the only way to use Sentry with ESM lambda functions. You cannot use the Sentry AWS Lambda Layer with ESM. We're working on an ESM lambda layer to provide a simpler setup but need to solve several OpenTelemetry-related limitations first.

## [1. Prerequisites](https://docs.sentry.io/platforms/javascript/guides/aws-lambda/install/esm-npm.md#1-prerequisites)

Before you begin, make sure you have the following:

* You have a lambda function that is running in EcmaScript Modules (ESM) mode, using `import` syntax.
* You're able to deploy dependencies (i.e. `node_modules`) alongside your function code to AWS Lambda.

## [2. Install](https://docs.sentry.io/platforms/javascript/guides/aws-lambda/install/esm-npm.md#2-install)

In addition to capturing errors, you can monitor interactions between multiple services or applications by [enabling tracing](https://docs.sentry.io/concepts/key-terms/tracing.md). You can also collect and analyze performance profiles from real users with [profiling](https://docs.sentry.io/product/explore/profiling.md).

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

Error Monitoring\[ ]Tracing\[ ]Profiling

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

```bash
npm install @sentry/aws-serverless
```

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

## [3. Wrap your handler](https://docs.sentry.io/platforms/javascript/guides/aws-lambda/install/esm-npm.md#3-wrap-your-handler)

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

`index.mjs`

```javascript
import * as Sentry from "@sentry/aws-serverless";



export const handler = Sentry.wrapHandler(async (event, context) => {

  // Your handler code
});
```

## [4. Set Environment Variables](https://docs.sentry.io/platforms/javascript/guides/aws-lambda/install/esm-npm.md#4-set-environment-variables)

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

```bash
NODE_OPTIONS="--import @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**:

[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fesm_env_vars-MPVQCB7E.png%23971x373\&w=2048\&q=75)](https://docs.sentry.io/mdx-images/esm_env_vars-MPVQCB7E.png)

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

## [Alternative: Initialize the SDK in Code](https://docs.sentry.io/platforms/javascript/guides/aws-lambda/install/esm-npm.md#alternative-initialize-the-sdk-in-code)

To further customize the SDK setup, you can also manually initialize the SDK in your lambda function. Due to ESM limitations, 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](https://docs.sentry.io/platforms/javascript/guides/aws-lambda/install/esm-npm.md#1-install)

Follow steps 1 and 2 above to [install the SDK NPM package](https://docs.sentry.io/platforms/javascript/guides/aws-lambda/install/esm-npm.md#2-install) in your project.

### [2. Initialize the SDK](https://docs.sentry.io/platforms/javascript/guides/aws-lambda/install/esm-npm.md#2-initialize-the-sdk)

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

`instrument.mjs`

```javascript
import * as Sentry from "@sentry/aws-serverless";
//  profiling
import { nodeProfilingIntegration } from "@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](https://docs.sentry.io/platforms/javascript/guides/aws-lambda/install/esm-npm.md#3-wrap-your-handler-1)

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

`index.mjs`

```javascript
import * as Sentry from "@sentry/aws-serverless";



export const handler = Sentry.wrapHandler(async (event, context) => {

  // Your handler code
});
```

### [4. Load the SDK](https://docs.sentry.io/platforms/javascript/guides/aws-lambda/install/esm-npm.md#4-load-the-sdk)

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

```bash
NODE_OPTIONS="--import ./instrument.mjs"
```

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

[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fesm_manual_env_vars-E3HT4T36.png%232040x660\&w=3840\&q=75)](https://docs.sentry.io/mdx-images/esm_manual_env_vars-E3HT4T36.png)

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

## [Using the v7 SDK](https://docs.sentry.io/platforms/javascript/guides/aws-lambda/install/esm-npm.md#using-the-v7-sdk)

The v7 `@sentry/serverless` SDK does not work correctly with ESM-based Lambda functions. Please upgrade to the latest SDK and follow the instructions above.
