Trace AWS Lambda Node.js functions

To achieve complete observability over AWS Lambda Node.js functions, Lumigo's distributed tracing supports both automatic instrumentation and manual instrumentation.

Automatic Instrumentation

By using Lumigo lambda layer our auto-tracing feature automatically adds the Lumigo tracer to your functions, instrumenting your entire code base, without changing a single line of code.

Instrumenting functions via the Lumigo UI

You can easily instrument your functions via the Lumigo UI. To do so:

• Go to the Functions page
• Select the functions you want to instrument
• Click Auto-trace or the Tracing toggle

⚡

Lumigo auto-tracing allows you to instrument your functions automatically, without touching your function source code. This can save you time, reduce your package size, and keep your tracing needs from impacting your functional code. Learn more about auto-tracing

Manual Instrumentation

The @lumigo/tracer package is Lumigo's Node.js agent for distributed tracing and performance monitoring on AWS Lambda. It allows you to pursue automated metric gathering through Lambda Layers, automated metric gathering and instrumentation through the Serverless framework, or manual metric creation and implementation.

Add the Lumigo Tracer to your application

Install the @lumigo/tracer package using NPM:

$ npm i @lumigo/tracer

Next, wrap your _handler _in Lumigo's _trace _function.

const lumigo = require('@lumigo/tracer')()

const myHandler = async (event, context, callback) => { ... }

exports.handler = lumigo.trace(myHandler)

Connect Your Lumigo Account

Set your Lumigo token as the LUMIGO_TRACER_TOKEN environment variable of your Lambda function; refer to the Using AWS Lambda environment variables documentation for more information. Your Lumigo token is available in Settings -> Tracing -> Manual tracing, see the Lumigo Tokens documentation.

We advise you to use the most secure available to you to store secrets such as your LUMIGO_TRACER_TOKEN; refer to AWS Lambda's Securing environment variables documentation for guidance on keeping the values of your Lambda environment variables secure.

Configuration

@lumigo/tracer offers several different configuration options. Pass these to the Lambda function as environment variables:

• LUMIGO_DEBUG=TRUE - Enables debug logging
• LUMIGO_SECRET_MASKING_REGEX='["regex1", "regex2"]' - Prevents Lumigo from sending keys that match the supplied regular expressions. All regular expressions are case-insensitive. By default, Lumigo applies the following regular expressions:* ["._pass.", ".key.", ".secret.", ".credential.", ".passphrase."]_.
• LUMIGO_DOMAINS_SCRUBBER='["._secret."]'_ - Prevents Lumigo from collecting both request and response details from a list of domains. This accepts a comma-separated list of regular expressions that is JSON-formatted. By default, the tracer uses ["secretsmanager...amazonaws.com", "ssm...amazonaws.com", "kms...amazonaws.com"]*. Note - These defaults are overridden when you define a different list of regular expressions.
• LUMIGO_SWITCH_OFF=TRUE - In the event a critical issue arises, this turns off all actions that Lumigo takes in response to your code. This happens without a deployment, and is picked up on the next function run once the environment variable is present.

Library support

Databases

MongoDB and Bundlers

MongoDB and Esbuild

If your Lambda function is bundled using esbuild, add the following to your esbuild.config.json file:

{
  "external": ["mongodb"],
}

Depending on whether you use Atlas and how you authenticate with it, you may need to also add as external the aws4 package, that is used in some setups for authentication:

{
  "external": ["mongodb", "aws4"],
}

MongoDB and Webpack

If your Lambda function is bundled using Webpack, add the following to your webpack.config file:

externals: {
  mongodb: 'mongodb',
},

Depending on whether you use Atlas and how you authenticate with it, you may need to also add as external the aws4 package, that is used in some setups for authentication:

externals: {
  mongodb: 'mongodb',
  aws4: 'aws4',
},

📘

Do you need Lumigo to support a different package?

If Lumigo does not yet support a package you use, please contact our support.

Tracing through containers and OpenTelemetry

To be able to trace scenarios in which a Lambda function sends HTTP requests to an application instrumented with OpenTelemetry, like those using the Lumigo OpenTelemetry Distro for JS and Lumigo OpenTelemetry Distro for Python or other OpenTelemetry SDKs, the Lumigo Python tracer can optionally add W3C TraceContext HTTP headers to outgoing requests.

The support of W3C TraceContext in the Lambda Node.js tracer is currently opt-in via the LUMIGO_PROPAGATE_W3C=true environment variable.

👍

Supported tracer and layer versions

W3C TraceContext is supported by the @lumigo/tracer package v1.75.0 and above. The minimum layer versions are listed here by AWS region (applicable to all supported Node.js runtimes).

📘

Why opt-in?

We have implemented support for W3C TraceContext in the Lambda Node.js tracer as opt-in out of an abundance of caution. In some seldom cases, like invoking some Apple APIs, the HTTP request is signed, based on the current headers it has, before our tracer can interact with it by adding the W3C TraceContext traceparent header, and that may cause issues. Note that most AWS APIs use Signature Version 4 (SigV4) to sign requests, and the Lambda Node.js tracer will not add the W3C TraceContext traceparent headers to them.

We may consider changing the W3C TraceContext to be opt-out later down the road, based on your feedback.