{"id":13522920,"url":"https://github.com/lumigo-io/lumigo-node","last_synced_at":"2026-01-07T05:48:14.431Z","repository":{"id":35058626,"uuid":"185531534","full_name":"lumigo-io/lumigo-node","owner":"lumigo-io","description":"Lumigo Node tracer for AWS Lambda","archived":false,"fork":false,"pushed_at":"2025-03-20T15:16:50.000Z","size":5094,"stargazers_count":77,"open_issues_count":11,"forks_count":12,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-03-22T03:02:30.728Z","etag":null,"topics":["debugging","distributed-tracing","instrumentation","lumigo","monitoring","node","serverless","tracer"],"latest_commit_sha":null,"homepage":"https://lumigo.io","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lumigo-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-05-08T05:03:19.000Z","updated_at":"2025-03-20T15:16:54.000Z","dependencies_parsed_at":"2023-12-20T16:33:29.296Z","dependency_job_id":"1910aa47-8358-44af-ba7c-036c145c8666","html_url":"https://github.com/lumigo-io/lumigo-node","commit_stats":{"total_commits":1125,"total_committers":38,"mean_commits":"29.605263157894736","dds":0.7386666666666667,"last_synced_commit":"829238faef4a77419970760a89f9def5bc05bda1"},"previous_names":[],"tags_count":239,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lumigo-io%2Flumigo-node","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lumigo-io%2Flumigo-node/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lumigo-io%2Flumigo-node/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lumigo-io%2Flumigo-node/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lumigo-io","download_url":"https://codeload.github.com/lumigo-io/lumigo-node/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246558108,"owners_count":20796696,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["debugging","distributed-tracing","instrumentation","lumigo","monitoring","node","serverless","tracer"],"created_at":"2024-08-01T06:00:53.731Z","updated_at":"2026-01-07T05:48:14.425Z","avatar_url":"https://github.com/lumigo-io.png","language":"JavaScript","funding_links":[],"categories":["Layers"],"sub_categories":["Monitoring"],"readme":"# lumigo-node :stars:\n\n[![CircleCI](https://dl.circleci.com/status-badge/img/gh/lumigo-io/lumigo-node/tree/master.svg?style=svg)](https://dl.circleci.com/status-badge/redirect/gh/lumigo-io/lumigo-node/tree/master)\n[![codecov](https://codecov.io/gh/lumigo-io/lumigo-node/branch/master/graph/badge.svg?token=mUkKlI8ifC)](https://codecov.io/gh/lumigo-io/lumigo-node)\n[![npm version](https://badge.fury.io/js/%40lumigo%2Ftracer.svg)](https://badge.fury.io/js/%40lumigo%2Ftracer)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)\n\nThis is [`@lumigo/tracer`](https://), Lumigo's Node.js agent for distributed tracing and performance monitoring.\n\nSupported NodeJS runtimes: 16.x (deprecated by AWS), 18.x (deprecated by AWS), 20.x, 22.x and 24.x\n\nPlease refer to AWS NodeJS runtime support [here](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html).\n## Usage\n\nThe `@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.\n\n### With Lambda Layers\n\n* When configuring your Lambda functions, include the appropriate Lambda Layer ARN [from these tables](https://github.com/lumigo-io/lumigo-node/blob/master/layers)\n\n*Note* - Lambda Layers are an optional feature. If you decide to use this capability, the list of Lambda layers available is available [here.](https://github.com/lumigo-io/lumigo-node/blob/master/layers)\n\n### With Serverless framework\n\n* To configure the Serverless Framework to work with Lumigo, simply install our plugin: [**serverless-lumigo-plugin**](https://github.com/lumigo-io/serverless-lumigo-plugin/blob/master/README.md)\n\n### Manually\n\nTo manually configure Lumigo in your Lambda functions:\n\n* First, install the `@lumigo/tracer` package using your preferred package manager:\n\n```bash\n$ npm i @lumigo/tracer\n# or\n$ yarn add @lumigo/tracer\n```\n\n* Next, wrap your `handler` in Lumigo's `trace` function:\n\n```javascript\n// javascript\nconst lumigo = require('@lumigo/tracer')()\n\nconst myHandler = async (event, context, callback) =\u003e { ... }\n\nexports.handler = lumigo.trace(myHandler)\n```\n\n```typescript\n// typescript\nimport lumigo from '@lumigo/tracer';\n\nconst tracer = lumigo();\n\nexport const handler = tracer.trace(async (event, context) =\u003e {\n  ...\n});\n```\n\n#### Note\n\nFor Typescript users, you must add the following to your `tsconfig.json` file:\n\n```json\n{\n  ...,\n  \"esModuleInterop\": true,\n}\n```\n\nYou can read more about it [here](https://www.typescriptlang.org/tsconfig#esModuleInterop)\n\n* Your function is now fully instrumented\n\n## Connect Your Lumigo Account\nSet your Lumigo token as the `LUMIGO_TRACER_TOKEN` environment variable of your Lambda function; refer to the [Using AWS Lambda environment variables](https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars.html) documentation for more information. Your Lumigo token is available in `Settings -\u003e Tracing -\u003e Lumigo Token for Tracing`, see the [Lumigo Tokens](https://docs.lumigo.io/docs/lumigo-tokens) documentation.\n\nWe advise you to store secrets such as your LUMIGO_TRACER_TOKEN securely; refer to AWS Lambda's [Securing environment variables](https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars.html#configuration-envvars-encryption) documentation for guidance on keeping the values of your Lambda environment variables secure.\n## Configuration\n\n`@lumigo/tracer` offers several different configuration options. Pass these to the Lambda function as environment variables:\n\n* `LUMIGO_TRACER_TOKEN` - Your Lumigo token, used for authentication. \n  It can also be passed to the tracer as a parameter:\n  ```javascript\n  const lumigo = require('@lumigo/tracer')({ token: 'YOUR-TOKEN-HERE' });\n  ```\n* `LUMIGO_DEBUG=TRUE` - Enables debug logging.\n* `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.*\"]`.\n  * 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`.\n* `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.\n* `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.\n* `LUMIGO_PROPAGATE_W3C=TRUE` - Add W3C TraceContext headers to outgoing HTTP requests. This enables uninterrupted transactions with applications traced with OpenTelemetry.\n* `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.\n* `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).\n* `LUMIGO_STEP_FUNCTION=TRUE` - for Lambda functions that are triggered by your step function’s state machine.\n\n### Step Functions\n\nIf 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.\n\n```javascript\nconst lumigo = require('@lumigo/tracer')({ step_function: true })\n```\n\nNote: the tracer adds the key `\"_lumigo\"` to the return value of the function.\n\nIf you override the `\"Parameters\"` configuration, add `\"_lumigo.$\": \"$._lumigo\"` to ensure this value is still present.\n\nBelow is an example configuration for a Lambda function that is part of a step function that has overridden its parameters:\n\n```json\n\"States\": {\n    \"state1\": {\n      \"Type\": \"Task\",\n      \"Resource\": \"arn:aws:lambda:us-west-2:ACCOUNT:function:FUNCTION_NAME\",\n      \"Parameters\": {\n          \"Changed\": \"parameters\",\n          \"_lumigo.$\": \"$._lumigo\"\n        },\n      \"Next\": \"state2\"\n    },\n    \"state2\": {\n      \"Type\": \"pass\",\n      \"End\": true\n    }\n}\n```\n\n## Logging Programmatic Errors\n\nWith the tracer configured, simply call\n\n```javascript\nconsole.log(\"[LUMIGO_LOG] \u003cYOUR_MESSAGE\u003e\");\n```\n\nto 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.\n\n## Adding Execution Tags\n\nYou can add execution tags to a function with dynamic values using the parameter `addExecutionTag`.\n\nThese tags will be searchable from within the Lumigo platform.\n\n### Adding tags for Manual tracing\n\nTo add a tag to a manual trace statement:\n\n* Add the following to your code:\n\n  ```javascript\n  const lumigo = require('@lumigo/tracer')({ token: 'YOUR-TOKEN-HERE' })\n  ```\n\n* Add execution tags by using\n\n  ```javascript\n  lumigo.addExecutionTag('\u003ckey\u003e', '\u003cvalue\u003e');\n  ```\n\n### Adding tags for Auto tracing\n\nTo add a tag to an automatically-traced function:\n\n* Add the following to the top of your handler's .js file:\n\n  ```javascript\n  const lumigo = require('@lumigo/tracer')\n  ```\n\n* Use\n\n  ```javascript\n  lumigo.addExecutionTag('\u003ckey\u003e', '\u003cvalue\u003e');\n  ```\n\n  anywhere in your lambda code.\n\n### Execution Tag Limitations\n\nExecution tags are subject to the following limitations:\n\n* The maximum number of tags is 50.\n* Key length must be between 1 and 50.\n* Value length must be between 1 and 70.\n\n### Scrubbing Limitations\n\nSecrets scrubbing are subject to the following limitations:\n\n* Only JSON data secrets scrubbing is supported\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flumigo-io%2Flumigo-node","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flumigo-io%2Flumigo-node","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flumigo-io%2Flumigo-node/lists"}