AWS Lambda Support

SeaLights provides a simple way to collect code coverage from AWS Lambda functions using a lightweight Lambda Layer for Node.js runtimes. The integration requires minimal changes to your deployment and no changes to your application code.

Overview

To use SeaLights with AWS Lambda, you’ll:

• Add the SeaLights Layer to your function.

• Set a few required environment variables.

• Ensure your SeaLights collector is configured to accept coverage from Lambda executions.

Requirements

Before starting:

• Node.js version 16.20.2 or higher.

• AWS Lambda using a supported Node.js runtime (e.g., nodejs16.x, nodejs18.x).

• AWS CLI or Serverless Framework access to modify function deployment.

• SeaLights agent token and build session ID.

Important: When scanning your code using slnodejs scan, you must add the --awsConfigure flag to ensure proper Lambda support.

---

How It Works

When a Lambda function is instrumented with the SeaLights agent, the SeaLights Lambda Layer wraps the original handler and collects coverage during its execution. The process is seamless and transparent to your function code.

The sequence works as follows:

1. SeaLights Layer is invoked first: AWS uses the AWS_LAMBDA_EXEC_WRAPPER to redirect the function call.

2. Coverage starts before your original handler is called.

3. The original Lambda function runs as usual.

4. When your function completes, coverage is stopped and converted into a footprint.

5. The footprint is sent to the SeaLights collector, and the original response is returned.

You can see this flow in the diagram below:

This design ensures accurate, real-time coverage data with minimal impact on performance or function logic.

Configuration

Step 1: Add the SeaLights Lambda Layer

In your deployment manifest (serverless.yml or AWS config), add the following layer to each function or define it globally:

yamlCopyEdit# At the function level
functions:
  myLambda:
    handler: src/myLambda.handler
    layers:
      - arn:aws:lambda:eu-west-1:159616352881:layer:sl-nodejs-layer:44

Or define it globally:

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

---

Step 2: Set Environment Variables

Configure the following environment variables for each function that should report coverage:

yamlCopyEditenvironment:
  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

These variables are used by the SeaLights agent to identify your function and store coverage data. The AWS_LAMBDA_EXEC_WRAPPER is required to enable the layer functionality.

---

Step 3: Configure the SeaLights Collector

Your collector should include the following settings:

yamlCopyEditcollectors:
  properties:
    enableNYCCollector: true
    nycCollectorUploadInterval: 60

These settings enable the SeaLights agent to collect and upload coverage data from Lambda executions.

---

Step 4: Verify the Setup in the SeaLights Cockpit

Once your Lambda function is deployed and invoked:

• You should see two entries in the Live Agents Monitor in the SeaLights Cockpit:

  1. The Application (your Lambda function)

  2. The Collector reporting the coverage

If both are visible, your setup is complete and data collection has started successfully.

---

Additional Notes

Working with Other Lambda Layers

SeaLights is compatible with third-party Lambda observability layers:

Tool	Exec Wrapper Value	Behavior
Dynatrace	/opt/dynatrace	Supported automatically
OTEL	/opt/otel-handler	Supported automatically

To explicitly disable integration with OTEL or Dynatrace:

yamlCopyEditenvironment:
  DISABLE_OTEL_HANDLER: true
  DISABLE_DYNATRACE: true

Troubleshooting

• Make sure AWS_LAMBDA_EXEC_WRAPPER is set correctly.

• Ensure the layer ARN is present in the function configuration.

• Verify your SL_TOKEN, SL_BUILD_SESSION_ID, and SL_PROJECT_ROOT are set and correct.

• The function must run at least once to appear in the Live Agents Monitor.

Example Project

You can review a working Serverless Framework example here: https://github.com/Sealights/SL.OnPremise.Lambda.Layers/tree/master/node/example

It includes a basic function and pre-configured settings for SeaLights Lambda integration.