{"id":23330433,"url":"https://github.com/iopipe/iopipe-js-trace","last_synced_at":"2025-08-23T00:31:04.337Z","repository":{"id":23732982,"uuid":"99581466","full_name":"iopipe/iopipe-js-trace","owner":"iopipe","description":"Custom timings + tracing for AWS Lambda serverless functions","archived":false,"fork":false,"pushed_at":"2023-01-25T07:55:34.000Z","size":1323,"stargazers_count":8,"open_issues_count":32,"forks_count":5,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-12-14T05:15:07.732Z","etag":null,"topics":["aws","aws-lambda","iopipe","iopipe-plugin","monitoring","nodejs","performance","performance-monitoring","serverless","tracing"],"latest_commit_sha":null,"homepage":"https://www.iopipe.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iopipe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-08-07T13:34:36.000Z","updated_at":"2019-10-01T17:04:36.000Z","dependencies_parsed_at":"2023-02-14T05:47:04.562Z","dependency_job_id":null,"html_url":"https://github.com/iopipe/iopipe-js-trace","commit_stats":null,"previous_names":["iopipe/iopipe-plugin-trace"],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iopipe%2Fiopipe-js-trace","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iopipe%2Fiopipe-js-trace/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iopipe%2Fiopipe-js-trace/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iopipe%2Fiopipe-js-trace/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iopipe","download_url":"https://codeload.github.com/iopipe/iopipe-js-trace/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230650672,"owners_count":18259299,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","aws-lambda","iopipe","iopipe-plugin","monitoring","nodejs","performance","performance-monitoring","serverless","tracing"],"created_at":"2024-12-20T22:18:02.063Z","updated_at":"2024-12-20T22:18:02.682Z","avatar_url":"https://github.com/iopipe.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# IOpipe Trace Plugin\n\n[![styled with prettier](https://img.shields.io/badge/styled_with-prettier-ff69b4.svg)](https://github.com/prettier/prettier)\n[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)\n\nCreate marks and measures for arbitrary units of time. Measure latency of database calls, third party requests, or code blocks and visualize them in [IOpipe](https://iopipe.com)!\n\nSupports automatic tracing of functions using Node's native `http` and `https`, as well as `ioredis`.\n\n## Requirements\n- Node \u003e= `8.10.0`\n- NPM \u003e= `6.9.0`\n- [IOpipe](https://github.com/iopipe/iopipe-js) \u003e= `1.x`\n\n## Install\n\n__Note: This plugin is automatically included in the recommended package [@iopipe/iopipe](https://github.com/iopipe/iopipe-js)__\n\nWith [yarn](https://yarnpkg.com) (recommended) in project directory:\n\n`yarn add @iopipe/trace`\n\nWith npm in project directory:\n\n`npm install @iopipe/trace`\n\nThen include the plugin with IOpipe in your serverless function:\n\n```js\nconst iopipeLib = require('@iopipe/iopipe');\nconst tracePlugin = require('@iopipe/trace');\n\nconst iopipe = iopipeLib({\n  token: 'TOKEN_HERE',\n  plugins: [tracePlugin()]\n});\n\n// wrap your lambda handler\nexports.handler = iopipe((event, context) =\u003e {\n  const {mark} = context.iopipe;\n  mark.start('database');\n  // after database call is finished\n  mark.end('database');\n\n  mark.start('analytics');\n  // after analytics call is finished\n  mark.end('analytics');\n  context.succeed('Wow!');\n});\n```\n\n## Methods\n\n```js\n// create the start mark\n// the string argument is a name you are assigning the particular trace\ncontext.iopipe.mark.start('db');\n\n// create the end mark\n// pass the name of the trace that you want to end\ncontext.iopipe.mark.end('db');\n\n// create an custom measurement between start:init and end:db\ncontext.iopipe.measure('custom', 'init', 'db');\n```\n\n## Config\n\n#### `autoHttp` (object: optional = {})\n\nAutomatically create traces and matching metadata for each http/s call made within your function invocation.\n\n#### `autoHttp.enabled` (bool: optional = false)\n\nEnable HTTP/S auto-tracing. Enabled by default. You can also use the environment variable `IOPIPE_TRACE_AUTO_HTTP_ENABLED`.\n\n#### `autoHttp.filter` (func: optional)\n\nFilter what data is recorded for each http request that occurs within the invocation. The function will be passed two arguments. The first is an object containing \"safe\" data that is typically not sensitive in nature. The second argument is a more complete object with the same shape that may include sensitive data. You can use these objects to determine:\n- A. What information to record / not to record (i.e. filter out certain headers)\n- B. If the http call should be completely excluded from trace data (ie filter out sensitive calls altogether)\n\n```js\nconst iopipe = iopipeLib({\n  plugins: [\n    tracePlugin({\n      autoHttp: {\n        enabled: true,\n        filter: (safeData, allData) =\u003e {\n          // obj = {'request.url':'http://iopipe.com', 'request.method': 'GET'}\n          // return the object with filtered keys\n          // or return false to exclude the trace data completely\n          const url = safeData['request.url'];\n          if (url.match(/restricted/)) {\n            // if you don't want any traces on this restricted URI return false\n            return false;\n          } else if (url.match(/cat-castle/)) {\n            // if you need to keep track of a sensitive header\n            return Object.assign(safeData, {\n              'request.headers.cookie': allData['request.headers.cookie']\n            });\n          }\n          // if you want to record the default data after some logic checks\n          return safeData;\n        }\n      }\n    })\n  ]\n});\n```\n#### `autoRedis` Automatically trace Redis commands using redis (node_redis)\n\nSet the environment variable `IOPIPE_TRACE_REDIS` to `true`, and IOpipe will trace Redis commands automatically: which command, which key is being read or written, and information about the connection: hostname, port, and connection name (if defined in your connection options).  Commands batched with multi/exec are traced individually, so you can measure individual performance within batch operations.  \n\nIf you're using redis@2.5.3 or earlier, turn on auto-tracing with the `IOPIPE_TRACE_REDIS_CB` environment variable set to true.  \n\n#### `autoIoRedis` Automatically trace Redis commands using ioredis\n\nSet the environment variable `IOPIPE_TRACE_IOREDIS` to `true`, and your function will enable automatic traces on Redis commands: the name of the command, name of the host, port, and connection (if defined in your connection options), and the key being written or read.  Commands batched with multi/exec are traced individually, so you can measure individual performance within batch operations.\n\n#### `autoMongoDb` Automatically trace MongoDB commands\n\nSet the environment variable `IOPIPE_TRACE_MONGODB` to `true`, and IOpipe will trace commands automatically: which command, which key is being read or written, database and collection name (if available), and the connection's hostname and port. This plugin supports these commands: \n \n* `command`, `insert`, `update`, and `remove` on the Server class\n* `connect`, `close`, and `db` on the MongoClient class.\n*  `find`, `findOne`, `insertOne`, `insertMany`, `updateOne`, `updateMany`, `replaceOne`, `deleteOne`, `deleteMany`, `createIndex` on collections. `bulkWrite` is also supported, and generates a list of which commands were part of the bulk operation.\n*  `next`, `filter`, `sort`, `hint`, and `toArray` on the Cursor class.\n\nCommands used with a callback parameter generate end traces and duration metrics. (Note that MongoDB commands that don't take callback params--like `find`--won't generate durations.) \n\nThis plugin supports MongoDB Node.JS Driver v3.3 and newer.  \n\n#### `autoMeasure` (bool: optional = true)\n\nBy default, the plugin will create auto-measurements for marks with matching `mark.start` and `mark.end`. These measurements will be displayed in the [IOpipe Dashboard](https://dashboard.iopipe.com). If you'd like to turn this off, set `autoMeasure: false`.\n\n```js\nconst iopipe = iopipeLib({\n  plugins: [tracePlugin({\n    autoMeasure: false\n  })]\n});\n```\n\n## Contributing\n- This project uses [Prettier](https://github.com/prettier/prettier). Please execute `npm run eslint -- --fix` to auto-format the code before submitting pull requests.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiopipe%2Fiopipe-js-trace","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiopipe%2Fiopipe-js-trace","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiopipe%2Fiopipe-js-trace/lists"}