AWS Lambda Instrumentation (serverless)

Capture runtime coverage from Node.js AWS Lambda functions by attaching the SeaLights Lambda Layer.

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

When you scan Lambda code with slnodejs scan, include --awsConfigure.

1

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.

Bash

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

GitHub Actions

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

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

If you already have a working slnodejs scan command, keep it and add --awsConfigure.

2

Add the SeaLights Lambda Layer

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

Example serverless.yml:

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:

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

Use the SeaLights layer ARN that matches your AWS region and published layer version.

3

Configure environment variables

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

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.

Do not hardcode production secrets in the manifest. Inject SL_TOKEN from your deployment system or secret manager.

4

Configure the collector

Make sure the collector accepts NYC coverage uploads.

collectors:
  properties:
    enableNYCCollector: true
    nycCollectorUploadInterval: 60

For the full collector setup, see HTTPS Collector setup reference.

5

Validate the setup

Deploy the function and invoke it at least once.

Then validate:

1. Invoke the Lambda function.
2. Open Agent Monitor.
3. Confirm the Lambda agent appears.
4. Confirm the collector receives coverage activity.

When both the function and collector report activity, SeaLights is collecting Lambda coverage.

6

Run your tests

Once the function is deployed with the SeaLights layer, continue to Capturing Tests.

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.

Want a working reference? See the SeaLights Lambda example project.

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:

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.