Skip to content

Latest commit

 

History

History
194 lines (130 loc) · 8.33 KB

README.md

File metadata and controls

194 lines (130 loc) · 8.33 KB
Raw

lumigo-node 🌠

CircleCI codecov npm version License semantic-release

This is @lumigo/tracer, Lumigo's Node.js agent for distributed tracing and performance monitoring.

Supported NodeJS runtimes: 12.x, 14.x, 16.x, and 18.x

Usage

The @lumigo/tracer package 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.

With Lambda Layers

  • When configuring your Lambda functions, include the appropriate Lambda Layer ARN from these tables

Note - Lambda Layers are an optional feature. If you decide to use this capability, the list of Lambda layers available is available here.

With Serverless framework

Manually

To manually configure Lumigo in your Lambda functions:

  • First, install the @lumigo/tracer package using your preferred package manager:
$ npm i @lumigo/tracer
# or
$ yarn add @lumigo/tracer
  • Next, wrap your handler in Lumigo's trace function:
// javascript
const lumigo = require('@lumigo/tracer')()

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

exports.handler = lumigo.trace(myHandler)
// typescript
import lumigo from '@lumigo/tracer';

const tracer = lumigo();

export const handler = tracer.trace(async (event, context) => {
  ...
});

Note

For Typescript users, you must add the following to your tsconfig.json file:

{
  ...,
  "esModuleInterop": true,
}

You can read more about it here

  • Your function is now fully instrumented

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 -> Lumigo Token for Tracing, see the Lumigo Tokens documentation.

We advise you to store secrets such as your LUMIGO_TRACER_TOKEN securely; 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_TRACER_TOKEN - Your Lumigo token, used for authentication. It can also be passed to the tracer as a parameter: 
    const lumigo = require('@lumigo/tracer')({ token: 'YOUR-TOKEN-HERE' });
  • 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.*"].
    • We support more granular masking using the following parameters. If not given, the above configuration is the fallback: LUMIGO_SECRET_MASKING_REGEX_HTTP_REQUEST_BODIES, LUMIGO_SECRET_MASKING_REGEX_HTTP_REQUEST_HEADERS, LUMIGO_SECRET_MASKING_REGEX_HTTP_RESPONSE_BODIES, LUMIGO_SECRET_MASKING_REGEX_HTTP_RESPONSE_HEADERS, LUMIGO_SECRET_MASKING_REGEX_HTTP_QUERY_PARAMS.
  • LUMIGO_SECRET_MASKING_EXACT_PATH='["key1.key2", "key3.key4"]' - Prevents Lumigo from sending keys that match the supplied path (we support nested fields). All paths are case-insensitive.
  • 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_PROPAGATE_W3C=TRUE - Add W3C TraceContext headers to outgoing HTTP requests. This enables uninterrupted transactions with applications traced with OpenTelemetry.
  • 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.
  • LUMIGO_AUTO_TAG=key1.key2,key3 - Configure execution tags that will be driven directly from the event for the supplied key (we support nested fields).
  • LUMIGO_STEP_FUNCTION=TRUE - for Lambda functions that are triggered by your step function’s state machine.

Step Functions

If your function is part of a set of step functions, you can add the flag step_function: true to the Lumigo tracer import. Alternatively, you can configure the step function using an environment variable LUMIGO_STEP_FUNCTION=True. When this is active, Lumigo tracks all states in the step function in a single transaction, easing debugging and observability.

const lumigo = require('@lumigo/tracer')({ step_function: true })

Note: the tracer adds the key "_lumigo" to the return value of the function.

If you override the "Parameters" configuration, add "_lumigo.$": "$._lumigo" to ensure this value is still present.

Below is an example configuration for a Lambda function that is part of a step function that has overridden its parameters:

"States": {
    "state1": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:us-west-2:ACCOUNT:function:FUNCTION_NAME",
      "Parameters": {
          "Changed": "parameters",
          "_lumigo.$": "$._lumigo"
        },
      "Next": "state2"
    },
    "state2": {
      "Type": "pass",
      "End": true
    }
}

Logging Programmatic Errors

With the tracer configured, simply call

console.log("[LUMIGO_LOG] <YOUR_MESSAGE>");

to create custom errors that are visible throughout the platform. This can be used anywhere in your Lambda code, and is included with the @lumigo/tracer package.

Adding Execution Tags

You can add execution tags to a function with dynamic values using the parameter addExecutionTag.

These tags will be searchable from within the Lumigo platform.

Adding tags for Manual tracing

To add a tag to a manual trace statement:

  • Add the following to your code:

    const lumigo = require('@lumigo/tracer')({ token: 'YOUR-TOKEN-HERE' })

  • Add execution tags by using

    lumigo.addExecutionTag('<key>', '<value>');

Adding tags for Auto tracing

To add a tag to an automatically-traced function:

  • Add the following to the top of your handler's .js file:

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

  • Use

    lumigo.addExecutionTag('<key>', '<value>');

    anywhere in your lambda code.

Execution Tag Limitations

Execution tags are subject to the following limitations:

  • The maximum number of tags is 50.
  • Key length must be between 1 and 50.
  • Value length must be between 1 and 70.

Scrubbing Limitations

Secrets scrubbing are subject to the following limitations:

  • Only JSON data secrets scrubbing is supported