> 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)

> **Applies to:** Node.js AWS Lambda functions that need runtime coverage in SeaLights.

AWS Lambda uses **serverless runtime instrumentation**. SeaLights attaches through a Lambda Layer and starts coverage during each invocation.

This is different from [Scanning Your Application](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/scanning-your-application.md). `scan` uploads the build map. The Lambda Layer and wrapper attach runtime coverage when the function runs.

You do not change your handler code. You update deployment settings and environment variables.

{% hint style="warning" %}
When you scan Lambda code with `slnodejs scan`, include `--awsConfigure`.
{% endhint %}

{% stepper %}
{% step %}

## Scan the Lambda code

Start by scanning the same source folder you deploy to Lambda.

This step matches the default Node.js scan flow.

The only Lambda-specific difference is the explicit `--awsConfigure` option.

{% tabs %}
{% tab title="Bash" %}

```sh
npx slnodejs scan \
  --tokenFile ./sltoken.txt \
  --buildSessionIdFile buildSessionId \
  --scanDir ./src \
  --awsConfigure
```

{% endtab %}

{% tab title="GitHub Actions" %}

```yaml
- name: SeaLights scan (Lambda)
  run: |
    npx slnodejs scan \
      --token "${{ secrets.SL_TOKEN }}" \
      --buildSessionIdFile buildSessionId \
      --scanDir ./src \
      --awsConfigure
```

{% endtab %}
{% endtabs %}

Use the same `--scanDir` later when you configure the function.

{% hint style="info" %}
If you already have a working `slnodejs scan` command, keep it and add `--awsConfigure`.
{% endhint %}
{% endstep %}

{% step %}

## Add the SeaLights Lambda Layer

Attach the SeaLights Lambda Layer to each function that should report coverage.

Example `serverless.yml`:

```yaml
functions:
  myLambda:
    handler: src/myLambda.handler
    layers:
      - arn:aws:lambda:eu-west-1:159616352881:layer:sl-nodejs-layer:44
```

Or define it at the provider level:

```yaml
provider:
  layers:
    - arn:aws:lambda:eu-west-1:159616352881:layer:sl-nodejs-layer:44
```

{% hint style="info" %}
Use the SeaLights layer ARN that matches your AWS region and published layer version.
{% endhint %}
{% endstep %}

{% step %}

## Configure environment variables

Set the required variables on each function that should upload coverage.

```yaml
environment:
  AWS_LAMBDA_EXEC_WRAPPER: /opt/sealights-extension
  SL_TOKEN: your-sl-token
  SL_BUILD_SESSION_ID: your-build-session-id
  SL_PROJECT_ROOT: ./src
  LAB_ID: lambda-test
```

Variable notes:

* `AWS_LAMBDA_EXEC_WRAPPER` activates the SeaLights wrapper.
* `SL_PROJECT_ROOT` should match the code root used during `scan`.
* `LAB_ID` should identify the environment or test lab that invokes the function.

{% hint style="warning" %}
Do not hardcode production secrets in the manifest. Inject `SL_TOKEN` from your deployment system or secret manager.
{% endhint %}
{% endstep %}

{% step %}

## Configure the collector

Make sure the collector accepts NYC coverage uploads.

```yaml
collectors:
  properties:
    enableNYCCollector: true
    nycCollectorUploadInterval: 60
```

{% hint style="info" %}
For the full collector setup, see [HTTPS Collector setup reference](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/https-collector/download-and-installation.md#configuration-file-reference).
{% endhint %}
{% endstep %}

{% step %}

## Validate the setup

Deploy the function and invoke it at least once.

Then validate:

1. Invoke the Lambda function.
2. Open [Agent Monitor](/knowledgebase/setup-and-configuration/monitoring/sealights-cockpit/agent-monitor.md).
3. Confirm the Lambda agent appears.
4. Confirm the collector receives coverage activity.

{% hint style="success" %}
When both the function and collector report activity, SeaLights is collecting Lambda coverage.
{% endhint %}
{% endstep %}

{% step %}

## Run your tests

Once the function is deployed with the SeaLights layer, continue to [Capturing Tests](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/capturing-tests.md).
{% endstep %}
{% endstepper %}

## References

### How the Lambda wrapper works

At invocation time, AWS starts the SeaLights wrapper before your handler.

1. The wrapper intercepts the Lambda startup through `AWS_LAMBDA_EXEC_WRAPPER`.
2. SeaLights starts coverage collection before your handler runs.
3. After execution completes, SeaLights converts coverage into a footprint and sends it to the collector.

<div data-with-frame="true"><figure><img src="/files/oRwx7C2iJcYsXFPKmjLJ" alt=""><figcaption></figcaption></figure></div>

<div data-with-frame="true"><figure><img src="/files/YVK1M1BkM5ydxl91NyQl" alt=""><figcaption></figcaption></figure></div>

{% hint style="info" %}
Want a working reference? See the [SeaLights Lambda example project](https://github.com/Sealights/SL.OnPremise.Lambda.Layers/tree/master/node/example).
{% endhint %}

### Working with other Lambda layers

SeaLights supports common observability wrappers.

| Tool      | Exec wrapper value  | Behavior                |
| --------- | ------------------- | ----------------------- |
| Dynatrace | `/opt/dynatrace`    | Supported automatically |
| OTEL      | `/opt/otel-handler` | Supported automatically |

If needed, disable wrapper integration explicitly:

```yaml
environment:
  DISABLE_OTEL_HANDLER: true
  DISABLE_DYNATRACE: true
```

### Troubleshooting

Check these first if the function runs but no coverage appears:

* Confirm the function includes the SeaLights layer ARN.
* Confirm `AWS_LAMBDA_EXEC_WRAPPER` is set to `/opt/sealights-extension`.
* Confirm `SL_BUILD_SESSION_ID` matches the build you scanned.
* Confirm `SL_PROJECT_ROOT` matches the scanned source root.
* Invoke the function at least once after deployment.

### Parameters

| Variable / setting           | Purpose                                                    |
| ---------------------------- | ---------------------------------------------------------- |
| `--awsConfigure`             | Prepares the build scan for AWS Lambda runtime attachment. |
| `AWS_LAMBDA_EXEC_WRAPPER`    | Starts the SeaLights wrapper before the Lambda handler.    |
| `SL_TOKEN`                   | Authenticates the function with SeaLights.                 |
| `SL_BUILD_SESSION_ID`        | Connects coverage to the scanned build session.            |
| `SL_PROJECT_ROOT`            | Points to the Lambda source root used during `scan`.       |
| `LAB_ID`                     | Groups coverage by environment, lab, or execution context. |
| `enableNYCCollector`         | Enables collector-side NYC coverage ingestion.             |
| `nycCollectorUploadInterval` | Controls how often coverage data is uploaded.              |


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
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=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.