> For the complete documentation index, see [llms.txt](https://docs.sealights.io/knowledgebase/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/capturing-runtime-coverage/aws-lambda-support.md).

# AWS Lambda Instrumentation (serverless)

Capture runtime coverage from Node.js AWS Lambda functions with the SeaLights Node.js Lambda layer.

> **Applies to:** Node.js AWS Lambda functions that are exercised by tests.

Lambda functions are covered by the **SeaLights Node.js Lambda layer**. The layer wraps your handler: on each invocation it turns on V8 coverage, runs your handler, and uploads the coverage for the open test stage before the invocation returns. You do not change your handler code.

{% stepper %}
{% step %}

### Scan the function code

Scan the code you deploy, like any other back-end build. `--awsConfigure` additionally writes an `sl-config.json` file into each subdirectory of the scanned directory, which the layer reads.

```bash
printf '%s' "$SEALIGHTS_AGENT_TOKEN" > sltoken.txt
npx slnodejs config --tokenFile sltoken.txt --appName my-lambdas --branchName main --buildName "$BUILD_NUMBER"
npx slnodejs scan --tokenFile sltoken.txt --buildSessionIdFile buildSessionId \
  --scanDir src --scmType git \
  --awsConfigure --awsConfigKeysToIgnore token
```

{% hint style="warning" %}
`sl-config.json` contains the agent token in plain text unless you pass `--awsConfigKeysToIgnore token`. Every deployment package built from the scanned directory would then carry the token. Keep it out, and set `SL_TOKEN` on the function instead.
{% endhint %}

`--awsConfigure` is optional: you can set every value as a function environment variable instead (step 3).
{% endstep %}

{% step %}

### Add the layer

SeaLights publishes two variants:

| Layer                 | Use it when                                                  |
| --------------------- | ------------------------------------------------------------ |
| `sl-nodejs-layer-cjs` | Your handler is CommonJS.                                    |
| `sl-nodejs-layer-esm` | Your handler is an ES module (`"type": "module"` or `.mjs`). |

Get the layer ARN for your AWS region from SeaLights support. The layer and the function must be in the same region.
{% endstep %}

{% step %}

### Configure the function

| Variable                  | Required                           | Value                                                                     |
| ------------------------- | ---------------------------------- | ------------------------------------------------------------------------- |
| `AWS_LAMBDA_EXEC_WRAPPER` | Yes                                | `/opt/sealights-extension`                                                |
| `SL_TOKEN`                | Yes (variable or `sl-config.json`) | The agent token. Inject it from your secret store.                        |
| `SL_BUILD_SESSION_ID`     | Yes (variable or `sl-config.json`) | The build session ID of the scanned build.                                |
| `SL_LAB_ID`               | No                                 | Lab ID of the test environment. Without it, the build session ID is used. |
| `SL_PROJECT_ROOT`         | No                                 | The project root of the scan, when you gave the scan one.                 |
| `SL_COLLECTOR_URL`        | No                                 | A SeaLights Collector address. Required only with `SL_RAW_COVERAGE=true`. |
| `SL_PROXY`                | No                                 | Proxy for the layer's calls to SeaLights.                                 |

A function environment variable takes precedence over the same key in `sl-config.json`.

Serverless Framework example:

```yaml
provider:
  name: aws
  runtime: nodejs20.x
  environment:
    AWS_LAMBDA_EXEC_WRAPPER: /opt/sealights-extension
    SL_TOKEN: ${env:SEALIGHTS_AGENT_TOKEN}
    SL_BUILD_SESSION_ID: ${env:SL_BUILD_SESSION_ID}
    SL_LAB_ID: lambda-qa
  layers:
    - <SEALIGHTS_LAYER_ARN>

functions:
  myFunction:
    handler: src/index.handler
```

AWS CLI example (this command replaces the function's whole layer list and environment, so include what the function already has):

```bash
aws lambda update-function-configuration \
  --function-name my-function \
  --layers "<SEALIGHTS_LAYER_ARN>" \
  --environment "Variables={AWS_LAMBDA_EXEC_WRAPPER=/opt/sealights-extension,SL_TOKEN=$SEALIGHTS_AGENT_TOKEN,SL_BUILD_SESSION_ID=$(cat buildSessionId),SL_LAB_ID=lambda-qa}"
```

{% endstep %}

{% step %}

### Open a test stage and invoke

The layer looks up the open test stage for its lab ID on every invocation. Without an open test stage, it collects no coverage.

```bash
npx slnodejs openTestStage --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --labId lambda-qa --testStage "Integration Tests"
# invoke the functions through your tests
npx slnodejs closeTestStage --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --labId lambda-qa --testStage "Integration Tests"
```

{% endstep %}

{% step %}

### Check that it works

In the function's CloudWatch logs, a working setup logs lines that start with `Sealights Layer:`, for example `Sealights Layer: V8 coverage collection is enabled.` and `Sealights Layer: Uploading footprints...`.
{% endstep %}
{% endstepper %}

## Coverage modes <a href="#coverage-modes" id="coverage-modes"></a>

| Mode         | How to turn it on      | Needs                                                                        |
| ------------ | ---------------------- | ---------------------------------------------------------------------------- |
| V8 (default) | Nothing                | Nothing beyond the setup above.                                              |
| `nyc`        | `SL_USE_NYC=true`      | Code instrumented with `nyc` before deployment, and `SL_PROJECT_ROOT`.       |
| Raw V8       | `SL_RAW_COVERAGE=true` | `SL_COLLECTOR_URL` (a SeaLights Collector), and a scan with `--rawCoverage`. |

## Other Lambda wrappers (Dynatrace, OpenTelemetry) <a href="#working-with-other-lambda-layers" id="working-with-other-lambda-layers"></a>

Lambda accepts only one `AWS_LAMBDA_EXEC_WRAPPER`. The SeaLights wrapper runs other wrappers itself, in this order, before your function starts:

1. `/opt/dynatrace`, if present, unless `DISABLE_DYNATRACE=true`.
2. `/opt/otel-handler`, if present, unless `DISABLE_OTEL_HANDLER=true`.
3. The scripts listed in `ENABLE_HANDLER` (comma-separated absolute paths, no spaces).

If one of those scripts exits with a non-zero status, the function fails to initialize.

## Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

| Symptom                                                                                                 | Check                                                                                                             |
| ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| No `Sealights Layer:` lines in the logs                                                                 | The layer ARN is attached, and `AWS_LAMBDA_EXEC_WRAPPER` is `/opt/sealights-extension`.                           |
| `SL_TOKEN environment variable is required.` or `SL_BUILD_SESSION_ID environment variable is required.` | Set the variable on the function, or keep the key in `sl-config.json`. An empty variable also wins over the file. |
| `Failed to resolve execution data from API, please check that an execution is open.`                    | No test stage is open for the function's lab ID (or for the build session ID when `SL_LAB_ID` is not set).        |
| `Collector setup is required when rawCoverage is enabled.`                                              | Set `SL_COLLECTOR_URL`, or turn off `SL_RAW_COVERAGE`.                                                            |
| Coverage appears but does not match the scan                                                            | `SL_PROJECT_ROOT` differs from the scan's project root.                                                           |
| The handler fails with an ES module error                                                               | Use the `-esm` layer for ES module handlers, and the `-cjs` layer for CommonJS handlers.                          |

The configuration error does not stop the function: the layer logs it, skips coverage for that invocation, and your handler still runs.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/capturing-runtime-coverage/aws-lambda-support.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
