\n\n[](https://travis-ci.com/epsagon/epsagon-node)\n[](https://badge.fury.io/js/epsagon)\n[](https://github.com/semantic-release/semantic-release)\n\n# Epsagon Tracing for Node.js\nThis package provides tracing to Node.js applications for the collection of distributed tracing and performance metrics in [Epsagon](https://app.epsagon.com/?utm_source=github).\n\n## Contents\n\n- [Installation](#installation)\n- [Usage](#usage)\n - [Auto-tracing](#auto-tracing)\n - [Calling the SDK](#calling-the-sdk)\n - [Tagging Traces](#tagging-traces)\n - [Custom Errors](#custom-errors)\n - [Filter Sensitive Data](#filter-sensitive-data)\n - [Ignore Endpoints](#ignore-endpoints)\n - [Trace URL](#trace-url)\n- [Frameworks](#frameworks)\n- [Integrations](#integrations)\n- [Configuration](#configuration)\n- [Getting Help](#getting-help)\n- [Opening Issues](#opening-issues)\n- [License](#license)\n\n## Installation\n\nTo install Epsagon, simply run:\n```sh\nnpm install epsagon\n```\n\n## Usage\n\n### Auto-tracing\n\nThe simplest way to get started in some frameworks is to install `epsagon-frameworks`:\n```sh\nnpm install epsagon-frameworks\n```\n\n[`epsagon-frameworks`](https://github.com/epsagon/epsagon-node-frameworks) extends the base `epsagon` support to more frameworks.\n\nAnd run your node command:\n```sh\nexport EPSAGON_TOKEN=\nexport EPSAGON_APP_NAME=\nexport NODE_OPTIONS='-r epsagon-frameworks'\n\n```\n\nFor example:\n```sh\nexport EPSAGON_TOKEN=\nexport EPSAGON_APP_NAME=express-prod\nexport NODE_OPTIONS='-r epsagon-frameworks'\nnode app.js\n```\n\nWhen using inside a `Dockerfile`, you can use `ENV` instead of `export`.\n\nYou can see the list of auto-tracing [supported frameworks](#frameworks)\n\n### Calling the SDK\n\nAnother simple alternative is to copy the snippet into your code:\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTo run on your framework please refer to [supported frameworks](#frameworks)\n\n\n### Tagging Traces\n\nYou can add custom tags to your traces, for easier filtering and aggregations.\n\nAdd the following call inside your code:\n```javascript\nepsagon.label('key', 'value');\nepsagon.label('userId', userId);\n```\n\nYou can also use it to ship custom metrics:\n```javascript\nepsagon.label('key', 'metric')\nepsagon.label('itemsInCart', itemsInCart)\n```\n\nYou can also use it iniside init function:\n```javascript\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n labels: [['key', 'value'], ['userId', userId]],\n});\n```\n\nValid types are `string`, `boolean` and `number`.\n\nIn some [frameworks](#frameworks) tagging can be done in different ways.\n\n### Custom Errors\n\nYou can set a trace as an error (although handled correctly) to get an alert or just follow it on the dashboard.\n\nAdd the following call inside your code:\n```javascript\ntry {\n // something bad happens\n} catch (err) {\n epsagon.setError(err);\n}\n\n// Or manually specify Error object\nepsagon.setError(Error('My custom error'));\n```\n\nIn some [frameworks](#frameworks) custom errors can be declared in different ways.\n\n### Filter Sensitive Data\n\nYou can pass a list of sensitive properties and hostnames and they will be filtered out from the traces:\n\n```javascript\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n ignoredKeys: ['password', /.*_token$/],\n urlPatternsToIgnore: ['example.com', 'auth.com'],\n});\n```\n\nThe `ignoredKeys` property can contain strings (will perform a loose match, so that `First Name` also matches `first_name`), regular expressions, and predicate functions.\nAlso, you can set `urlPatternsToIgnore` to ignore HTTP calls to specific domains.\n\n\n### Ignore Endpoints\n\nYou can ignore certain incoming requests by specifying endpoints:\n```javascript\nepsagon.ignoreEndpoints(['/healthcheck'])\n```\n\n### Trace URL\n\nYou can get the Epsagon dashboard URL for the current trace, using the following:\n```node\n# Inside some endpoint or function\nconsole.log('Epsagon trace URL:', epsagon.getTraceUrl())\n```\n\nThis can be useful to have an easy access the trace from different platforms.\n\n\n## Frameworks\n\nThe following frameworks are supported by Epsagon.\nSome require installing also [`epsagon-frameworks`](https://github.com/epsagon/epsagon-node-frameworks)\n\n|Framework |Supported Version |Epsagon Library |Auto-tracing Supported |\n|----------------------------------------|---------------------------|---------------------------------------------------|-----------------------------------------------------|\n|[AWS Lambda](#aws-lambda) |All |`epsagon` |
|\n\n\n### AWS Lambda\n\nTracing Lambda functions can be done in three methods:\n1. Auto-tracing through the Epsagon dashboard.\n2. Using the [`serverless-plugin-epsagon`](https://github.com/epsagon/serverless-plugin-epsagon) if you're using The Serverless Framework.\n3. Calling the SDK.\n\n**Make sure to choose just one of the methods**\n\nCalling the SDK is simple:\n\n```javascript\nconst epsagon = require('epsagon');\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n\n// Wrap your entry point\nmodule.exports.handler = epsagon.lambdaWrapper((event, context, callback) => {\n // Your code is here\n});\n\n// Async functions example\nmodule.exports.handler = epsagon.lambdaWrapper(async (event) => {\n // Your code is here\n});\n```\n\n### Step Functions\n\nTracing Step Functions is similar to regular Lambda functions, but the wrapper changes from `lambdaWrapper` to `stepLambdaWrapper`:\n\n```javascript\nconst epsagon = require('epsagon');\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n\n// Wrap your entry point\nmodule.exports.handler = epsagon.stepLambdaWrapper((event, context, callback) => {\n // Your code is here\n});\n\n// Async functions example\nmodule.exports.handler = epsagon.stepLambdaWrapper(async (event) => {\n // Your code is here\n});\n```\nECS Step - You should pass Epsagon step_dict id from ECS state input into ```EPSAGON_STEPS_ID``` environment variables of the container, ```EPSAGON_STEPS_NUM``` is the step number of the ECS (default: 0). check the [configuration](https://github.com/epsagon/epsagon-node/#configuration) section.\n\n### OpenWhisk Action\n\nYou should pass the Epsagon token to your action as a default parameter, so that you don't have to expose important credentials in your code.\nThe name of the parameter can be configured using `token_param`, in this example we use `epsagon-token`:\n\n```javascript\nconst epsagon = require('epsagon');\n\nfunction main(params) {\n // Your code is here\n}\n\nmodule.exports.main = epsagon.openWhiskWrapper(\n main,\n {\n token_param: 'epsagon-token', // name of the action parameter to take the token from\n appName: 'app-name-stage',\n metadataOnly: false\n }\n);\n```\n\n### AWS Batch\n\nTracing batch jobs running in AWS Batch can be done by wrapping the main handler/entrypoint of the code:\n\n```javascript\nconst epsagon = require('epsagon');\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n\n\nfunction process(params) {\n // Your code is here\n}\n\nconst wrappedProcess = epsagon.wrapBatchJob(process);\n```\n\n### Express\n\nTracing Express application can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the application is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\napp.get('/', (req, res) => {\n req.epsagon.label('key', 'value');\n req.epsagon.setError(Error('My custom error'));\n}\n```\n\n### Hapi\n\nTracing Hapi application can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the application is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\nserver.route({\n method: 'GET',\n path:'/',\n handler: (request, h) => {\n request.epsagon.label('key', 'value');\n request.epsagon.setError(Error('My custom error'));\n }\n});\n```\n\n### Koa\n\nTracing Koa application can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the application is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\napp.use(async ctx => {\n ctx.epsagon.label('key', 'value');\n ctx.epsagon.setError(Error('My custom error'));\n});\n```\n\n### WS (Websocket)\n\nTracing `ws` consumers can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the consumer is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\nsocket.on('message', (message) => {\n message.epsagon.label('key', 'value');\n message.epsagon.setError(Error('My custom error'));\n}) \n```\n\n### KafkaJS\n\nTracing `kafkajs` consumers can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the consumer is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\nawait consumer.run({\n eachMessage: async ({ topic, partition, message }) => {\n message.epsagon.label('key', 'value');\n message.epsagon.setError(Error('My custom error'));\n },\n})\n```\n\n### kafka-node\n\nTracing `kafka0node` consumers can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the consumer is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\nconsumer.on('message', function (message) {\n message.epsagon.label('key', 'value');\n message.epsagon.setError(Error('My custom error'));\n})\n```\n\n### PubSub\n\nTracing `@google-cloud/pubsub` consumers can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the consumer is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\nawait consumer.run({\n eachMessage: async ({ topic, partition, message }) => {\n message.epsagon.label('key', 'value');\n message.epsagon.setError(Error('My custom error'));\n },\n})\n```\n\n### SQS Consumer\n\nTracing [`sqs-consumer`](https://github.com/bbc/sqs-consumer) consumers can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the consumer is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\nconst messageHandler = message => {\n message.epsagon.label('key', 'value');\n message.epsagon.setError(Error('My custom error'));\n};\n```\n\nOr in batch message handler:\n```javascript\nconst batchMessageHandler = messages => {\n messages[0].epsagon.label('key', 'value');\n messages[0].epsagon.setError(Error('My custom error'));\n};\n```\n\n\n### amqplib\n\nTracing amqplib consumers can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the consumer is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\nch.consume(q, function cons(msg) {\n if (msg !== null) {\n msg.epsagon.label('key', 'value');\n msg.epsagon.setError(Error('My custom error'));\n ch.ack(msg);\n }\n});\n```\n\n### bunnybus\n\nTracing bunnybus consumers can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the consumer is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\n// epsagon is added as an argument to the handler\nhandler: async ({message, metaData, ack, rej, requeue, epsagon}) => {\n epsagon.label('key', 'value');\n epsagon.setError(Error('My custom error'));\n await ack();\n}\n```\n\n### NATS\n\nTracing `nats` consumers can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the consumer is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\n\n### Generic\n\nFor any tracing, you can simply use the generic Epsagon wrapper using the following example:\n\n```javascript\nconst epsagon = require('epsagon');\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n\n\nfunction main(params) {\n // Your code is here\n}\n\nconst wrappedMain = epsagon.nodeWrapper(main);\n```\n\n## Integrations\n\nEpsagon provides out-of-the-box instrumentation (tracing) for many popular frameworks and libraries.\n\n|Library |Supported Version |\n|--------------------|---------------------------|\n|http |Fully supported |\n|https |Fully supported |\n|http2 |Fully supported |\n|dns |Fully supported |\n|aws-sdk |`>=2.2.0` |\n|amazon-dax-client |`>=1.0.2` |\n|@google-cloud |`>=2.0.0` |\n|@google-cloud/pubsub|`>=1.1.0` |\n|mysql |`>=2` |\n|mysql2 |`>=1` |\n|pg |`>=4` |\n|mongodb |`>=2.2.12` |\n|kafkajs |`>=1.2.0` |\n|kafka-node |`>=3.0.0` |\n|amqplib |`>=0.5.0` |\n|amqp |`>=0.2.0` |\n|redis |`>=0.12.1` |\n|ioredis |`>=4.0.0` |\n|mqtt |`>=2.13.1` |\n|nats |`>=1.4.0` |\n|openwhisk |`>=3.0.0` |\n|@azure/cosmos |`>=3.7.5` |\n|@azure/storage-blob |`>=12.2.0` |\n|ldapjs |`>=2.1.0` |\n|ws |`>=7.3.1` |\n\n\n\n## Configuration\n\nAdvanced options can be configured as a parameter to the init() method or as environment variables.\n\n|Parameter |Environment Variable |Type |Default |Description |\n|-------------------|---------------------------|-------|-------------|-----------------------------------------------------------------------------------|\n|token |EPSAGON_TOKEN |String |- |Epsagon account token |\n|appName |EPSAGON_APP_NAME |String |`Application`|Application name that will be set for traces |\n|metadataOnly |EPSAGON_METADATA |Boolean|`true` |Whether to send only the metadata (`true`) or also the payloads (`false`) |\n|useSSL |EPSAGON_SSL |Boolean|`true` |Whether to send the traces over HTTPS SSL or not |\n|traceCollectorURL |EPSAGON_COLLECTOR_URL |String |- |The address of the trace collector to send trace to |\n|isEpsagonDisabled |DISABLE_EPSAGON |Boolean|`false` |A flag to completely disable Epsagon (can be used for tests or locally) |\n|ignoredKeys |EPSAGON_IGNORED_KEYS |Array |- |Array of keys names (can be string or regex) to be removed from the trace |\n|urlPatternsToIgnore|EPSAGON_URLS_TO_IGNORE |Array |`[]` |Array of URL patterns to ignore the calls |\n|sendTimeout |EPSAGON_SEND_TIMEOUT_SEC |Float |`1.0` |The timeout duration in seconds to send the traces to the trace collector |\n|decodeHTTP |EPSAGON_DECODE_HTTP |Boolean|`true` |Whether to decode and decompress HTTP responses into the payload |\n|httpErrorStatusCode|EPSAGON_HTTP_ERR_CODE |Integer|`400` |The minimum number of an HTTP response status code to treat as an error |\n|- |EPSAGON_PROPAGATE_LAMBDA_ID|Boolean|`False` |Insert Lambda request ID into the response payload |\n|- |DISABLE_EPSAGON_PATCH |Boolean|`false` |Disable the library patching (instrumentation) |\n|- |EPSAGON_DEBUG |Boolean|`false` |Enable debug prints for troubleshooting |\n|- |EPSAGON_PROPAGATE_NATS_ID |Boolean|`false` |Whether to propagate a correlation ID in NATS.io calls for distributed tracing |\n|- |EPSAGON_ADD_NODE_PATH |String |- |List of folders to looks for node_modules when patching libraries. Separated by `:`|\n|- |EPSAGON_AUTO_ADD_NODE_PATHS|Boolean |`false` |Auto add node_modules sub folders to look when patching libraries. |\n|- |EPSAGON_DNS_INSTRUMENTATION|Boolean|`false` |Whether to capture `dns` calls into the trace |\n|- |EPSAGON_LOGGING_TRACING_ENABLED|Boolean|`true` |whether to add an Epsagon ID to the logs in order to correlate traces to logs in the dashboard|\n|- |EPSAGON_STEPS_ID |String|- |The Epsagon step id from the ECS step functions state input |\n|- |EPSAGON_STEPS_NUM |String|`0` |The step number of the ECS step functions state |\n|- |EPSAGON_LAMBDA_TIMEOUT_THRESHOLD_MS |Integer|`200` |The threshold in millieseconds to send the trace before a Lambda timeout occurs |\n\n\n## Getting Help\n\nIf you have any issue around using the library or the product, please don't hesitate to:\n\n* Use the [documentation](https://docs.epsagon.com).\n* Use the help widget inside the product.\n* Open an issue in GitHub.\n\n\n## Opening Issues\n\nIf you encounter a bug with the Epsagon library for Node.js, we want to hear about it.\n\nWhen opening a new issue, please provide as much information about the environment:\n* Library version, Node.js runtime version, dependencies, etc.\n* Snippet of the usage.\n* A reproducible example can really help.\n\nThe GitHub issues are intended for bug reports and feature requests.\nFor help and questions about Epsagon, use the help widget inside the product.\n\n## License\n\nProvided under the MIT license. See LICENSE for details.\n\nCopyright 2020, Epsagon\n","readmeFilename":"README.md","gitHead":"145f483b2dd612883b053baef0f931e2be7e71dd","_id":"epsagon@1.88.1-beta.0","_nodeVersion":"12.18.2","_npmVersion":"6.14.5","dist":{"integrity":"sha512-vSWBREuAgBedMlAX5Zi14g0mTXdg2YR8O5oqsBhBG4cKj1yJXmQh4nNJ6prCH5wFz5LJ9XLhOI1brLGRLKCfVQ==","shasum":"7c04075c66dcc82abb5e96b53cfce9cf0e30e36b","tarball":"https://registry.npmjs.org/epsagon/-/epsagon-1.88.1-beta.0.tgz","fileCount":5,"unpackedSize":188403,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.13\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJfhqVDCRA9TVsSAnZWagAAiR4P/RVfV1y9Bgo1tLGGbbzv\nEnusF4fGyvvpQQBPrTQzSfSrrXvXVxghnDhIJnTOcZPFxUg1vp7mWFDZ3AwZ\n9pfCXj+Lx5rvbkNvJezHEXwpWtUljA0sxFLXJiYaJF1uaua6tZvZ8ltxvORG\n4APtSzIeYlTNSpqXzhc+2+GDp2CuhJc1KYVCh5tkd4m7DhVyoR8E1Dml3DSd\ndNUAxJvus0MewyM47fpx8xzRHo+cMTW6OjK8l1ltrrXhfmcWCmlERcTeGc/d\nvag8EtzNJGNHvLuwKd9cBFXu1+PCtRVtdV20E7jXUtRPtuTAeCZqqMGP73zh\nNxUSVIJfz9J/0ltEGppZJdWAmaWaMNkCRdHBJ20tAEXrmfDdKHUdPYpTSZcu\n1vFwY883R3dD1uHEtjLY0+18W5M5tgX2gW422EHEKYACfJoVp9IN/tL48D0E\nWAXwhV9nFbAr0XAEHoIfq58v6lQpyeDEQ/67e4b+7h2cH0GgjdQa8HnXQOrL\n+FYOffy4Xf9LL5fhtlnE4hcET5/PjiBKK1VShAt733vrCBJ89WAh7+rrLkF3\nqIkqEX6J3Y150Jml9IHI0QK7QQen54u/6IsdcrlCluk1I3Jx/8bSEaX4rnzK\njPgY2lkhnsLUaZXN4d9Sz6otyhNBB1HXiCBKWpY+4mMpk3/flS/SK6HxbbM1\nwLb+\r\n=haeF\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIC8oDcbedHDC78B9dt3P4mNqjvImXOFEUXytovghDIkvAiEA2m1Tig1ay9jDedCLYLxufkbcLiGnMF+Y+vHQ8D8I4UI="}]},"maintainers":[{"name":"epsagon","email":"dev@epsagon.com"}],"_npmUser":{"name":"epsagon","email":"dev@epsagon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/epsagon_1.88.1-beta.0_1602659650303_0.45446781204734976"},"_hasShrinkwrap":false},"1.88.1-beta.1":{"name":"epsagon","version":"1.88.1-beta.1","description":"Epsagon Instrumentation for Node.js","keywords":["serverless","epsagon","tracing","distributed-tracing","lambda","aws-lambda","debugging","monitoring"],"author":{"name":"Epsagon Team","email":"support@epsagon.com"},"license":"MIT","scripts":{"pretest":"./scripts/build_peg.sh","test":"./scripts/run_tests.sh","lint:js":"eslint --max-warnings=0 ./src/ ./examples/ ./test/unit_tests ./index.js -f table --ext .js --ext .jsx","lint:js:fix":"eslint --max-warnings=0 ./src/ ./examples/ ./test/unit_tests ./index.js -f table --ext .js --ext .jsx --fix","lint":"npm run lint:js","build:dev":"./scripts/build_peg.sh && rollup -c","build":"./scripts/build_peg.sh && NODE_ENV=production rollup -c","clean":"rm -r dist/","prepublishOnly":"npm run build","semantic-release":"semantic-release"},"bugs":{"url":"https://github.com/epsagon/epsagon-node/issues"},"homepage":"https://github.com/epsagon/epsagon-node#readme","repository":{"type":"git","url":"git+https://github.com/epsagon/epsagon-node.git"},"main":"dist/bundle.js","husky":{"hooks":{"commit-msg":"commitlint -E HUSKY_GIT_PARAMS"}},"devDependencies":{"@babel/runtime":"^7.4.5","@commitlint/cli":"^9.1.2","@commitlint/config-angular":"^7.1.2","@commitlint/config-conventional":"^7.1.2","aws-sdk":"^2.197.0","chai":"^4.1.2","chai-as-promised":"^7.1.1","dotenv":"^8.2.0","eslint":"^4.18.0","eslint-config-airbnb":"^17.1.0","eslint-plugin-chai-friendly":"^0.4.1","eslint-plugin-import":"^2.14.0","eslint-plugin-json":"^1.2.1","eslint-plugin-jsx-a11y":"^6.1.1","eslint-plugin-mocha":"^4.11.0","eslint-plugin-react":"^7.11.0","husky":"^1.1.0","ldap-server-mock":"^3.0.0","ldapjs":"^2.1.0","lolex":"^3.0.0","mocha":"^5.0.4","mongodb":"^3.1.13","mysql":"^2.16.0","mysql2":"^1.6.4","pegjs":"^0.10.0","pg":"^7.6.0","pg-pool":"^2.0.3","proxyquire":"^2.0.1","redis":"^2.8.0","request":"^2.88.2","request-promise-native":"^1.0.7","rollup":"^0.66.6","rollup-plugin-commonjs":"^9.1.8","rollup-plugin-copy":"^3.1.0","rollup-plugin-eslint":"^5.0.0","rollup-plugin-json":"^3.1.0","rollup-plugin-terser":"^7.0.1","semantic-release":"^15.13.30","sinon":"^4.3.0","uglify-es":"^3.3.9"},"dependencies":{"axios":"^0.19.0","google-protobuf":"^3.5.0","json.sortify":"^2.2.2","md5":"^2.2.1","require-in-the-middle":"^5.0.3","shimmer":"^1.2.1","uuid-parse":"^1.1.0","uuid4":"^1.0.0"},"readme":"
\n\n[](https://travis-ci.com/epsagon/epsagon-node)\n[](https://badge.fury.io/js/epsagon)\n[](https://github.com/semantic-release/semantic-release)\n\n# Epsagon Tracing for Node.js\nThis package provides tracing to Node.js applications for the collection of distributed tracing and performance metrics in [Epsagon](https://app.epsagon.com/?utm_source=github).\n\n## Contents\n\n- [Installation](#installation)\n- [Usage](#usage)\n - [Auto-tracing](#auto-tracing)\n - [Calling the SDK](#calling-the-sdk)\n - [Tagging Traces](#tagging-traces)\n - [Custom Errors](#custom-errors)\n - [Filter Sensitive Data](#filter-sensitive-data)\n - [Ignore Endpoints](#ignore-endpoints)\n - [Trace URL](#trace-url)\n- [Frameworks](#frameworks)\n- [Integrations](#integrations)\n- [Configuration](#configuration)\n- [Getting Help](#getting-help)\n- [Opening Issues](#opening-issues)\n- [License](#license)\n\n## Installation\n\nTo install Epsagon, simply run:\n```sh\nnpm install epsagon\n```\n\n## Usage\n\n### Auto-tracing\n\nThe simplest way to get started in some frameworks is to install `epsagon-frameworks`:\n```sh\nnpm install epsagon-frameworks\n```\n\n[`epsagon-frameworks`](https://github.com/epsagon/epsagon-node-frameworks) extends the base `epsagon` support to more frameworks.\n\nAnd run your node command:\n```sh\nexport EPSAGON_TOKEN=\nexport EPSAGON_APP_NAME=\nexport NODE_OPTIONS='-r epsagon-frameworks'\n\n```\n\nFor example:\n```sh\nexport EPSAGON_TOKEN=\nexport EPSAGON_APP_NAME=express-prod\nexport NODE_OPTIONS='-r epsagon-frameworks'\nnode app.js\n```\n\nWhen using inside a `Dockerfile`, you can use `ENV` instead of `export`.\n\nYou can see the list of auto-tracing [supported frameworks](#frameworks)\n\n### Calling the SDK\n\nAnother simple alternative is to copy the snippet into your code:\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTo run on your framework please refer to [supported frameworks](#frameworks)\n\n\n### Tagging Traces\n\nYou can add custom tags to your traces, for easier filtering and aggregations.\n\nAdd the following call inside your code:\n```javascript\nepsagon.label('key', 'value');\nepsagon.label('userId', userId);\n```\n\nYou can also use it to ship custom metrics:\n```javascript\nepsagon.label('key', 'metric')\nepsagon.label('itemsInCart', itemsInCart)\n```\n\nYou can also use it iniside init function:\n```javascript\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n labels: [['key', 'value'], ['userId', userId]],\n});\n```\n\nValid types are `string`, `boolean` and `number`.\n\nIn some [frameworks](#frameworks) tagging can be done in different ways.\n\n### Custom Errors\n\nYou can set a trace as an error (although handled correctly) to get an alert or just follow it on the dashboard.\n\nAdd the following call inside your code:\n```javascript\ntry {\n // something bad happens\n} catch (err) {\n epsagon.setError(err);\n}\n\n// Or manually specify Error object\nepsagon.setError(Error('My custom error'));\n```\n\nIn some [frameworks](#frameworks) custom errors can be declared in different ways.\n\n### Filter Sensitive Data\n\nYou can pass a list of sensitive properties and hostnames and they will be filtered out from the traces:\n\n```javascript\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n ignoredKeys: ['password', /.*_token$/],\n urlPatternsToIgnore: ['example.com', 'auth.com'],\n});\n```\n\nThe `ignoredKeys` property can contain strings (will perform a loose match, so that `First Name` also matches `first_name`), regular expressions, and predicate functions.\nAlso, you can set `urlPatternsToIgnore` to ignore HTTP calls to specific domains.\n\n\n### Ignore Endpoints\n\nYou can ignore certain incoming requests by specifying endpoints:\n```javascript\nepsagon.ignoreEndpoints(['/healthcheck'])\n```\n\n### Trace URL\n\nYou can get the Epsagon dashboard URL for the current trace, using the following:\n```node\n# Inside some endpoint or function\nconsole.log('Epsagon trace URL:', epsagon.getTraceUrl())\n```\n\nThis can be useful to have an easy access the trace from different platforms.\n\n\n## Frameworks\n\nThe following frameworks are supported by Epsagon.\nSome require installing also [`epsagon-frameworks`](https://github.com/epsagon/epsagon-node-frameworks)\n\n|Framework |Supported Version |Epsagon Library |Auto-tracing Supported |\n|----------------------------------------|---------------------------|---------------------------------------------------|-----------------------------------------------------|\n|[AWS Lambda](#aws-lambda) |All |`epsagon` |
|\n\n\n### AWS Lambda\n\nTracing Lambda functions can be done in three methods:\n1. Auto-tracing through the Epsagon dashboard.\n2. Using the [`serverless-plugin-epsagon`](https://github.com/epsagon/serverless-plugin-epsagon) if you're using The Serverless Framework.\n3. Calling the SDK.\n\n**Make sure to choose just one of the methods**\n\nCalling the SDK is simple:\n\n```javascript\nconst epsagon = require('epsagon');\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n\n// Wrap your entry point\nmodule.exports.handler = epsagon.lambdaWrapper((event, context, callback) => {\n // Your code is here\n});\n\n// Async functions example\nmodule.exports.handler = epsagon.lambdaWrapper(async (event) => {\n // Your code is here\n});\n```\n\n### Step Functions\n\nTracing Step Functions is similar to regular Lambda functions, but the wrapper changes from `lambdaWrapper` to `stepLambdaWrapper`:\n\n```javascript\nconst epsagon = require('epsagon');\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n\n// Wrap your entry point\nmodule.exports.handler = epsagon.stepLambdaWrapper((event, context, callback) => {\n // Your code is here\n});\n\n// Async functions example\nmodule.exports.handler = epsagon.stepLambdaWrapper(async (event) => {\n // Your code is here\n});\n```\nECS Step - You should pass Epsagon step_dict id from ECS state input into ```EPSAGON_STEPS_ID``` environment variables of the container, ```EPSAGON_STEPS_NUM``` is the step number of the ECS (default: 0). check the [configuration](https://github.com/epsagon/epsagon-node/#configuration) section.\n\n### OpenWhisk Action\n\nYou should pass the Epsagon token to your action as a default parameter, so that you don't have to expose important credentials in your code.\nThe name of the parameter can be configured using `token_param`, in this example we use `epsagon-token`:\n\n```javascript\nconst epsagon = require('epsagon');\n\nfunction main(params) {\n // Your code is here\n}\n\nmodule.exports.main = epsagon.openWhiskWrapper(\n main,\n {\n token_param: 'epsagon-token', // name of the action parameter to take the token from\n appName: 'app-name-stage',\n metadataOnly: false\n }\n);\n```\n\n### AWS Batch\n\nTracing batch jobs running in AWS Batch can be done by wrapping the main handler/entrypoint of the code:\n\n```javascript\nconst epsagon = require('epsagon');\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n\n\nfunction process(params) {\n // Your code is here\n}\n\nconst wrappedProcess = epsagon.wrapBatchJob(process);\n```\n\n### Express\n\nTracing Express application can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the application is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\napp.get('/', (req, res) => {\n req.epsagon.label('key', 'value');\n req.epsagon.setError(Error('My custom error'));\n}\n```\n\n### Hapi\n\nTracing Hapi application can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the application is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\nserver.route({\n method: 'GET',\n path:'/',\n handler: (request, h) => {\n request.epsagon.label('key', 'value');\n request.epsagon.setError(Error('My custom error'));\n }\n});\n```\n\n### Koa\n\nTracing Koa application can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the application is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\napp.use(async ctx => {\n ctx.epsagon.label('key', 'value');\n ctx.epsagon.setError(Error('My custom error'));\n});\n```\n\n### WS (Websocket)\n\nTracing `ws` consumers can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the consumer is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\nsocket.on('message', (message) => {\n message.epsagon.label('key', 'value');\n message.epsagon.setError(Error('My custom error'));\n}) \n```\n\n### KafkaJS\n\nTracing `kafkajs` consumers can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the consumer is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\nawait consumer.run({\n eachMessage: async ({ topic, partition, message }) => {\n message.epsagon.label('key', 'value');\n message.epsagon.setError(Error('My custom error'));\n },\n})\n```\n\n### kafka-node\n\nTracing `kafka0node` consumers can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the consumer is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\nconsumer.on('message', function (message) {\n message.epsagon.label('key', 'value');\n message.epsagon.setError(Error('My custom error'));\n})\n```\n\n### PubSub\n\nTracing `@google-cloud/pubsub` consumers can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the consumer is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\nawait consumer.run({\n eachMessage: async ({ topic, partition, message }) => {\n message.epsagon.label('key', 'value');\n message.epsagon.setError(Error('My custom error'));\n },\n})\n```\n\n### SQS Consumer\n\nTracing [`sqs-consumer`](https://github.com/bbc/sqs-consumer) consumers can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the consumer is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\nconst messageHandler = message => {\n message.epsagon.label('key', 'value');\n message.epsagon.setError(Error('My custom error'));\n};\n```\n\nOr in batch message handler:\n```javascript\nconst batchMessageHandler = messages => {\n messages[0].epsagon.label('key', 'value');\n messages[0].epsagon.setError(Error('My custom error'));\n};\n```\n\n\n### amqplib\n\nTracing amqplib consumers can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the consumer is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\nch.consume(q, function cons(msg) {\n if (msg !== null) {\n msg.epsagon.label('key', 'value');\n msg.epsagon.setError(Error('My custom error'));\n ch.ack(msg);\n }\n});\n```\n\n### bunnybus\n\nTracing bunnybus consumers can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the consumer is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\n// epsagon is added as an argument to the handler\nhandler: async ({message, metaData, ack, rej, requeue, epsagon}) => {\n epsagon.label('key', 'value');\n epsagon.setError(Error('My custom error'));\n await ack();\n}\n```\n\n### NATS\n\nTracing `nats` consumers can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the consumer is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\n\n### Generic\n\nFor any tracing, you can simply use the generic Epsagon wrapper using the following example:\n\n```javascript\nconst epsagon = require('epsagon');\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n\n\nfunction main(params) {\n // Your code is here\n}\n\nconst wrappedMain = epsagon.nodeWrapper(main);\n```\n\n## Integrations\n\nEpsagon provides out-of-the-box instrumentation (tracing) for many popular frameworks and libraries.\n\n|Library |Supported Version |\n|--------------------|---------------------------|\n|http |Fully supported |\n|https |Fully supported |\n|http2 |Fully supported |\n|dns |Fully supported |\n|aws-sdk |`>=2.2.0` |\n|amazon-dax-client |`>=1.0.2` |\n|@google-cloud |`>=2.0.0` |\n|@google-cloud/pubsub|`>=1.1.0` |\n|mysql |`>=2` |\n|mysql2 |`>=1` |\n|pg |`>=4` |\n|mongodb |`>=2.2.12` |\n|kafkajs |`>=1.2.0` |\n|kafka-node |`>=3.0.0` |\n|amqplib |`>=0.5.0` |\n|amqp |`>=0.2.0` |\n|redis |`>=0.12.1` |\n|ioredis |`>=4.0.0` |\n|mqtt |`>=2.13.1` |\n|nats |`>=1.4.0` |\n|openwhisk |`>=3.0.0` |\n|@azure/cosmos |`>=3.7.5` |\n|@azure/storage-blob |`>=12.2.0` |\n|ldapjs |`>=2.1.0` |\n|ws |`>=7.3.1` |\n\n\n\n## Configuration\n\nAdvanced options can be configured as a parameter to the init() method or as environment variables.\n\n|Parameter |Environment Variable |Type |Default |Description |\n|-------------------|---------------------------|-------|-------------|-----------------------------------------------------------------------------------|\n|token |EPSAGON_TOKEN |String |- |Epsagon account token |\n|appName |EPSAGON_APP_NAME |String |`Application`|Application name that will be set for traces |\n|metadataOnly |EPSAGON_METADATA |Boolean|`true` |Whether to send only the metadata (`true`) or also the payloads (`false`) |\n|useSSL |EPSAGON_SSL |Boolean|`true` |Whether to send the traces over HTTPS SSL or not |\n|traceCollectorURL |EPSAGON_COLLECTOR_URL |String |- |The address of the trace collector to send trace to |\n|isEpsagonDisabled |DISABLE_EPSAGON |Boolean|`false` |A flag to completely disable Epsagon (can be used for tests or locally) |\n|ignoredKeys |EPSAGON_IGNORED_KEYS |Array |- |Array of keys names (can be string or regex) to be removed from the trace |\n|urlPatternsToIgnore|EPSAGON_URLS_TO_IGNORE |Array |`[]` |Array of URL patterns to ignore the calls |\n|sendTimeout |EPSAGON_SEND_TIMEOUT_SEC |Float |`1.0` |The timeout duration in seconds to send the traces to the trace collector |\n|decodeHTTP |EPSAGON_DECODE_HTTP |Boolean|`true` |Whether to decode and decompress HTTP responses into the payload |\n|httpErrorStatusCode|EPSAGON_HTTP_ERR_CODE |Integer|`400` |The minimum number of an HTTP response status code to treat as an error |\n|- |EPSAGON_PROPAGATE_LAMBDA_ID|Boolean|`False` |Insert Lambda request ID into the response payload |\n|- |DISABLE_EPSAGON_PATCH |Boolean|`false` |Disable the library patching (instrumentation) |\n|- |EPSAGON_DEBUG |Boolean|`false` |Enable debug prints for troubleshooting |\n|- |EPSAGON_PROPAGATE_NATS_ID |Boolean|`false` |Whether to propagate a correlation ID in NATS.io calls for distributed tracing |\n|- |EPSAGON_ADD_NODE_PATH |String |- |List of folders to looks for node_modules when patching libraries. Separated by `:`|\n|- |EPSAGON_AUTO_ADD_NODE_PATHS|Boolean |`false` |Auto add node_modules sub folders to look when patching libraries. |\n|- |EPSAGON_DNS_INSTRUMENTATION|Boolean|`false` |Whether to capture `dns` calls into the trace |\n|- |EPSAGON_LOGGING_TRACING_ENABLED|Boolean|`true` |whether to add an Epsagon ID to the logs in order to correlate traces to logs in the dashboard|\n|- |EPSAGON_STEPS_ID |String|- |The Epsagon step id from the ECS step functions state input |\n|- |EPSAGON_STEPS_NUM |String|`0` |The step number of the ECS step functions state |\n|- |EPSAGON_LAMBDA_TIMEOUT_THRESHOLD_MS |Integer|`200` |The threshold in millieseconds to send the trace before a Lambda timeout occurs |\n\n\n## Getting Help\n\nIf you have any issue around using the library or the product, please don't hesitate to:\n\n* Use the [documentation](https://docs.epsagon.com).\n* Use the help widget inside the product.\n* Open an issue in GitHub.\n\n\n## Opening Issues\n\nIf you encounter a bug with the Epsagon library for Node.js, we want to hear about it.\n\nWhen opening a new issue, please provide as much information about the environment:\n* Library version, Node.js runtime version, dependencies, etc.\n* Snippet of the usage.\n* A reproducible example can really help.\n\nThe GitHub issues are intended for bug reports and feature requests.\nFor help and questions about Epsagon, use the help widget inside the product.\n\n## License\n\nProvided under the MIT license. See LICENSE for details.\n\nCopyright 2020, Epsagon\n","readmeFilename":"README.md","gitHead":"145f483b2dd612883b053baef0f931e2be7e71dd","_id":"epsagon@1.88.1-beta.1","_nodeVersion":"12.18.2","_npmVersion":"6.14.5","dist":{"integrity":"sha512-ov3OrFJhYSiXoeNFqePniGav3UAmoAF/x9qCpO6IEc+lpoXxsw/zrtt/vr1hTCrQD3xaAumfSULhH5MokMNWYA==","shasum":"2b1aa0867eb36b91619932161c3ffd60b149814e","tarball":"https://registry.npmjs.org/epsagon/-/epsagon-1.88.1-beta.1.tgz","fileCount":5,"unpackedSize":188094,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.13\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJfhu9JCRA9TVsSAnZWagAAQMUP/3EfFxOG9fp2GzuTlNGg\nEKOXfmbciTDeKa2tzR5hc3DnCh3eo8SbGUdwmH+/qazXHXApWsWuFVst7eWl\nro3QLrfm7d4n/f4oFdNhNbTRE2bDToBym6UreXw4FYSHYu39D5ZwAsyr3Qdg\njaoBmOb7pcYBeeQUDEZwjA6oEgEmJ5j25mNSXJNYUYIeIMSEgQALbpDvMYGG\nMy/nTw8xoXT46vz0i+lTSEeUrOnjBynaaMseOFon7dJFakzFbIacTxVE2o4D\nAvPg7ZTKjrLl0kkX2nE/p78wduWlSNIrGj5uIEVPJ0QC2fX5p+kUT/5ifgo3\na5TaISnIiYou1p12TtcsyxqMU15EGjZQVt1x5zTJ9lgSsuVGKgGvQ/3joaSF\nLDu+bJ7AD5Ze8BdapuwdoKRdEbDhsNqbiL7yN1sP/BHGV24numaAQJb3Hlnt\n8F2B3vymPlsGMIT2mYn/WbghYdBz9Sf7JNj+1d7JuWBPGzMrFYoq064jjaJF\nj1B63r7IgEHVutGqRhiwaowurQcqoKvdpIXSTvXkHPfSLwI1aNPRq85CZe62\nXlQpdupbknqM90+jWJEI3kL8mOxILJ8V2ysd+OFr+a9U8IuV94Kr6vgpDru5\nXu1meI4N9aFTqtIOlXxI7q1D9NkoAbJvAJ92Iqh0jeYqugCTUga68PRdQU4G\nitvr\r\n=5cbj\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQC6fjWOioDgztOtFITFWBClb8ePwN2l6uwebPnsuG+UxwIhAPwM8ABpPmyKO4yX74WX1AnVj3/kI0gP9a5cX/YOZuS1"}]},"maintainers":[{"name":"epsagon","email":"dev@epsagon.com"}],"_npmUser":{"name":"epsagon","email":"dev@epsagon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/epsagon_1.88.1-beta.1_1602678600769_0.40169191996804177"},"_hasShrinkwrap":false},"1.88.1-beta.2":{"name":"epsagon","version":"1.88.1-beta.2","description":"Epsagon Instrumentation for Node.js","keywords":["serverless","epsagon","tracing","distributed-tracing","lambda","aws-lambda","debugging","monitoring"],"author":{"name":"Epsagon Team","email":"support@epsagon.com"},"license":"MIT","scripts":{"pretest":"./scripts/build_peg.sh","test":"./scripts/run_tests.sh","lint:js":"eslint --max-warnings=0 ./src/ ./examples/ ./test/unit_tests ./index.js -f table --ext .js --ext .jsx","lint:js:fix":"eslint --max-warnings=0 ./src/ ./examples/ ./test/unit_tests ./index.js -f table --ext .js --ext .jsx --fix","lint":"npm run lint:js","build:dev":"./scripts/build_peg.sh && rollup -c","build":"./scripts/build_peg.sh && NODE_ENV=production rollup -c","clean":"rm -r dist/","prepublishOnly":"npm run build","semantic-release":"semantic-release"},"bugs":{"url":"https://github.com/epsagon/epsagon-node/issues"},"homepage":"https://github.com/epsagon/epsagon-node#readme","repository":{"type":"git","url":"git+https://github.com/epsagon/epsagon-node.git"},"main":"dist/bundle.js","husky":{"hooks":{"commit-msg":"commitlint -E HUSKY_GIT_PARAMS"}},"devDependencies":{"@babel/runtime":"^7.4.5","@commitlint/cli":"^9.1.2","@commitlint/config-angular":"^7.1.2","@commitlint/config-conventional":"^7.1.2","aws-sdk":"^2.197.0","chai":"^4.1.2","chai-as-promised":"^7.1.1","dotenv":"^8.2.0","eslint":"^4.18.0","eslint-config-airbnb":"^17.1.0","eslint-plugin-chai-friendly":"^0.4.1","eslint-plugin-import":"^2.14.0","eslint-plugin-json":"^1.2.1","eslint-plugin-jsx-a11y":"^6.1.1","eslint-plugin-mocha":"^4.11.0","eslint-plugin-react":"^7.11.0","husky":"^1.1.0","ldap-server-mock":"^3.0.0","ldapjs":"^2.1.0","lolex":"^3.0.0","mocha":"^5.0.4","mongodb":"^3.1.13","mysql":"^2.16.0","mysql2":"^1.6.4","pegjs":"^0.10.0","pg":"^7.6.0","pg-pool":"^2.0.3","proxyquire":"^2.0.1","redis":"^2.8.0","request":"^2.88.2","request-promise-native":"^1.0.7","rollup":"^0.66.6","rollup-plugin-commonjs":"^9.1.8","rollup-plugin-copy":"^3.1.0","rollup-plugin-eslint":"^5.0.0","rollup-plugin-json":"^3.1.0","rollup-plugin-terser":"^7.0.1","semantic-release":"^15.13.30","sinon":"^4.3.0","uglify-es":"^3.3.9"},"dependencies":{"axios":"^0.19.0","google-protobuf":"^3.5.0","json.sortify":"^2.2.2","md5":"^2.2.1","require-in-the-middle":"^5.0.3","shimmer":"^1.2.1","uuid-parse":"^1.1.0","uuid4":"^1.0.0"},"readme":"
\n\n[](https://travis-ci.com/epsagon/epsagon-node)\n[](https://badge.fury.io/js/epsagon)\n[](https://github.com/semantic-release/semantic-release)\n\n# Epsagon Tracing for Node.js\nThis package provides tracing to Node.js applications for the collection of distributed tracing and performance metrics in [Epsagon](https://app.epsagon.com/?utm_source=github).\n\n## Contents\n\n- [Installation](#installation)\n- [Usage](#usage)\n - [Auto-tracing](#auto-tracing)\n - [Calling the SDK](#calling-the-sdk)\n - [Tagging Traces](#tagging-traces)\n - [Custom Errors](#custom-errors)\n - [Filter Sensitive Data](#filter-sensitive-data)\n - [Ignore Endpoints](#ignore-endpoints)\n - [Trace URL](#trace-url)\n- [Frameworks](#frameworks)\n- [Integrations](#integrations)\n- [Configuration](#configuration)\n- [Getting Help](#getting-help)\n- [Opening Issues](#opening-issues)\n- [License](#license)\n\n## Installation\n\nTo install Epsagon, simply run:\n```sh\nnpm install epsagon\n```\n\n## Usage\n\n### Auto-tracing\n\nThe simplest way to get started in some frameworks is to install `epsagon-frameworks`:\n```sh\nnpm install epsagon-frameworks\n```\n\n[`epsagon-frameworks`](https://github.com/epsagon/epsagon-node-frameworks) extends the base `epsagon` support to more frameworks.\n\nAnd run your node command:\n```sh\nexport EPSAGON_TOKEN=\nexport EPSAGON_APP_NAME=\nexport NODE_OPTIONS='-r epsagon-frameworks'\n\n```\n\nFor example:\n```sh\nexport EPSAGON_TOKEN=\nexport EPSAGON_APP_NAME=express-prod\nexport NODE_OPTIONS='-r epsagon-frameworks'\nnode app.js\n```\n\nWhen using inside a `Dockerfile`, you can use `ENV` instead of `export`.\n\nYou can see the list of auto-tracing [supported frameworks](#frameworks)\n\n### Calling the SDK\n\nAnother simple alternative is to copy the snippet into your code:\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTo run on your framework please refer to [supported frameworks](#frameworks)\n\n\n### Tagging Traces\n\nYou can add custom tags to your traces, for easier filtering and aggregations.\n\nAdd the following call inside your code:\n```javascript\nepsagon.label('key', 'value');\nepsagon.label('userId', userId);\n```\n\nYou can also use it to ship custom metrics:\n```javascript\nepsagon.label('key', 'metric')\nepsagon.label('itemsInCart', itemsInCart)\n```\n\nYou can also use it iniside init function:\n```javascript\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n labels: [['key', 'value'], ['userId', userId]],\n});\n```\n\nValid types are `string`, `boolean` and `number`.\n\nIn some [frameworks](#frameworks) tagging can be done in different ways.\n\n### Custom Errors\n\nYou can set a trace as an error (although handled correctly) to get an alert or just follow it on the dashboard.\n\nAdd the following call inside your code:\n```javascript\ntry {\n // something bad happens\n} catch (err) {\n epsagon.setError(err);\n}\n\n// Or manually specify Error object\nepsagon.setError(Error('My custom error'));\n```\n\nIn some [frameworks](#frameworks) custom errors can be declared in different ways.\n\n### Filter Sensitive Data\n\nYou can pass a list of sensitive properties and hostnames and they will be filtered out from the traces:\n\n```javascript\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n ignoredKeys: ['password', /.*_token$/],\n urlPatternsToIgnore: ['example.com', 'auth.com'],\n});\n```\n\nThe `ignoredKeys` property can contain strings (will perform a loose match, so that `First Name` also matches `first_name`), regular expressions, and predicate functions.\nAlso, you can set `urlPatternsToIgnore` to ignore HTTP calls to specific domains.\n\n\n### Ignore Endpoints\n\nYou can ignore certain incoming requests by specifying endpoints:\n```javascript\nepsagon.ignoreEndpoints(['/healthcheck'])\n```\n\n### Trace URL\n\nYou can get the Epsagon dashboard URL for the current trace, using the following:\n```node\n# Inside some endpoint or function\nconsole.log('Epsagon trace URL:', epsagon.getTraceUrl())\n```\n\nThis can be useful to have an easy access the trace from different platforms.\n\n\n## Frameworks\n\nThe following frameworks are supported by Epsagon.\nSome require installing also [`epsagon-frameworks`](https://github.com/epsagon/epsagon-node-frameworks)\n\n|Framework |Supported Version |Epsagon Library |Auto-tracing Supported |\n|----------------------------------------|---------------------------|---------------------------------------------------|-----------------------------------------------------|\n|[AWS Lambda](#aws-lambda) |All |`epsagon` |
|\n\n\n### AWS Lambda\n\nTracing Lambda functions can be done in three methods:\n1. Auto-tracing through the Epsagon dashboard.\n2. Using the [`serverless-plugin-epsagon`](https://github.com/epsagon/serverless-plugin-epsagon) if you're using The Serverless Framework.\n3. Calling the SDK.\n\n**Make sure to choose just one of the methods**\n\nCalling the SDK is simple:\n\n```javascript\nconst epsagon = require('epsagon');\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n\n// Wrap your entry point\nmodule.exports.handler = epsagon.lambdaWrapper((event, context, callback) => {\n // Your code is here\n});\n\n// Async functions example\nmodule.exports.handler = epsagon.lambdaWrapper(async (event) => {\n // Your code is here\n});\n```\n\n### Step Functions\n\nTracing Step Functions is similar to regular Lambda functions, but the wrapper changes from `lambdaWrapper` to `stepLambdaWrapper`:\n\n```javascript\nconst epsagon = require('epsagon');\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n\n// Wrap your entry point\nmodule.exports.handler = epsagon.stepLambdaWrapper((event, context, callback) => {\n // Your code is here\n});\n\n// Async functions example\nmodule.exports.handler = epsagon.stepLambdaWrapper(async (event) => {\n // Your code is here\n});\n```\nECS Step - You should pass Epsagon step_dict id from ECS state input into ```EPSAGON_STEPS_ID``` environment variables of the container, ```EPSAGON_STEPS_NUM``` is the step number of the ECS (default: 0). check the [configuration](https://github.com/epsagon/epsagon-node/#configuration) section.\n\n### OpenWhisk Action\n\nYou should pass the Epsagon token to your action as a default parameter, so that you don't have to expose important credentials in your code.\nThe name of the parameter can be configured using `token_param`, in this example we use `epsagon-token`:\n\n```javascript\nconst epsagon = require('epsagon');\n\nfunction main(params) {\n // Your code is here\n}\n\nmodule.exports.main = epsagon.openWhiskWrapper(\n main,\n {\n token_param: 'epsagon-token', // name of the action parameter to take the token from\n appName: 'app-name-stage',\n metadataOnly: false\n }\n);\n```\n\n### AWS Batch\n\nTracing batch jobs running in AWS Batch can be done by wrapping the main handler/entrypoint of the code:\n\n```javascript\nconst epsagon = require('epsagon');\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n\n\nfunction process(params) {\n // Your code is here\n}\n\nconst wrappedProcess = epsagon.wrapBatchJob(process);\n```\n\n### Express\n\nTracing Express application can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the application is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\napp.get('/', (req, res) => {\n req.epsagon.label('key', 'value');\n req.epsagon.setError(Error('My custom error'));\n}\n```\n\n### Hapi\n\nTracing Hapi application can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the application is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\nserver.route({\n method: 'GET',\n path:'/',\n handler: (request, h) => {\n request.epsagon.label('key', 'value');\n request.epsagon.setError(Error('My custom error'));\n }\n});\n```\n\n### Koa\n\nTracing Koa application can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the application is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\napp.use(async ctx => {\n ctx.epsagon.label('key', 'value');\n ctx.epsagon.setError(Error('My custom error'));\n});\n```\n\n### WS (Websocket)\n\nTracing `ws` consumers can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the consumer is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\nsocket.on('message', (message) => {\n message.epsagon.label('key', 'value');\n message.epsagon.setError(Error('My custom error'));\n}) \n```\n\n### KafkaJS\n\nTracing `kafkajs` consumers can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the consumer is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\nawait consumer.run({\n eachMessage: async ({ topic, partition, message }) => {\n message.epsagon.label('key', 'value');\n message.epsagon.setError(Error('My custom error'));\n },\n})\n```\n\n### kafka-node\n\nTracing `kafka0node` consumers can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the consumer is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\nconsumer.on('message', function (message) {\n message.epsagon.label('key', 'value');\n message.epsagon.setError(Error('My custom error'));\n})\n```\n\n### PubSub\n\nTracing `@google-cloud/pubsub` consumers can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the consumer is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\nawait consumer.run({\n eachMessage: async ({ topic, partition, message }) => {\n message.epsagon.label('key', 'value');\n message.epsagon.setError(Error('My custom error'));\n },\n})\n```\n\n### SQS Consumer\n\nTracing [`sqs-consumer`](https://github.com/bbc/sqs-consumer) consumers can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the consumer is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\nconst messageHandler = message => {\n message.epsagon.label('key', 'value');\n message.epsagon.setError(Error('My custom error'));\n};\n```\n\nOr in batch message handler:\n```javascript\nconst batchMessageHandler = messages => {\n messages[0].epsagon.label('key', 'value');\n messages[0].epsagon.setError(Error('My custom error'));\n};\n```\n\n\n### amqplib\n\nTracing amqplib consumers can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the consumer is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\nch.consume(q, function cons(msg) {\n if (msg !== null) {\n msg.epsagon.label('key', 'value');\n msg.epsagon.setError(Error('My custom error'));\n ch.ack(msg);\n }\n});\n```\n\n### bunnybus\n\nTracing bunnybus consumers can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the consumer is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\n// epsagon is added as an argument to the handler\nhandler: async ({message, metaData, ack, rej, requeue, epsagon}) => {\n epsagon.label('key', 'value');\n epsagon.setError(Error('My custom error'));\n await ack();\n}\n```\n\n### NATS\n\nTracing `nats` consumers can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the consumer is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\n\n### Generic\n\nFor any tracing, you can simply use the generic Epsagon wrapper using the following example:\n\n```javascript\nconst epsagon = require('epsagon');\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n\n\nfunction main(params) {\n // Your code is here\n}\n\nconst wrappedMain = epsagon.nodeWrapper(main);\n```\n\n## Integrations\n\nEpsagon provides out-of-the-box instrumentation (tracing) for many popular frameworks and libraries.\n\n|Library |Supported Version |\n|--------------------|---------------------------|\n|http |Fully supported |\n|https |Fully supported |\n|http2 |Fully supported |\n|dns |Fully supported |\n|aws-sdk |`>=2.2.0` |\n|amazon-dax-client |`>=1.0.2` |\n|@google-cloud |`>=2.0.0` |\n|@google-cloud/pubsub|`>=1.1.0` |\n|mysql |`>=2` |\n|mysql2 |`>=1` |\n|pg |`>=4` |\n|mongodb |`>=2.2.12` |\n|kafkajs |`>=1.2.0` |\n|kafka-node |`>=3.0.0` |\n|amqplib |`>=0.5.0` |\n|amqp |`>=0.2.0` |\n|redis |`>=0.12.1` |\n|ioredis |`>=4.0.0` |\n|mqtt |`>=2.13.1` |\n|nats |`>=1.4.0` |\n|openwhisk |`>=3.0.0` |\n|@azure/cosmos |`>=3.7.5` |\n|@azure/storage-blob |`>=12.2.0` |\n|ldapjs |`>=2.1.0` |\n|ws |`>=7.3.1` |\n\n\n\n## Configuration\n\nAdvanced options can be configured as a parameter to the init() method or as environment variables.\n\n|Parameter |Environment Variable |Type |Default |Description |\n|-------------------|---------------------------|-------|-------------|-----------------------------------------------------------------------------------|\n|token |EPSAGON_TOKEN |String |- |Epsagon account token |\n|appName |EPSAGON_APP_NAME |String |`Application`|Application name that will be set for traces |\n|metadataOnly |EPSAGON_METADATA |Boolean|`true` |Whether to send only the metadata (`true`) or also the payloads (`false`) |\n|useSSL |EPSAGON_SSL |Boolean|`true` |Whether to send the traces over HTTPS SSL or not |\n|traceCollectorURL |EPSAGON_COLLECTOR_URL |String |- |The address of the trace collector to send trace to |\n|isEpsagonDisabled |DISABLE_EPSAGON |Boolean|`false` |A flag to completely disable Epsagon (can be used for tests or locally) |\n|ignoredKeys |EPSAGON_IGNORED_KEYS |Array |- |Array of keys names (can be string or regex) to be removed from the trace |\n|urlPatternsToIgnore|EPSAGON_URLS_TO_IGNORE |Array |`[]` |Array of URL patterns to ignore the calls |\n|sendTimeout |EPSAGON_SEND_TIMEOUT_SEC |Float |`1.0` |The timeout duration in seconds to send the traces to the trace collector |\n|decodeHTTP |EPSAGON_DECODE_HTTP |Boolean|`true` |Whether to decode and decompress HTTP responses into the payload |\n|httpErrorStatusCode|EPSAGON_HTTP_ERR_CODE |Integer|`400` |The minimum number of an HTTP response status code to treat as an error |\n|- |EPSAGON_PROPAGATE_LAMBDA_ID|Boolean|`False` |Insert Lambda request ID into the response payload |\n|- |DISABLE_EPSAGON_PATCH |Boolean|`false` |Disable the library patching (instrumentation) |\n|- |EPSAGON_DEBUG |Boolean|`false` |Enable debug prints for troubleshooting |\n|- |EPSAGON_PROPAGATE_NATS_ID |Boolean|`false` |Whether to propagate a correlation ID in NATS.io calls for distributed tracing |\n|- |EPSAGON_ADD_NODE_PATH |String |- |List of folders to looks for node_modules when patching libraries. Separated by `:`|\n|- |EPSAGON_AUTO_ADD_NODE_PATHS|Boolean |`false` |Auto add node_modules sub folders to look when patching libraries. |\n|- |EPSAGON_DNS_INSTRUMENTATION|Boolean|`false` |Whether to capture `dns` calls into the trace |\n|- |EPSAGON_LOGGING_TRACING_ENABLED|Boolean|`true` |whether to add an Epsagon ID to the logs in order to correlate traces to logs in the dashboard|\n|- |EPSAGON_STEPS_ID |String|- |The Epsagon step id from the ECS step functions state input |\n|- |EPSAGON_STEPS_NUM |String|`0` |The step number of the ECS step functions state |\n|- |EPSAGON_LAMBDA_TIMEOUT_THRESHOLD_MS |Integer|`200` |The threshold in millieseconds to send the trace before a Lambda timeout occurs |\n\n\n## Getting Help\n\nIf you have any issue around using the library or the product, please don't hesitate to:\n\n* Use the [documentation](https://docs.epsagon.com).\n* Use the help widget inside the product.\n* Open an issue in GitHub.\n\n\n## Opening Issues\n\nIf you encounter a bug with the Epsagon library for Node.js, we want to hear about it.\n\nWhen opening a new issue, please provide as much information about the environment:\n* Library version, Node.js runtime version, dependencies, etc.\n* Snippet of the usage.\n* A reproducible example can really help.\n\nThe GitHub issues are intended for bug reports and feature requests.\nFor help and questions about Epsagon, use the help widget inside the product.\n\n## License\n\nProvided under the MIT license. See LICENSE for details.\n\nCopyright 2020, Epsagon\n","readmeFilename":"README.md","gitHead":"145f483b2dd612883b053baef0f931e2be7e71dd","_id":"epsagon@1.88.1-beta.2","_nodeVersion":"12.18.2","_npmVersion":"6.14.5","dist":{"integrity":"sha512-Gm7zTSwRH8fuNUvjgnfDNtg1BDUIUTYu2fZktPdQ+yBw6sDCywvchOaNHZs3UZWYHnbOmDQiQacwU0pEpeHdmw==","shasum":"bc9082c20c54455908189a96739f321576a878f8","tarball":"https://registry.npmjs.org/epsagon/-/epsagon-1.88.1-beta.2.tgz","fileCount":5,"unpackedSize":188132,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.13\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJfhvUbCRA9TVsSAnZWagAApGIP/34hE7LPTrI/FWSIFrqI\n5140ONucQPPpvFHyUHyML27VHn9ynptUoJ2xDyU2Y3dVyTTm1YjRChqs4Hqv\nA9dRF0b3J756nuQFA7C18dym2Fl0N+ZChgFnyNjhGBAiiTpalKS9dDDRcR0D\nA9/WejI0mrQKNLVkvIDUgVM3pC1rkTmwi0JcPl2jrO81a17u9Ot1rJ19ulJH\n8G4v2/HeYjjkGanJKvJcjro0wTx3srRT8BA5jukdzAPNaoHAEEgebfgB7xZA\nZgADaRbHTitAkNXqQmmr8kqk7OZS7UOxvkMPnXRI/FK5Pk/vqGsj4UjKkRSx\nr5JRX+Su9+MjWp+C8eYkU4D2eBb76DfTUvVZxNMZAfo58F1rTT0nRZIFZUHB\nTOa5yYRI9JJUF/AWDDm/W/Cw/mbEEnzC+OWkP+jQpERL3+jhhUpt86Tg1Hdf\nS+4nRX3EOn6Ev/DUHqcE33YxixV6Nr3eC8qgzzQtwSYu0YsuJTWFoy1ATK+H\nw+EMHcsMCI/md8y+qbmEM8lnLB4TlM3lZS7zi7ESMmvakMiAr1M7RopYZrrh\n7zIwIV7rDW/AFbjoXrhJeiLb99JFajSPWLCII2taWK11tWhr8D0/vdrCsqek\nDoCUBSeJw4s/SDXJAka3dkTIJLk4zune1vwRunjvBZHW67rqYj7A1ykWAJwx\nswux\r\n=6MDr\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIFKfmnYhOzQJZ0MU/KaIWTWWEE0eL9vSgZh1sZRqegAzAiBr4MepH7CM387Ntc1zMUvwPUd2Cxy+S6jnkyXSGf9SJQ=="}]},"maintainers":[{"name":"epsagon","email":"dev@epsagon.com"}],"_npmUser":{"name":"epsagon","email":"dev@epsagon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/epsagon_1.88.1-beta.2_1602680091167_0.30597547926571433"},"_hasShrinkwrap":false},"1.88.1-beta.3":{"name":"epsagon","version":"1.88.1-beta.3","description":"Epsagon Instrumentation for Node.js","keywords":["serverless","epsagon","tracing","distributed-tracing","lambda","aws-lambda","debugging","monitoring"],"author":{"name":"Epsagon Team","email":"support@epsagon.com"},"license":"MIT","scripts":{"pretest":"./scripts/build_peg.sh","test":"./scripts/run_tests.sh","lint:js":"eslint --max-warnings=0 ./src/ ./examples/ ./test/unit_tests ./index.js -f table --ext .js --ext .jsx","lint:js:fix":"eslint --max-warnings=0 ./src/ ./examples/ ./test/unit_tests ./index.js -f table --ext .js --ext .jsx --fix","lint":"npm run lint:js","build:dev":"./scripts/build_peg.sh && rollup -c","build":"./scripts/build_peg.sh && NODE_ENV=production rollup -c","clean":"rm -r dist/","prepublishOnly":"npm run build","semantic-release":"semantic-release"},"bugs":{"url":"https://github.com/epsagon/epsagon-node/issues"},"homepage":"https://github.com/epsagon/epsagon-node#readme","repository":{"type":"git","url":"git+https://github.com/epsagon/epsagon-node.git"},"main":"dist/bundle.js","husky":{"hooks":{"commit-msg":"commitlint -E HUSKY_GIT_PARAMS"}},"devDependencies":{"@babel/runtime":"^7.4.5","@commitlint/cli":"^9.1.2","@commitlint/config-angular":"^7.1.2","@commitlint/config-conventional":"^7.1.2","aws-sdk":"^2.197.0","chai":"^4.1.2","chai-as-promised":"^7.1.1","dotenv":"^8.2.0","eslint":"^4.18.0","eslint-config-airbnb":"^17.1.0","eslint-plugin-chai-friendly":"^0.4.1","eslint-plugin-import":"^2.14.0","eslint-plugin-json":"^1.2.1","eslint-plugin-jsx-a11y":"^6.1.1","eslint-plugin-mocha":"^4.11.0","eslint-plugin-react":"^7.11.0","husky":"^1.1.0","ldap-server-mock":"^3.0.0","ldapjs":"^2.1.0","lolex":"^3.0.0","mocha":"^5.0.4","mongodb":"^3.1.13","mysql":"^2.16.0","mysql2":"^1.6.4","pegjs":"^0.10.0","pg":"^7.6.0","pg-pool":"^2.0.3","proxyquire":"^2.0.1","redis":"^2.8.0","request":"^2.88.2","request-promise-native":"^1.0.7","rollup":"^0.66.6","rollup-plugin-commonjs":"^9.1.8","rollup-plugin-copy":"^3.1.0","rollup-plugin-eslint":"^5.0.0","rollup-plugin-json":"^3.1.0","rollup-plugin-terser":"^7.0.1","semantic-release":"^15.13.30","sinon":"^4.3.0","uglify-es":"^3.3.9"},"dependencies":{"axios":"^0.19.0","google-protobuf":"^3.5.0","json.sortify":"^2.2.2","md5":"^2.2.1","require-in-the-middle":"^5.0.3","shimmer":"^1.2.1","uuid-parse":"^1.1.0","uuid4":"^1.0.0"},"readme":"
\n\n[](https://travis-ci.com/epsagon/epsagon-node)\n[](https://badge.fury.io/js/epsagon)\n[](https://github.com/semantic-release/semantic-release)\n\n# Epsagon Tracing for Node.js\nThis package provides tracing to Node.js applications for the collection of distributed tracing and performance metrics in [Epsagon](https://app.epsagon.com/?utm_source=github).\n\n## Contents\n\n- [Installation](#installation)\n- [Usage](#usage)\n - [Auto-tracing](#auto-tracing)\n - [Calling the SDK](#calling-the-sdk)\n - [Tagging Traces](#tagging-traces)\n - [Custom Errors](#custom-errors)\n - [Filter Sensitive Data](#filter-sensitive-data)\n - [Ignore Endpoints](#ignore-endpoints)\n - [Trace URL](#trace-url)\n- [Frameworks](#frameworks)\n- [Integrations](#integrations)\n- [Configuration](#configuration)\n- [Getting Help](#getting-help)\n- [Opening Issues](#opening-issues)\n- [License](#license)\n\n## Installation\n\nTo install Epsagon, simply run:\n```sh\nnpm install epsagon\n```\n\n## Usage\n\n### Auto-tracing\n\nThe simplest way to get started in some frameworks is to install `epsagon-frameworks`:\n```sh\nnpm install epsagon-frameworks\n```\n\n[`epsagon-frameworks`](https://github.com/epsagon/epsagon-node-frameworks) extends the base `epsagon` support to more frameworks.\n\nAnd run your node command:\n```sh\nexport EPSAGON_TOKEN=\nexport EPSAGON_APP_NAME=\nexport NODE_OPTIONS='-r epsagon-frameworks'\n\n```\n\nFor example:\n```sh\nexport EPSAGON_TOKEN=\nexport EPSAGON_APP_NAME=express-prod\nexport NODE_OPTIONS='-r epsagon-frameworks'\nnode app.js\n```\n\nWhen using inside a `Dockerfile`, you can use `ENV` instead of `export`.\n\nYou can see the list of auto-tracing [supported frameworks](#frameworks)\n\n### Calling the SDK\n\nAnother simple alternative is to copy the snippet into your code:\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTo run on your framework please refer to [supported frameworks](#frameworks)\n\n\n### Tagging Traces\n\nYou can add custom tags to your traces, for easier filtering and aggregations.\n\nAdd the following call inside your code:\n```javascript\nepsagon.label('key', 'value');\nepsagon.label('userId', userId);\n```\n\nYou can also use it to ship custom metrics:\n```javascript\nepsagon.label('key', 'metric')\nepsagon.label('itemsInCart', itemsInCart)\n```\n\nYou can also use it iniside init function:\n```javascript\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n labels: [['key', 'value'], ['userId', userId]],\n});\n```\n\nValid types are `string`, `boolean` and `number`.\n\nIn some [frameworks](#frameworks) tagging can be done in different ways.\n\n### Custom Errors\n\nYou can set a trace as an error (although handled correctly) to get an alert or just follow it on the dashboard.\n\nAdd the following call inside your code:\n```javascript\ntry {\n // something bad happens\n} catch (err) {\n epsagon.setError(err);\n}\n\n// Or manually specify Error object\nepsagon.setError(Error('My custom error'));\n```\n\nIn some [frameworks](#frameworks) custom errors can be declared in different ways.\n\n### Filter Sensitive Data\n\nYou can pass a list of sensitive properties and hostnames and they will be filtered out from the traces:\n\n```javascript\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n ignoredKeys: ['password', /.*_token$/],\n urlPatternsToIgnore: ['example.com', 'auth.com'],\n});\n```\n\nThe `ignoredKeys` property can contain strings (will perform a loose match, so that `First Name` also matches `first_name`), regular expressions, and predicate functions.\nAlso, you can set `urlPatternsToIgnore` to ignore HTTP calls to specific domains.\n\n\n### Ignore Endpoints\n\nYou can ignore certain incoming requests by specifying endpoints:\n```javascript\nepsagon.ignoreEndpoints(['/healthcheck'])\n```\n\n### Trace URL\n\nYou can get the Epsagon dashboard URL for the current trace, using the following:\n```node\n# Inside some endpoint or function\nconsole.log('Epsagon trace URL:', epsagon.getTraceUrl())\n```\n\nThis can be useful to have an easy access the trace from different platforms.\n\n\n## Frameworks\n\nThe following frameworks are supported by Epsagon.\nSome require installing also [`epsagon-frameworks`](https://github.com/epsagon/epsagon-node-frameworks)\n\n|Framework |Supported Version |Epsagon Library |Auto-tracing Supported |\n|----------------------------------------|---------------------------|---------------------------------------------------|-----------------------------------------------------|\n|[AWS Lambda](#aws-lambda) |All |`epsagon` |
|\n\n\n### AWS Lambda\n\nTracing Lambda functions can be done in three methods:\n1. Auto-tracing through the Epsagon dashboard.\n2. Using the [`serverless-plugin-epsagon`](https://github.com/epsagon/serverless-plugin-epsagon) if you're using The Serverless Framework.\n3. Calling the SDK.\n\n**Make sure to choose just one of the methods**\n\nCalling the SDK is simple:\n\n```javascript\nconst epsagon = require('epsagon');\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n\n// Wrap your entry point\nmodule.exports.handler = epsagon.lambdaWrapper((event, context, callback) => {\n // Your code is here\n});\n\n// Async functions example\nmodule.exports.handler = epsagon.lambdaWrapper(async (event) => {\n // Your code is here\n});\n```\n\n### Step Functions\n\nTracing Step Functions is similar to regular Lambda functions, but the wrapper changes from `lambdaWrapper` to `stepLambdaWrapper`:\n\n```javascript\nconst epsagon = require('epsagon');\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n\n// Wrap your entry point\nmodule.exports.handler = epsagon.stepLambdaWrapper((event, context, callback) => {\n // Your code is here\n});\n\n// Async functions example\nmodule.exports.handler = epsagon.stepLambdaWrapper(async (event) => {\n // Your code is here\n});\n```\nECS Step - You should pass Epsagon step_dict id from ECS state input into ```EPSAGON_STEPS_ID``` environment variables of the container, ```EPSAGON_STEPS_NUM``` is the step number of the ECS (default: 0). check the [configuration](https://github.com/epsagon/epsagon-node/#configuration) section.\n\n### OpenWhisk Action\n\nYou should pass the Epsagon token to your action as a default parameter, so that you don't have to expose important credentials in your code.\nThe name of the parameter can be configured using `token_param`, in this example we use `epsagon-token`:\n\n```javascript\nconst epsagon = require('epsagon');\n\nfunction main(params) {\n // Your code is here\n}\n\nmodule.exports.main = epsagon.openWhiskWrapper(\n main,\n {\n token_param: 'epsagon-token', // name of the action parameter to take the token from\n appName: 'app-name-stage',\n metadataOnly: false\n }\n);\n```\n\n### AWS Batch\n\nTracing batch jobs running in AWS Batch can be done by wrapping the main handler/entrypoint of the code:\n\n```javascript\nconst epsagon = require('epsagon');\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n\n\nfunction process(params) {\n // Your code is here\n}\n\nconst wrappedProcess = epsagon.wrapBatchJob(process);\n```\n\n### Express\n\nTracing Express application can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the application is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\napp.get('/', (req, res) => {\n req.epsagon.label('key', 'value');\n req.epsagon.setError(Error('My custom error'));\n}\n```\n\n### Hapi\n\nTracing Hapi application can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the application is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\nserver.route({\n method: 'GET',\n path:'/',\n handler: (request, h) => {\n request.epsagon.label('key', 'value');\n request.epsagon.setError(Error('My custom error'));\n }\n});\n```\n\n### Koa\n\nTracing Koa application can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the application is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\napp.use(async ctx => {\n ctx.epsagon.label('key', 'value');\n ctx.epsagon.setError(Error('My custom error'));\n});\n```\n\n### WS (Websocket)\n\nTracing `ws` consumers can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the consumer is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\nsocket.on('message', (message) => {\n message.epsagon.label('key', 'value');\n message.epsagon.setError(Error('My custom error'));\n}) \n```\n\n### KafkaJS\n\nTracing `kafkajs` consumers can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the consumer is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\nawait consumer.run({\n eachMessage: async ({ topic, partition, message }) => {\n message.epsagon.label('key', 'value');\n message.epsagon.setError(Error('My custom error'));\n },\n})\n```\n\n### kafka-node\n\nTracing `kafka0node` consumers can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the consumer is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\nconsumer.on('message', function (message) {\n message.epsagon.label('key', 'value');\n message.epsagon.setError(Error('My custom error'));\n})\n```\n\n### PubSub\n\nTracing `@google-cloud/pubsub` consumers can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the consumer is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\nawait consumer.run({\n eachMessage: async ({ topic, partition, message }) => {\n message.epsagon.label('key', 'value');\n message.epsagon.setError(Error('My custom error'));\n },\n})\n```\n\n### SQS Consumer\n\nTracing [`sqs-consumer`](https://github.com/bbc/sqs-consumer) consumers can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the consumer is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\nconst messageHandler = message => {\n message.epsagon.label('key', 'value');\n message.epsagon.setError(Error('My custom error'));\n};\n```\n\nOr in batch message handler:\n```javascript\nconst batchMessageHandler = messages => {\n messages[0].epsagon.label('key', 'value');\n messages[0].epsagon.setError(Error('My custom error'));\n};\n```\n\n\n### amqplib\n\nTracing amqplib consumers can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the consumer is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\nch.consume(q, function cons(msg) {\n if (msg !== null) {\n msg.epsagon.label('key', 'value');\n msg.epsagon.setError(Error('My custom error'));\n ch.ack(msg);\n }\n});\n```\n\n### bunnybus\n\nTracing bunnybus consumers can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the consumer is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\n// epsagon is added as an argument to the handler\nhandler: async ({message, metaData, ack, rej, requeue, epsagon}) => {\n epsagon.label('key', 'value');\n epsagon.setError(Error('My custom error'));\n await ack();\n}\n```\n\n### NATS\n\nTracing `nats` consumers can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the consumer is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\n\n### Generic\n\nFor any tracing, you can simply use the generic Epsagon wrapper using the following example:\n\n```javascript\nconst epsagon = require('epsagon');\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n\n\nfunction main(params) {\n // Your code is here\n}\n\nconst wrappedMain = epsagon.nodeWrapper(main);\n```\n\n## Integrations\n\nEpsagon provides out-of-the-box instrumentation (tracing) for many popular frameworks and libraries.\n\n|Library |Supported Version |\n|--------------------|---------------------------|\n|http |Fully supported |\n|https |Fully supported |\n|http2 |Fully supported |\n|dns |Fully supported |\n|aws-sdk |`>=2.2.0` |\n|amazon-dax-client |`>=1.0.2` |\n|@google-cloud |`>=2.0.0` |\n|@google-cloud/pubsub|`>=1.1.0` |\n|mysql |`>=2` |\n|mysql2 |`>=1` |\n|pg |`>=4` |\n|mongodb |`>=2.2.12` |\n|kafkajs |`>=1.2.0` |\n|kafka-node |`>=3.0.0` |\n|amqplib |`>=0.5.0` |\n|amqp |`>=0.2.0` |\n|redis |`>=0.12.1` |\n|ioredis |`>=4.0.0` |\n|mqtt |`>=2.13.1` |\n|nats |`>=1.4.0` |\n|openwhisk |`>=3.0.0` |\n|@azure/cosmos |`>=3.7.5` |\n|@azure/storage-blob |`>=12.2.0` |\n|ldapjs |`>=2.1.0` |\n|ws |`>=7.3.1` |\n\n\n\n## Configuration\n\nAdvanced options can be configured as a parameter to the init() method or as environment variables.\n\n|Parameter |Environment Variable |Type |Default |Description |\n|-------------------|---------------------------|-------|-------------|-----------------------------------------------------------------------------------|\n|token |EPSAGON_TOKEN |String |- |Epsagon account token |\n|appName |EPSAGON_APP_NAME |String |`Application`|Application name that will be set for traces |\n|metadataOnly |EPSAGON_METADATA |Boolean|`true` |Whether to send only the metadata (`true`) or also the payloads (`false`) |\n|useSSL |EPSAGON_SSL |Boolean|`true` |Whether to send the traces over HTTPS SSL or not |\n|traceCollectorURL |EPSAGON_COLLECTOR_URL |String |- |The address of the trace collector to send trace to |\n|isEpsagonDisabled |DISABLE_EPSAGON |Boolean|`false` |A flag to completely disable Epsagon (can be used for tests or locally) |\n|ignoredKeys |EPSAGON_IGNORED_KEYS |Array |- |Array of keys names (can be string or regex) to be removed from the trace |\n|urlPatternsToIgnore|EPSAGON_URLS_TO_IGNORE |Array |`[]` |Array of URL patterns to ignore the calls |\n|sendTimeout |EPSAGON_SEND_TIMEOUT_SEC |Float |`1.0` |The timeout duration in seconds to send the traces to the trace collector |\n|decodeHTTP |EPSAGON_DECODE_HTTP |Boolean|`true` |Whether to decode and decompress HTTP responses into the payload |\n|httpErrorStatusCode|EPSAGON_HTTP_ERR_CODE |Integer|`400` |The minimum number of an HTTP response status code to treat as an error |\n|- |EPSAGON_PROPAGATE_LAMBDA_ID|Boolean|`False` |Insert Lambda request ID into the response payload |\n|- |DISABLE_EPSAGON_PATCH |Boolean|`false` |Disable the library patching (instrumentation) |\n|- |EPSAGON_DEBUG |Boolean|`false` |Enable debug prints for troubleshooting |\n|- |EPSAGON_PROPAGATE_NATS_ID |Boolean|`false` |Whether to propagate a correlation ID in NATS.io calls for distributed tracing |\n|- |EPSAGON_ADD_NODE_PATH |String |- |List of folders to looks for node_modules when patching libraries. Separated by `:`|\n|- |EPSAGON_AUTO_ADD_NODE_PATHS|Boolean |`false` |Auto add node_modules sub folders to look when patching libraries. |\n|- |EPSAGON_DNS_INSTRUMENTATION|Boolean|`false` |Whether to capture `dns` calls into the trace |\n|- |EPSAGON_LOGGING_TRACING_ENABLED|Boolean|`true` |whether to add an Epsagon ID to the logs in order to correlate traces to logs in the dashboard|\n|- |EPSAGON_STEPS_ID |String|- |The Epsagon step id from the ECS step functions state input |\n|- |EPSAGON_STEPS_NUM |String|`0` |The step number of the ECS step functions state |\n|- |EPSAGON_LAMBDA_TIMEOUT_THRESHOLD_MS |Integer|`200` |The threshold in millieseconds to send the trace before a Lambda timeout occurs |\n\n\n## Getting Help\n\nIf you have any issue around using the library or the product, please don't hesitate to:\n\n* Use the [documentation](https://docs.epsagon.com).\n* Use the help widget inside the product.\n* Open an issue in GitHub.\n\n\n## Opening Issues\n\nIf you encounter a bug with the Epsagon library for Node.js, we want to hear about it.\n\nWhen opening a new issue, please provide as much information about the environment:\n* Library version, Node.js runtime version, dependencies, etc.\n* Snippet of the usage.\n* A reproducible example can really help.\n\nThe GitHub issues are intended for bug reports and feature requests.\nFor help and questions about Epsagon, use the help widget inside the product.\n\n## License\n\nProvided under the MIT license. See LICENSE for details.\n\nCopyright 2020, Epsagon\n","readmeFilename":"README.md","gitHead":"87629ac6e3fa8f2432dce47763cbd71221749354","_id":"epsagon@1.88.1-beta.3","_nodeVersion":"12.18.2","_npmVersion":"6.14.5","dist":{"integrity":"sha512-QyWKscTtQiJ1bb50ip6FdyPL8do5F9wJWgBDvSfed3g9C3lDSnSNYKsSLgzqGTvKWa56+exFjPAeyNkyD1+PKw==","shasum":"7e7bc63cb01361e811cf32fae5460293cf89dfa5","tarball":"https://registry.npmjs.org/epsagon/-/epsagon-1.88.1-beta.3.tgz","fileCount":5,"unpackedSize":188132,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.13\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJfhvaVCRA9TVsSAnZWagAAc7YP/i23U1I+RGGb84lTOzfz\ntZeOfZDUZ1wO4A/x3oCF1skNBzb7Blt5+qcie6WbSRXqik7SVCvhfCifFCu6\nNHtIUArgmj37S6fI8T1d8zGXFCFUsFYkIO92SmI8gxLVKhOSj5bRo7LoCfFB\n1hI6mJ1mtIbrHV1qj4tb4dKnkTBgXGQwg6tjBh5gfaozfey+hBfyX8VtFo8/\n2rGTFnM7EaTRivd3ee0xkrefCf8+GpwVoY3GSsvhaXClrFkSbqMn5eMEaajl\nqgu8qkvq+0KHv4w3F6y0VpElaT8gKp92+/IK/0AlYlqro31RTGIsXhVmgWQ0\nml2NLZ+puFhARiL5yX+uKCUpcTqvy1IBWcIP5d/z8yZ+v202YsfXWzCyTtd4\ne0flkGDaUwPzbP/1IbgWW8ufSU+wt1OtCbTna43wDrWtMQHZv57Xr+cnJQ3h\nc5/2POX/A1LPNBnrY5aBQm6u8oCFq1X/hQPJhQDzoalgB1K6scFuPJhMym1/\nfvmCW6CKIEbbCVEIwH7YPPN+JXunI11l59Ia6IMAnzZuBdfxP99IRK7mxRXz\nxRu22/YsLSZEqPuywdPuqQ+2tEOtAst/dVha6f7ejTbMcys5xdM7cZ2rgwQ1\n1AuLG53BejCkwA4z7hfRbETO5qD1mEvPvRHw4XexL6o/LZ9r2S54U9yhPlvd\nB2gx\r\n=5HcU\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCICD5Biew+0iIlEsDS8LvxEOEAZpBotUlrPXGbSq8X+kzAiAY94jtEfLPCKiEkwVbS9mlYWqJ6sW3rulA7CvOgsg73w=="}]},"maintainers":[{"name":"epsagon","email":"dev@epsagon.com"}],"_npmUser":{"name":"epsagon","email":"dev@epsagon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/epsagon_1.88.1-beta.3_1602680468835_0.9105629793474226"},"_hasShrinkwrap":false},"1.88.1-beta.4":{"name":"epsagon","version":"1.88.1-beta.4","description":"Epsagon Instrumentation for Node.js","keywords":["serverless","epsagon","tracing","distributed-tracing","lambda","aws-lambda","debugging","monitoring"],"author":{"name":"Epsagon Team","email":"support@epsagon.com"},"license":"MIT","scripts":{"pretest":"./scripts/build_peg.sh","test":"./scripts/run_tests.sh","lint:js":"eslint --max-warnings=0 ./src/ ./examples/ ./test/unit_tests ./index.js -f table --ext .js --ext .jsx","lint:js:fix":"eslint --max-warnings=0 ./src/ ./examples/ ./test/unit_tests ./index.js -f table --ext .js --ext .jsx --fix","lint":"npm run lint:js","build:dev":"./scripts/build_peg.sh && rollup -c","build":"./scripts/build_peg.sh && NODE_ENV=production rollup -c","clean":"rm -r dist/","prepublishOnly":"npm run build","semantic-release":"semantic-release"},"bugs":{"url":"https://github.com/epsagon/epsagon-node/issues"},"homepage":"https://github.com/epsagon/epsagon-node#readme","repository":{"type":"git","url":"git+https://github.com/epsagon/epsagon-node.git"},"main":"dist/bundle.js","husky":{"hooks":{"commit-msg":"commitlint -E HUSKY_GIT_PARAMS"}},"devDependencies":{"@babel/runtime":"^7.4.5","@commitlint/cli":"^9.1.2","@commitlint/config-angular":"^7.1.2","@commitlint/config-conventional":"^7.1.2","aws-sdk":"^2.197.0","chai":"^4.1.2","chai-as-promised":"^7.1.1","dotenv":"^8.2.0","eslint":"^4.18.0","eslint-config-airbnb":"^17.1.0","eslint-plugin-chai-friendly":"^0.4.1","eslint-plugin-import":"^2.14.0","eslint-plugin-json":"^1.2.1","eslint-plugin-jsx-a11y":"^6.1.1","eslint-plugin-mocha":"^4.11.0","eslint-plugin-react":"^7.11.0","husky":"^1.1.0","ldap-server-mock":"^3.0.0","ldapjs":"^2.1.0","lolex":"^3.0.0","mocha":"^5.0.4","mongodb":"^3.1.13","mysql":"^2.16.0","mysql2":"^1.6.4","pegjs":"^0.10.0","pg":"^7.6.0","pg-pool":"^2.0.3","proxyquire":"^2.0.1","redis":"^2.8.0","request":"^2.88.2","request-promise-native":"^1.0.7","rollup":"^0.66.6","rollup-plugin-commonjs":"^9.1.8","rollup-plugin-copy":"^3.1.0","rollup-plugin-eslint":"^5.0.0","rollup-plugin-json":"^3.1.0","rollup-plugin-terser":"^7.0.1","semantic-release":"^15.13.30","sinon":"^4.3.0","uglify-es":"^3.3.9"},"dependencies":{"axios":"^0.19.0","google-protobuf":"^3.5.0","json.sortify":"^2.2.2","md5":"^2.2.1","require-in-the-middle":"^5.0.3","shimmer":"^1.2.1","uuid-parse":"^1.1.0","uuid4":"^1.0.0"},"readme":"
\n\n[](https://travis-ci.com/epsagon/epsagon-node)\n[](https://badge.fury.io/js/epsagon)\n[](https://github.com/semantic-release/semantic-release)\n\n# Epsagon Tracing for Node.js\nThis package provides tracing to Node.js applications for the collection of distributed tracing and performance metrics in [Epsagon](https://app.epsagon.com/?utm_source=github).\n\n## Contents\n\n- [Installation](#installation)\n- [Usage](#usage)\n - [Auto-tracing](#auto-tracing)\n - [Calling the SDK](#calling-the-sdk)\n - [Tagging Traces](#tagging-traces)\n - [Custom Errors](#custom-errors)\n - [Filter Sensitive Data](#filter-sensitive-data)\n - [Ignore Endpoints](#ignore-endpoints)\n - [Trace URL](#trace-url)\n- [Frameworks](#frameworks)\n- [Integrations](#integrations)\n- [Configuration](#configuration)\n- [Getting Help](#getting-help)\n- [Opening Issues](#opening-issues)\n- [License](#license)\n\n## Installation\n\nTo install Epsagon, simply run:\n```sh\nnpm install epsagon\n```\n\n## Usage\n\n### Auto-tracing\n\nThe simplest way to get started in some frameworks is to install `epsagon-frameworks`:\n```sh\nnpm install epsagon-frameworks\n```\n\n[`epsagon-frameworks`](https://github.com/epsagon/epsagon-node-frameworks) extends the base `epsagon` support to more frameworks.\n\nAnd run your node command:\n```sh\nexport EPSAGON_TOKEN=\nexport EPSAGON_APP_NAME=\nexport NODE_OPTIONS='-r epsagon-frameworks'\n\n```\n\nFor example:\n```sh\nexport EPSAGON_TOKEN=\nexport EPSAGON_APP_NAME=express-prod\nexport NODE_OPTIONS='-r epsagon-frameworks'\nnode app.js\n```\n\nWhen using inside a `Dockerfile`, you can use `ENV` instead of `export`.\n\nYou can see the list of auto-tracing [supported frameworks](#frameworks)\n\n### Calling the SDK\n\nAnother simple alternative is to copy the snippet into your code:\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTo run on your framework please refer to [supported frameworks](#frameworks)\n\n\n### Tagging Traces\n\nYou can add custom tags to your traces, for easier filtering and aggregations.\n\nAdd the following call inside your code:\n```javascript\nepsagon.label('key', 'value');\nepsagon.label('userId', userId);\n```\n\nYou can also use it to ship custom metrics:\n```javascript\nepsagon.label('key', 'metric')\nepsagon.label('itemsInCart', itemsInCart)\n```\n\nYou can also use it iniside init function:\n```javascript\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n labels: [['key', 'value'], ['userId', userId]],\n});\n```\n\nValid types are `string`, `boolean` and `number`.\n\nIn some [frameworks](#frameworks) tagging can be done in different ways.\n\n### Custom Errors\n\nYou can set a trace as an error (although handled correctly) to get an alert or just follow it on the dashboard.\n\nAdd the following call inside your code:\n```javascript\ntry {\n // something bad happens\n} catch (err) {\n epsagon.setError(err);\n}\n\n// Or manually specify Error object\nepsagon.setError(Error('My custom error'));\n```\n\nIn some [frameworks](#frameworks) custom errors can be declared in different ways.\n\n### Filter Sensitive Data\n\nYou can pass a list of sensitive properties and hostnames and they will be filtered out from the traces:\n\n```javascript\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n ignoredKeys: ['password', /.*_token$/],\n urlPatternsToIgnore: ['example.com', 'auth.com'],\n});\n```\n\nThe `ignoredKeys` property can contain strings (will perform a loose match, so that `First Name` also matches `first_name`), regular expressions, and predicate functions.\nAlso, you can set `urlPatternsToIgnore` to ignore HTTP calls to specific domains.\n\n\n### Ignore Endpoints\n\nYou can ignore certain incoming requests by specifying endpoints:\n```javascript\nepsagon.ignoreEndpoints(['/healthcheck'])\n```\n\n### Trace URL\n\nYou can get the Epsagon dashboard URL for the current trace, using the following:\n```node\n# Inside some endpoint or function\nconsole.log('Epsagon trace URL:', epsagon.getTraceUrl())\n```\n\nThis can be useful to have an easy access the trace from different platforms.\n\n\n## Frameworks\n\nThe following frameworks are supported by Epsagon.\nSome require installing also [`epsagon-frameworks`](https://github.com/epsagon/epsagon-node-frameworks)\n\n|Framework |Supported Version |Epsagon Library |Auto-tracing Supported |\n|----------------------------------------|---------------------------|---------------------------------------------------|-----------------------------------------------------|\n|[AWS Lambda](#aws-lambda) |All |`epsagon` |
\n\n[](https://travis-ci.com/epsagon/epsagon-node)\n[](https://badge.fury.io/js/epsagon)\n[](https://github.com/semantic-release/semantic-release)\n\n# Epsagon Tracing for Node.js\n\n\n\nThis package provides tracing to Node.js applications for the collection of distributed tracing and performance metrics in [Epsagon](https://app.epsagon.com/?utm_source=github).\n\n## Contents\n\n- [Installation](#installation)\n- [Usage](#usage)\n - [Auto-tracing](#auto-tracing)\n - [Calling the SDK](#calling-the-sdk)\n - [Tagging Traces](#tagging-traces)\n - [Custom Errors](#custom-errors)\n - [Filter Sensitive Data](#filter-sensitive-data)\n - [Ignore Endpoints](#ignore-endpoints)\n - [Trace URL](#trace-url)\n- [Frameworks](#frameworks)\n- [Integrations](#integrations)\n- [Configuration](#configuration)\n- [Getting Help](#getting-help)\n- [Opening Issues](#opening-issues)\n- [License](#license)\n\n\n## Installation\n\nTo install Epsagon, simply run:\n```sh\nnpm install epsagon\n```\n\n## Usage\n**Important: Epsagon is activated and instruments the supported libraries once the module is imported.**\n\n### Auto-tracing\n\nThe simplest way to get started in some frameworks is to install `epsagon-frameworks`:\n```sh\nnpm install epsagon-frameworks\n```\n\n[`epsagon-frameworks`](https://github.com/epsagon/epsagon-node-frameworks) extends the base `epsagon` support to more frameworks.\n\nAnd run your node command:\n```sh\nexport EPSAGON_TOKEN=\nexport EPSAGON_APP_NAME=\nexport EPSAGON_METADATA=FALSE\nexport NODE_OPTIONS='-r epsagon-frameworks'\n\n```\n\nFor example:\n```sh\nexport EPSAGON_TOKEN=\nexport EPSAGON_APP_NAME=express-prod\nexport EPSAGON_METADATA=FALSE\nexport NODE_OPTIONS='-r epsagon-frameworks'\nnode app.js\n```\n\nWhen using inside a `Dockerfile`, you can use `ENV` instead of `export`.\n\nYou can see the list of auto-tracing [supported frameworks](#frameworks)\n\n### Calling the SDK\n\nAnother simple alternative is to copy the snippet into your code:\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n sendBatch: false,\n});\n```\n\nTo run on your framework please refer to [supported frameworks](#frameworks)\n\n\n### Tagging Traces\n\nYou can add custom tags to your traces, for easier filtering and aggregations.\n\nAdd the following call inside your code:\n```javascript\nepsagon.label('key', 'value');\nepsagon.label('userId', userId);\n```\n\nYou can also use it to ship custom metrics:\n```javascript\nepsagon.label('key', 'metric')\nepsagon.label('itemsInCart', itemsInCart)\n```\n\nYou can also set global labels as part of the Epsagon initialisation:\n```javascript\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n labels: [['key', 'value'], ['userId', userId]],\n});\n```\n\nValid types are `string`, `boolean` and `number`.\n\nIn some [frameworks](#frameworks) tagging can be done in different ways.\n\n### Custom Errors\n\nYou can set a trace as an error (although handled correctly) to get an alert or just follow it on the dashboard.\n\nAdd the following call inside your code:\n```javascript\ntry {\n // something bad happens\n} catch (err) {\n epsagon.setError(err);\n}\n\n// or manually specify Error object\nepsagon.setError(Error('My custom error'));\n```\n\n### Custom Warnings\n\nThis API allows you to flag the trace with a warning and also enables more flexible alerting\n\nAdd the following call inside your code:\n```javascript\ntry {\n // something bad happens\n} catch (err) {\n epsagon.setWarning(err);\n}\n\n// Or manually specify Error object\nepsagon.setWarning(Error('My custom error'));\n```\n\nIn some [frameworks](#frameworks) custom errors can be declared in different ways.\n\n### Filter Sensitive Data\n\nYou can pass a list of sensitive properties and hostnames and they will be filtered out from the traces:\n\n```javascript\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n ignoredKeys: ['password', /.*_token$/],\n ignoredDBTables: ['users', /.*password$/],\n urlPatternsToIgnore: ['example.com', 'auth.com'],\n});\n```\n\nThe `ignoredKeys` property can contain strings (will perform a loose match, so that `First Name` also matches `first_name`), regular expressions, and predicate functions. \n`ignoredDBTables` works similary, except will ignore response rows from DB queries.\n\nAlso, you can set `urlPatternsToIgnore` to ignore HTTP calls to specific domains.\n\n\n### Ignore Endpoints\n\nYou can ignore certain incoming requests by specifying endpoints:\n```javascript\nepsagon.ignoreEndpoints(['/healthcheck'])\n```\n\n### Trace URL\n\nYou can get the Epsagon dashboard URL for the current trace, using the following:\n```node\n# Inside some endpoint or function\nconsole.log('Epsagon trace URL:', epsagon.getTraceUrl())\n```\n\nThis can be useful to have an easy access the trace from different platforms.\n\n\n## Frameworks\n\nThe following frameworks are supported by Epsagon.\nSome require installing also [`epsagon-frameworks`](https://github.com/epsagon/epsagon-node-frameworks)\n\n|Framework |Supported Version |Epsagon Library |Auto-tracing Supported |\n|----------------------------------------|---------------------------|---------------------------------------------------|-----------------------------------------------------|\n|[AWS Lambda](#aws-lambda) |All |`epsagon` |
|\n\n\n### AWS Lambda\n\nTracing Lambda functions can be done in three methods:\n1. Auto-tracing through the Epsagon dashboard.\n2. Using the [`serverless-plugin-epsagon`](https://github.com/epsagon/serverless-plugin-epsagon) if you're using The Serverless Framework.\n3. Calling the SDK.\n\n**Make sure to choose just one of the methods**\n\nCalling the SDK is simple:\n\n```javascript\nconst epsagon = require('epsagon');\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n\n// Wrap your entry point\nmodule.exports.handler = epsagon.lambdaWrapper((event, context, callback) => {\n // Your code is here\n});\n\n// Async functions example\nmodule.exports.handler = epsagon.lambdaWrapper(async (event) => {\n // Your code is here\n});\n```\n\n### Step Functions\n\nTracing Step Functions is similar to regular Lambda functions, but the wrapper changes from `lambdaWrapper` to `stepLambdaWrapper`:\n\n```javascript\nconst epsagon = require('epsagon');\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n\n// Wrap your entry point\nmodule.exports.handler = epsagon.stepLambdaWrapper((event, context, callback) => {\n // Your code is here\n});\n\n// Async functions example\nmodule.exports.handler = epsagon.stepLambdaWrapper(async (event) => {\n // Your code is here\n});\n```\nECS Step - You should pass Epsagon step_dict id from ECS state input into ```EPSAGON_STEPS_ID``` environment variables of the container, ```EPSAGON_STEPS_NUM``` is the step number of the ECS (default: 0). check the [configuration](https://github.com/epsagon/epsagon-node/#configuration) section.\n\n### OpenWhisk Action\n\nYou should pass the Epsagon token to your action as a default parameter, so that you don't have to expose important credentials in your code.\nThe name of the parameter can be configured using `token_param`, in this example we use `epsagon-token`:\n\n```javascript\nconst epsagon = require('epsagon');\n\nfunction main(params) {\n // Your code is here\n}\n\nmodule.exports.main = epsagon.openWhiskWrapper(\n main,\n {\n token_param: 'epsagon-token', // name of the action parameter to take the token from\n appName: 'app-name-stage',\n metadataOnly: false\n }\n);\n```\n\n### Google Cloud Function\n\nTracing Google Cloud Functions by wrapping your entry point with the `epsagon.googleCloudFunctionWrapper`:\n\n```javascript\nconst epsagon = require('epsagon');\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n sendBatch: false,\n});\n\n// Wrap your entry point\nexports.helloWorld = epsagon.googleCloudFunctionWrapper((req, res) => {\n res.status(200).send('hello world');\n});\n```\n\n### AWS Batch\n\nTracing batch jobs running in AWS Batch can be done by calling `epsagon.wrapBatchJob()` at the main handler/entrypoint of the code:\n\n```javascript\nconst epsagon = require('epsagon');\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n labels: [[\"key\", \"value\"]],\n traceCollectorURL: \"https://eu-central-1.tc.epsagon.com\" // default region is us-east-1\n});\n\nepsagon.wrapBatchJob();\n\nfunction process(params) {\n try {\n // your code here\n } catch (error) {\n // some other code here\n process.exitCode = 1; //exits gracefully\n }\n}\n```\n\n### Express\n\nTracing Express application can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the application is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\napp.get('/', (req, res) => {\n req.epsagon.label('key', 'value');\n req.epsagon.setError(Error('My custom error'));\n}\n```\n\n### Hapi\n\nTracing Hapi application can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the application is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\nserver.route({\n method: 'GET',\n path:'/',\n handler: (request, h) => {\n request.epsagon.label('key', 'value');\n request.epsagon.setError(Error('My custom error'));\n }\n});\n```\n\n### Koa\n\nTracing Koa application can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the application is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\napp.use(async ctx => {\n ctx.epsagon.label('key', 'value');\n ctx.epsagon.setError(Error('My custom error'));\n});\n```\n\n### WS (Websocket)\n\nTracing `ws` consumers can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the consumer is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\nsocket.on('message', (message) => {\n message.epsagon.label('key', 'value');\n message.epsagon.setError(Error('My custom error'));\n}) \n```\n\n### restify\n\nTracing restify application can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the application is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\nfunction respond(req, res, next) {\n req.epsagon.label('key', 'value');\n req.epsagon.setError(Error('My custom error'));\n}\n```\n\n### fastify\n\nTracing fastify application can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the application is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\nfastify.get('/', (request, reply) => {\n request.epsagon.label('key', 'value');\n request.epsagon.setError(Error('My custom error'));\n reply.send({ hello: 'world' })\n})\n```\n\n### KafkaJS\n\nTracing `kafkajs` consumers can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the consumer is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\nawait consumer.run({\n eachMessage: async ({ topic, partition, message }) => {\n message.epsagon.label('key', 'value');\n message.epsagon.setError(Error('My custom error'));\n },\n})\n```\n\n### kafka-node\n\nTracing `kafka0node` consumers can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the consumer is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\nconsumer.on('message', function (message) {\n message.epsagon.label('key', 'value');\n message.epsagon.setError(Error('My custom error'));\n})\n```\n\n### PubSub\n\nTracing `@google-cloud/pubsub` consumers can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the consumer is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\nawait consumer.run({\n eachMessage: async ({ topic, partition, message }) => {\n message.epsagon.label('key', 'value');\n message.epsagon.setError(Error('My custom error'));\n },\n})\n```\n\n### SQS Consumer\n\nTracing [`sqs-consumer`](https://github.com/bbc/sqs-consumer) consumers can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the consumer is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\nconst messageHandler = message => {\n message.epsagon.label('key', 'value');\n message.epsagon.setError(Error('My custom error'));\n};\n```\n\nOr in batch message handler:\n```javascript\nconst batchMessageHandler = messages => {\n messages[0].epsagon.label('key', 'value');\n messages[0].epsagon.setError(Error('My custom error'));\n};\n```\n\n\n### amqplib\n\nTracing amqplib consumers can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the consumer is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\nch.consume(q, function cons(msg) {\n if (msg !== null) {\n msg.epsagon.label('key', 'value');\n msg.epsagon.setError(Error('My custom error'));\n ch.ack(msg);\n }\n});\n```\n\n### bunnybus\n\nTracing bunnybus consumers can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the consumer is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\nTagging traces or setting custom errors can be by:\n\n```javascript\n// epsagon is added as an argument to the handler\nhandler: async ({message, metaData, ack, rej, requeue, epsagon}) => {\n epsagon.label('key', 'value');\n epsagon.setError(Error('My custom error'));\n await ack();\n}\n```\n\n### NATS\n\nTracing `nats` consumers can be done in two methods:\n1. [Auto-tracing](#auto-tracing) using the environment variable.\n2. Calling the SDK.\n\nCalling the SDK is simple, and should be done in your main `js` file where the consumer is being initialized:\n\n```javascript\nconst epsagon = require('epsagon-frameworks');\n\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n```\n\n\n### Generic\n\nFor any tracing, you can simply use the generic Epsagon wrapper using the following example:\n\n```javascript\nconst epsagon = require('epsagon');\nepsagon.init({\n token: 'epsagon-token',\n appName: 'app-name-stage',\n metadataOnly: false,\n});\n\n\nfunction main(params) {\n // Your code is here\n}\n\nconst wrappedMain = epsagon.nodeWrapper(main);\n```\n\n## Integrations\n\nEpsagon provides out-of-the-box instrumentation (tracing) for many popular frameworks and libraries.\n\n|Library |Supported Version |\n|--------------------|---------------------------|\n|http |Fully supported |\n|https |Fully supported |\n|http2 |Fully supported |\n|dns |Fully supported |\n|fs |Fully supported |\n|aws-sdk |`>=2.2.0` |\n|amazon-dax-client |`>=1.0.2` |\n|@google-cloud |`>=2.0.0` |\n|@google-cloud/pubsub|`>=1.1.0` |\n|mysql |`>=2` |\n|mysql2 |`>=1` |\n|pg |`>=4` |\n|mongodb |`>=2.2.12` |\n|kafkajs |`>=1.2.0` |\n|kafka-node |`>=3.0.0` |\n|amqplib |`>=0.5.0` |\n|amqp |`>=0.2.0` |\n|redis |`>=0.12.1` |\n|ioredis |`>=4.0.0` |\n|cassandra-driver |`>=3.3.0` |\n|mqtt |`>=2.13.1` |\n|nats |`>=1.4.0` |\n|openwhisk |`>=3.0.0` |\n|@azure/cosmos |`>=3.7.5` |\n|@azure/storage-blob |`>=12.2.0` |\n|ldapjs |`>=2.1.0` |\n|ws |`>=7.3.1` |\n|pino |`>=6.0.0` |\n|bunyan |`>=1.8.0` |\n|winston |`>=2.4.5` |\n\n\n\n## Configuration\n\nAdvanced options can be configured as a parameter to the init() method or as environment variables.\n\n|Parameter |Environment Variable |Type |Default |Description |\n|-------------------|---------------------------|-------|-------------|-----------------------------------------------------------------------------------|\n|token |EPSAGON_TOKEN |String |- |Epsagon account token |\n|appName |EPSAGON_APP_NAME |String |`Application`|Application name that will be set for traces |\n|metadataOnly |EPSAGON_METADATA |Boolean|`true` |Whether to send only the metadata (`true`) or also the payloads (`false`) |\n|useSSL |EPSAGON_SSL |Boolean|`true` |Whether to send the traces over HTTPS SSL or not |\n|traceCollectorURL |EPSAGON_COLLECTOR_URL |String |- |The address of the trace collector to send trace to |\n|isEpsagonDisabled |DISABLE_EPSAGON |Boolean|`false` |A flag to completely disable Epsagon (can be used for tests or locally) |\n|keysToAllow |EPSAGON_ALLOWED_KEYS |Boolean|- |Array of keys to automatically label in the trace |\n|ignoredKeys |EPSAGON_IGNORED_KEYS |Array |- |Array of keys names (can be string or regex) to be removed from the trace |\n|ignoredDBTables |EPSAGON_IGNORED_DB_TABLES |Array |- |Array of DB Table names (can be string or regex) to ignore response from trace. |\n|removeIgnoredKeys |EPSAGON_REMOVE_IGNORED_KEYS|Boolean|`false` |Whether to remove ignored keys instead of masking them |\n|urlPatternsToIgnore|EPSAGON_URLS_TO_IGNORE |Array |`[]` |Array of URL patterns to ignore the calls |\n|sendTimeout |EPSAGON_SEND_TIMEOUT_SEC |Float |`1.0` |The timeout duration in seconds to send the traces to the trace collector |\n|sendBatch |EPSAGON_SEND_BATCH |Boolean|`true ` |Whether to set the traces in batch mode, effective under high scale (set `false` for development) |\n|batchSize |EPSAGON_BATCH_SIZE |Integer|`5 ` |The traces' batch size, when batch mode is activated |\n|decodeHTTP |EPSAGON_DECODE_HTTP |Boolean|`true` |Whether to decode and decompress HTTP responses into the payload |\n|httpErrorStatusCode|EPSAGON_HTTP_ERR_CODE |Integer|`400` |The minimum number of an HTTP response status code to treat as an error |\n|- |EPSAGON_ALLOW_ERR_MESSAGE_STATUS|Boolean|`true` |Whether to override `http.status_code` with a Status Code found in a raised Error's Message|\n|- |EPSAGON_PROPAGATE_LAMBDA_ID|Boolean|`false` |Insert Lambda request ID into the response payload |\n|- |DISABLE_EPSAGON_PATCH |Boolean|`false` |Disable the library patching (instrumentation) |\n|isConsolePatched |EPSAGON_PATCH_CONSOLE |Boolean|`false` |Enable console module patching (instrumentation) for labelling |\n|- |EPSAGON_DEBUG |Boolean|`false` |Enable debug prints for troubleshooting |\n|- |EPSAGON_PROPAGATE_NATS_ID |Boolean|`false` |Whether to propagate a correlation ID in NATS.io calls for distributed tracing |\n|- |EPSAGON_ADD_NODE_PATH |String |- |List of folders to looks for node_modules when patching libraries. Separated by `:`|\n|- |EPSAGON_AUTO_ADD_NODE_PATHS|Boolean |`false` |Auto add node_modules sub folders to look when patching libraries. |\n|- |EPSAGON_DNS_INSTRUMENTATION|Boolean|`false` |Whether to capture `dns` calls into the trace |\n|- |EPSAGON_FS_INSTRUMENTATION |Boolean|`false` |Whether to capture node `file system` calls into the trace |\n|- |EPSAGON_LOGGING_TRACING_ENABLED|Boolean|`true` |whether to add an Epsagon ID to the logs in order to correlate traces to logs in the dashboard|\n|- |EPSAGON_STEPS_ID |String|- |The Epsagon step id from the ECS step functions state input |\n|- |EPSAGON_STEPS_NUM |String|`0` |The step number of the ECS step functions state |\n|- |EPSAGON_ALLOW_NO_ROUTE |Boolean|`false` |Whether to capture non-matched route requests in Express.js |\n|- |EPSAGON_LAMBDA_TIMEOUT_THRESHOLD_MS |Integer|`200` |The threshold in milliseconds to send the trace before a Lambda timeout occurs |\n|- |EPSAGON_PAYLOADS_TO_IGNORE | Array |- |Array of dictionaries to not instrument. Example: `'[{\"source\": \"serverless-plugin-warmup\"}]'` |\n\n\n## Getting Help\n\nIf you have any issue around using the library or the product, please don't hesitate to:\n\n* Use the [documentation](https://docs.epsagon.com).\n* Use the help widget inside the product.\n* Open an issue in GitHub.\n\n\n## Opening Issues\n\nIf you encounter a bug with the Epsagon library for Node.js, we want to hear about it.\n\nWhen opening a new issue, please provide as much information about the environment:\n* Library version, Node.js runtime version, dependencies, etc.\n* Snippet of the usage.\n* A reproducible example can really help.\n\nThe GitHub issues are intended for bug reports and feature requests.\nFor help and questions about Epsagon, use the help widget inside the product.\n\n## License\n\nProvided under the MIT license. See LICENSE for details.\n\nCopyright 2021, Epsagon\n\n","readmeFilename":"README.md"}
![](\"https://cdn2.hubspot.net/hubfs/4636301/Positive%20RGB_Logo%20Horizontal%20-01.svg\")
\n \n