Serverless in Node.js

AWS Lambda

To achieve complete observability & monitoring over AWS Lambda functions, install Helios using one of the mechanisms supported below.

Navigate to your project's root directory, and install the latest Helios OpenTelemetry SDK:

npm install --save helios-opentelemetry-sdk

👉

Helios Lambda layer

Alternatively, you may add the Helios Lambda layer that includes the Helios SDK, without having to install directly.

Get the latest version of Helios' auto-instrumentation Lambda layer.
Go to the user menu on the top right corner and select Settings > General.
Copy the Node.js AWS Lambda Layer (ARN).

Please contact us if the layer isn't available in your region.

⚠️ The layer will not work if the Lambda is packaged using webpack or esbuild. In these cases, please use our serverless framework plugin.

👉

Helios serverless plugin

Helios provides a Serverless Framework plugin for streamlining the instrumentation of Lambda functions. Use it by:

1. Adding helios-serverless-plugin as a dev dependency to your project.
2. In your serverless.yml file, add helios-serverless-plugin as the first plugin.
   plugins:
- helios-serverless-plugin
3. Add the following configuration under custom:
   custom:
helios:
api_token: <YOUR_HELIOS_TOKEN>
typescript: <true is you're using typescript, default is false>
environment: <optional>

Define the following environment variable in your Lambda configuration:

NODE_OPTIONS="--require helios-opentelemetry-sdk"
HS_TOKEN=<API_TOKEN> # TODO: Replace value with API token from Helios.
HS_ENVIRONMENT="<ENVIRONMENT_NAME>" # TODO: Replace value with service environment.

Note: The service name is automatically populated with the function name.

Using AWS step functions

In order to apply context propagation when using AWS step functions, make sure to define the following env var as well:

HS_LAMBDA_STEP_FUNCTION_MODE=true

serverless-webpack

Wrap your Lambda handler function as demonstrated in the following example:

const { instrumentLambda } = require('helios-opentelemetry-sdk');

const originHandler = async (event) => {..} // The original Lambda handler

const handler = instrumentLambda(originHandler);

export default handler;

Define the following environment variables in your Lambda configuration:

HS_AUTO_INIT=true,
HS_TOKEN=<API_TOKEN>,           // TODO: Insert API token from Helios.
HS_ENVIRONMENT=<ENVIRONMENT>,   // Defaults to process.env.NODE_ENV if omitted.
HS_COMMIT_HASH=<COMMIT_HASH>,   // Defaults to process.env.COMMIT_HASH if omitted.

Note: The service name is automatically populated with the function name.

📘

OpenTelemetry dynamic require

For node_modules that are not part of the webpack bundle (configured as external), OpenTelemetry instrumentation should seamlessly work.
In case those are bundled, instrumentations should also work (even though webpack might print warnings in the build process).

👍

All set

After setup is complete and once the service is up and running, it will show up in the Helios application.