docs(aws): Update guides for v10 Lambda Layer and NPM package (#14482)

_Draft: Merge when JS v10 SDKs are released in GA_

Introduces new unified docs for ESM and CJS versions of the Lambda layer
and NPM package

Author: msonnb

docs/platforms/javascript/guides/aws-lambda/index.mdx

@@ -20,12 +20,16 @@ On this page you'll get an overview how to install, configure and use Sentry in
 
 ## Installation
 
-Depending on your setup, there are different ways to install and use Sentry in your Lambda functions:
+Depending on your preferences, you can install Sentry in your Lambda functions using the [Sentry AWS Lambda Layer](./install/layer) (recommended) or the [Sentry AWS NPM package](./install/npm).
 
-- If your Lambda functions are running in CommonJS (CJS) using `require` syntax, [install the Sentry AWS Lambda Layer](./install/cjs-layer)
-- If your Lambda functions are running in EcmaScript Modules (ESM) using `import` syntax, [install the Sentry AWS NPM package](./install/esm-npm)
+### Should I use the Lambda Layer or the NPM package?
 
-If you're not sure which installation method to use or want an overview of all available options to use Sentry in your Lambda functions, read the [installation methods overview](./install).
+We generally recommend using the Lambda layer as it doesn't require you to deploy any Sentry dependency alongside your function.
+With the layer, you can achieve the same level of customization as with the NPM package.
+There are two reasons why you still might want to use the NPM package instead:
+
+1. You want to minimize lambda function size and tree-shake parts of the SDK code that you don't need. A related reason might be because you're transpiling your code and want to transpile your dependencies as well.
+2. You already use NPM packages and deploy `node_modules` with your function and you don't want to add a (or another) Lambda layer to your functions.
 
 ## Configuration
 
@@ -41,8 +45,10 @@ exports.handler = async (event, context) => {
 };
 ```
 
-```javascript {filename:index.mjs}{tabTitle:ESM}{2}
-export const handler = async (event, context) => {
+```javascript {filename:index.mjs}{tabTitle:ESM}{4}
+import * as Sentry from "@sentry/aws-serverless";
+
+export const handler = Sentry.wrapHandler(async (event, context) => {
   throw new Error("This is a test error");
-};
+}));
 ```

docs/platforms/javascript/guides/aws-lambda/install/cjs-npm.mdx renamed to docs/platforms/javascript/guides/aws-lambda/install/cjs-npm__v9.x.mdx

@@ -4,38 +4,12 @@ sidebar_order: 1
 description: "Review all installation methods for using Sentry in AWS Lambda functions"
 ---
 
-
-## Which Installation Method Should I Use?
-
-Choosing the right installation method for using Sentry in your AWS Lambda functions depends on a couple of factors.
-
-Lambda functions can be written and executed either in CommonJS, using `require` syntax, or EcmaScript Modules (ESM), using `import` syntax.
-For Sentry to work correctly, you need to follow the guide for the format in which your functions are **executed**.
-
-### My Lambda function is written in TypeScript
-
-If you're using TypeScript, your lambda function is likely transpiled to CommonJS before running it. In this case, follow the [CommonJS instructions](#my-lambda-function-uses-require).
-Note that TypeScript can also be configured to output ESM, in which case you should follow the [ESM instructions](#my-lambda-function-uses-import).
-
-### My Lambda function uses `require`
-
-If you are using `require()` in your function, follow the CommonJS instructions. Choose between [using our Lambda Layer (recommended)](./cjs-layer) or [installing the Sentry AWS NPM package](./cjs-layer).
-
-### My Lambda function uses `import`
-
-If you're using `import` syntax in your function and you're _not_ transpiling the code to CommonJS, follow the [ESM instructions](./esm-npm).
-
-### Can I use the Lambda layer for ESM functions?
-
-At this time, the Lambda Layer is only available for CommonJS functions. If you're using ESM, you'll need to set up Sentry manually.
-We're working on an ESM lambda layer but need to solve several OpenTelemetry-related limitations first.
+<PageGrid />
 
 ### Should I use the Lambda Layer or the NPM package?
 
-First off, at this time, you can only use the layer in CommonJS functions. If you're using ESM, you'll need to set up Sentry manually with the NPM package.
-
-We generally recommend to use the Lambda layer as it doesn't require you to deploy any Sentry dependency alongside your function.
-With using the layer, you can achieve the same level of customization as with the NPM package.
+We generally recommend using the Lambda layer as it doesn't require you to deploy any Sentry dependency alongside your function.
+With the layer, you can achieve the same level of customization as with the NPM package.
 There are two reasons why you still might want to use the NPM package instead:
 
 1. You want to minimize lambda function size and tree-shake parts of the SDK code that you don't need. A related reason might be because you're transpiling your code and want to transpile your dependencies as well.

docs/platforms/javascript/guides/aws-lambda/install/esm-npm.mdx renamed to docs/platforms/javascript/guides/aws-lambda/install/esm-npm__v9.x.mdx

@@ -0,0 +1,41 @@
+---
+title: Installation Methods
+sidebar_order: 1
+description: "Review all installation methods for using Sentry in AWS Lambda functions"
+---
+
+## Which Installation Method Should I Use?
+
+Choosing the right installation method for using Sentry in your AWS Lambda functions depends on a couple of factors.
+
+Lambda functions can be written and executed either in CommonJS, using `require` syntax, or EcmaScript Modules (ESM), using `import` syntax.
+For Sentry to work correctly, you need to follow the guide for the format in which your functions are **executed**.
+
+### My Lambda function is written in TypeScript
+
+If you're using TypeScript, your lambda function is likely transpiled to CommonJS before running it. In this case, follow the [CommonJS instructions](#my-lambda-function-uses-require).
+Note that TypeScript can also be configured to output ESM, in which case you should follow the [ESM instructions](#my-lambda-function-uses-import).
+
+### My Lambda function uses `require`
+
+If you are using `require()` in your function, follow the CommonJS instructions. Choose between [using our Lambda Layer (recommended)](./install/layer__v9.x) or [installing the Sentry AWS NPM package](./install/cjs-npm__v9.x).
+
+### My Lambda function uses `import`
+
+If you're using `import` syntax in your function and you're _not_ transpiling the code to CommonJS, follow the [ESM instructions](./install/esm-npm__v9.x).
+
+### Can I use the Lambda layer for ESM functions?
+
+At this time, the Lambda Layer is only available for CommonJS functions. If you're using ESM, you'll need to set up Sentry manually.
+We're working on an ESM lambda layer but need to solve several OpenTelemetry-related limitations first.
+
+### Should I use the Lambda Layer or the NPM package?
+
+First off, at this time, you can only use the layer in CommonJS functions. If you're using ESM, you'll need to set up Sentry manually with the NPM package.
+
+We generally recommend to use the Lambda layer as it doesn't require you to deploy any Sentry dependency alongside your function.
+With using the layer, you can achieve the same level of customization as with the NPM package.
+There are two reasons why you still might want to use the NPM package instead:
+
+1. You want to minimize lambda function size and tree-shake parts of the SDK code that you don't need. A related reason might be because you're transpiling your code and want to transpile your dependencies as well.
+2. You already use NPM packages and deploy `node_modules` with your function and you don't want to add a (or another) Lambda layer to your functions.

docs/platforms/javascript/guides/aws-lambda/install/img/env_vars.png

@@ -0,0 +1,178 @@
+---
+title: Lambda Layer
+description: "Learn how to add the Sentry Node Lambda Layer to use Sentry in your Lambda functions"
+sidebar_order: 1
+---
+
+The easiest way to get started with Sentry is to use the Sentry [Lambda Layer](https://docs.aws.amazon.com/lambda/latest/dg/adding-layers.html) instead of installing `@sentry/aws-serverless` with a package manager manually.
+If you follow this guide, you don't have to worry about deploying Sentry dependencies alongside your function code.
+
+## Prerequisites
+
+Before you begin, make sure you have the following:
+
+- You have a Lambda function deployed in AWS.
+- You know the AWS region that your function is deployed to.
+
+## 1. Add the Sentry Lambda Layer
+
+Add the Sentry Layer by navigating to your Lambda function. Select **Layers**, then **Add a Layer**.
+
+![](./img/lambda_view.png)
+
+**Specify an ARN** tab as illustrated:
+
+![](./img/add_layer.png)
+
+Finally, set the region and copy the provided ARN value into the input.
+
+<LambdaLayerDetail canonical="aws-layer:node" />
+
+<br />
+
+## 2. Setup Options
+
+Choose your setup method based on your Lambda function type:
+
+<Alert level="info" title="ESM vs. CommonJS">
+
+The setup instructions you should follow depend on how your function **runs** at runtime, not how it's written in your source code.
+
+- **Use CommonJS instructions** if your function runs with CommonJS modules (uses `require()` and `module.exports` at runtime)
+- **Use ESM instructions** if your function runs with ES modules (uses `import`/`export` at runtime)
+
+**Important:** Even if you write your code with `import`/`export` syntax, your function might still run as CommonJS if you're using TypeScript or a build tool that compiles to CommonJS. Check your build output or Lambda runtime configuration to determine which applies to your function.
+
+</Alert>
+
+### Option A: Automatic Setup
+
+**CommonJS functions** support fully automatic setup using environment variables - both SDK initialization and handler wrapping are handled automatically.
+
+**ESM functions** support automatic SDK initialization via environment variables, but require manual handler wrapping.
+
+In addition to capturing errors, you can monitor interactions between multiple services or applications by [enabling tracing](/concepts/key-terms/tracing/).
+
+Select which Sentry features you'd like to install in addition to Error Monitoring to get the corresponding installation and configuration instructions below.
+
+<OnboardingOptionButtons options={["error-monitoring", "performance"]} />
+
+Set the following environment variables in your Lambda function configuration:
+
+```bash {tabTitle:CommonJS}
+NODE_OPTIONS="--require @sentry/aws-serverless/awslambda-auto"
+SENTRY_DSN="___PUBLIC_DSN___"
+# ___PRODUCT_OPTION_START___ performance
+SENTRY_TRACES_SAMPLE_RATE="1.0"
+# ___PRODUCT_OPTION_END___ performance
+```
+
+```bash {tabTitle:ESM}
+NODE_OPTIONS="--import @sentry/aws-serverless/awslambda-auto"
+SENTRY_DSN="___PUBLIC_DSN___"
+# ___PRODUCT_OPTION_START___ performance
+SENTRY_TRACES_SAMPLE_RATE="1.0"
+# ___PRODUCT_OPTION_END___ performance
+```
+
+To set environment variables, navigate to your Lambda function, select **Configuration**, then **Environment variables**:
+
+![](./img/env_vars.png)
+
+<Alert level="info" title="For ESM Lambda Functions">
+
+You'll also need to manually wrap your handler as shown below:
+
+```javascript {filename:index.mjs}
+import * as Sentry from "@sentry/aws-serverless";
+
+export const handler = Sentry.wrapHandler(async (event, context) => {
+  // Your handler code
+});
+```
+
+</Alert>
+
+### Option B: Manual Setup
+
+Instead of using environment variables, you can manually initialize the SDK and wrap your handler in code. This approach works for both CommonJS and ESM functions and allows for further customization of the SDK setup.
+
+Note that you don't have to actually install an NPM package for this to work, as the package is already included in the Lambda Layer.
+
+#### For CommonJS Lambda Functions
+
+```javascript {filename:index.js}
+const Sentry = require("@sentry/aws-serverless");
+
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+
+  // 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,
+  // ___PRODUCT_OPTION_START___ 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,
+  // ___PRODUCT_OPTION_END___ performance
+});
+
+// Your package imports
+
+exports.handler = Sentry.wrapHandler(async (event, context) => {
+  // Your handler code
+});
+```
+
+It's important to add both, the `Sentry.init` call outside the handler function and the `Sentry.wrapHandler` wrapper around your function to automatically catch errors and performance data. Make sure that the `Sentry.init` call and the import statement are at the very top of your file before any other imports.
+
+#### For ESM Lambda Functions
+
+First, wrap your handler:
+
+```javascript {filename:index.mjs}{1,3}
+import * as Sentry from "@sentry/aws-serverless";
+
+export const handler = Sentry.wrapHandler(async (event, context) => {
+  // Your handler code
+});
+```
+
+Due to ESM limitations, you need to initialize the SDK in a separate file and load it before your function starts.
+
+Create a new file, for example `instrument.mjs` to initialize the SDK:
+
+```javascript {filename:instrument.mjs}
+import * as Sentry from "@sentry/aws-serverless";
+
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+
+  // 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,
+  // ___PRODUCT_OPTION_START___ 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,
+  // ___PRODUCT_OPTION_END___ performance
+});
+```
+
+##### 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"
+```
+
+That's it — make sure to re-deploy your function and you're all set!

docs/platforms/javascript/guides/aws-lambda/install/index.mdx

@@ -31,9 +31,11 @@ Add the Sentry Layer by navigating to your Lambda function. Select **Layers**, t
 
 ![](./img/add_layer.png)
 
-Finally, set the region and copy the provided ARN value into the input.
+Modify and copy the ARN value for your region into the input, e.g. for region `us-west-1` and the current v9 Lambda layer version `56`:
 
-<LambdaLayerDetail canonical="aws-layer:node" />
+```
+arn:aws:Lambda:us-west-1:943013980633:layer:SentryNodeServerlessSDKv9:56
+```
 
 <br />
 
@@ -74,12 +76,12 @@ const Sentry = require("@sentry/aws-serverless");
 
 Sentry.init({
   dsn: "___PUBLIC_DSN___",
-  
+
   // 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,
   // ___PRODUCT_OPTION_START___ 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