{"id":22886361,"url":"https://github.com/iopipe/iopipe-js-core","last_synced_at":"2025-05-07T10:28:45.442Z","repository":{"id":6577204,"uuid":"55360643","full_name":"iopipe/iopipe-js-core","owner":"iopipe","description":"Observe and develop serverless apps with confidence on AWS Lambda with Tracing, Metrics, Profiling, Monitoring, and more.","archived":false,"fork":false,"pushed_at":"2022-12-30T17:42:00.000Z","size":3150,"stargazers_count":124,"open_issues_count":39,"forks_count":20,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-11-28T13:48:53.257Z","etag":null,"topics":["analytics","aws","aws-lambda","debugging","devops","iopipe","iopipe-agent","javascript","lambda","monitoring","profiling","serverless"],"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":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-04-03T17:59:28.000Z","updated_at":"2024-05-31T08:21:54.000Z","dependencies_parsed_at":"2023-01-13T15:30:51.480Z","dependency_job_id":null,"html_url":"https://github.com/iopipe/iopipe-js-core","commit_stats":null,"previous_names":["iopipe/iopipe"],"tags_count":54,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iopipe%2Fiopipe-js-core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iopipe%2Fiopipe-js-core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iopipe%2Fiopipe-js-core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iopipe%2Fiopipe-js-core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iopipe","download_url":"https://codeload.github.com/iopipe/iopipe-js-core/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":229608648,"owners_count":18098051,"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":["analytics","aws","aws-lambda","debugging","devops","iopipe","iopipe-agent","javascript","lambda","monitoring","profiling","serverless"],"created_at":"2024-12-13T20:17:56.651Z","updated_at":"2024-12-13T20:17:57.325Z","avatar_url":"https://github.com/iopipe.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# IOpipe Agent for JavaScript\n--------------------------------------------\n[![Coverage Status](https://coveralls.io/repos/github/iopipe/iopipe/badge.svg?branch=master)](https://coveralls.io/github/iopipe/iopipe?branch=master)\n[![npm version](https://badge.fury.io/js/%40iopipe%2Fcore.svg)](https://badge.fury.io/js/%40iopipe%2Fcore)\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\n[IOpipe](https://iopipe.com) is a serverless DevOps platform for organizations building event-driven architectures in [AWS Lambda](https://aws.amazon.com/lambda/). IOpipe captures crucial, high-fidelity metrics for each Lambda function invocation. This data powers a flexibile and robust development and operations experience with features including tracing, profiling, custom metrics, and low-latency alerts. Get started today to quickly and confidently gain superior observability, identify issues, and discover anomalies in your connected applications.\n\n- [Installation](#installation)\n- [Usage](#usage)\n  - [Custom Metrics](#custom-metrics)\n  - [Labels](#labels)\n- [Configuration](#configuration)\n  - [Methods](#methods)\n  - [Options](#options)\n\n__Note: this library is a lower-level implementation than the package [you might likely be looking for](https://github.com/iopipe/iopipe-js). Enjoy pre-bundled plugins like tracing and event info with [`@iopipe/iopipe`](https://github.com/iopipe/iopipe-js)__\n\n# Installation\n\nInstall using your package manager of choice,\n\n`npm install @iopipe/core`\n\nor\n\n`yarn add @iopipe/core`\n\nIf you are using the Serverless Framework to deploy your lambdas, check out our [serverless plugin](https://github.com/iopipe/serverless-plugin-iopipe).\n\n# Usage\n\nConfigure the library with your project token ([register for access](https://www.iopipe.com)), and it will automatically monitor and collect metrics from your applications running on AWS Lambda.\n\nExample:\n\n```js\nconst iopipeLib = require('@iopipe/core');\n\nconst iopipe = iopipeLib({ token: 'PROJECT_TOKEN' });\n\nexports.handler = iopipe((event, context) =\u003e {\n  context.succeed('This is my serverless function!');\n});\n```\n\n## Custom metrics\n\nYou may add custom metrics to an invocation using `context.iopipe.metric` to add\neither string or numerical values. Keys have a maximum length of 256 characters, and string values are limited\nto 1024.\n\nExample:\n\n```js\nconst iopipeLib = require('@iopipe/core');\n\nconst iopipe = iopipeLib({ token: 'PROJECT_TOKEN' });\n\nexports.handler = iopipe((event, context) =\u003e {\n  context.iopipe.metric('key', 'some-value');\n  context.iopipe.metric('another-key', 42);\n  context.succeed('This is my serverless function!');\n});\n```\n\n## Labels\n\nYou can label invocations using `context.iopipe.label` to label an invocation with a string value, with a limit of 128 characters.\n\nExample:\n\n```js\nconst iopipeLib = require('@iopipe/core');\n\nconst iopipe = iopipeLib({ token: 'PROJECT_TOKEN' });\n\nexports.handler = iopipe((event, context) =\u003e {\n  context.iopipe.label('something-important-happened');\n  context.succeed('This is my serverless function!');\n});\n```\n\n# Configuration\n\n## Methods\n\nYou can configure your iopipe setup through one or more different methods - that can be mixed, providing a config chain. The current methods are listed below, in order of precendence. The module instantiation object overrides all other config values (if values are provided).\n\n1. Module instantiation object\n2. `IOPIPE_*` environment variables\n3. [An `.iopiperc` file](#rc-file-configuration)\n4. [An `iopipe` package.json entry](#packagejson-configuration)\n5. [An `extends` key referencing a config package](#extends-configuration)\n6. Default values\n\n## Options\n\n#### `token` (string: required)\n\nIf not supplied, the environment variable `$IOPIPE_TOKEN` will be used if present. [Find your project token](https://dashboard.iopipe.com/install).\n\n#### `debug` (bool: optional = false)\n\nDebug mode will log all data sent to IOpipe servers to STDOUT. This is also a good way to evaluate the sort of data that IOpipe is receiving from your application. If not supplied, the environment variable `$IOPIPE_DEBUG` will be used if present.\n\n```js\nconst iopipe = require('@iopipe/core')({\n  token: 'PROJECT_TOKEN',\n  debug: true\n});\n\nexports.handler = iopipe((event, context, callback) =\u003e {\n  // Do things here. We'll log info to STDOUT.\n});\n```\n\n#### `networkTimeout` (int: optional = 5000)\n\nThe number of milliseconds IOpipe will wait while sending a report before timing out. If not supplied, the environment variable `$IOPIPE_NETWORK_TIMEOUT` will be used if present.\n\n```js\nconst iopipe = require('@iopipe/core')({ token: 'PROJECT_TOKEN', networkTimeout: 30000})\n```\n\n#### `timeoutWindow` (int: optional = 150)\n\nBy default, IOpipe will capture timeouts by exiting your function 150ms early from the AWS configured timeout, to allow time for reporting. You can disable this feature by setting `timeoutWindow` to `0` in your configuration. If not supplied, the environment variable `$IOPIPE_TIMEOUT_WINDOW` will be used if present.\n\n```js\nconst iopipe = require('@iopipe/core')({ token: 'PROJECT_TOKEN', timeoutWindow: 0})\n```\n\n#### `plugins` (array: optional)\n\n_Note that [if you use the `@iopipe/iopipe` package](https://github.com/iopipe/iopipe-js), you get our recommended plugin set-up right away._ Plugins can extend the functionality of IOpipe in ways that best work for you. Follow the guides for the plugins listed below for proper installation and usage on the `@iopipe/core` library:\n\n- [Event Info Plugin](https://github.com/iopipe/iopipe-plugin-event-info)\n- [Trace Plugin](https://github.com/iopipe/iopipe-plugin-trace)\n- [Logger Plugin](https://github.com/iopipe/iopipe-plugin-logger)\n- [Profiler Plugin](https://github.com/iopipe/iopipe-plugin-profiler)\n\nExample:\n\n```js\nconst tracePlugin = require('@iopipe/trace');\n\nconst iopipe = require('@iopipe/core')({\n  token: 'PROJECT_TOKEN',\n  plugins: [tracePlugin()]\n});\n\nexports.handler = iopipe((event, context, callback) =\u003e {\n  // Run your fn here\n});\n```\n\n#### `enabled` (boolean: optional = True)\n\nConditionally enable/disable the agent. The environment variable `$IOPIPE_ENABLED` will also be checked.\n\n#### `url` (string: optional)\n\nSets an alternative URL to use for the IOpipe collector. The environment variable `$IOPIPE_COLLECTOR_URL` will be used if present.\n\n## RC File Configuration\nNot recommended for webpack/bundlers due to dynamic require.\n\nYou can configure iopipe via an `.iopiperc` RC file. [An example of that is here](https://github.com/iopipe/iopipe-js-core/blob/master/testProjects/rcFileConfig/.iopiperc). Config options are the same as the module instantiation object, except for plugins. Plugins should be an array containing mixed-type values. A plugin value can be a:\n- String that is the name of the plugin\n- Or an array with plugin name first, and plugin options second\n\n```json\n{\n  \"token\": \"wow_token\",\n  \"plugins\": [\n    \"@iopipe/trace\",\n    [\"@iopipe/profiler\", {\"enabled\": true}]\n  ]\n}\n```\n\n**IMPORTANT**: You must install the plugins as dependencies for them to load properly in your environment.\n\n## package.json Configuration\nNot recommended for webpack/bundlers due to dynamic require.\n\nYou can configure iopipe within a `iopipe` package.json entry. [An example of that is here](https://github.com/iopipe/iopipe/blob/master/testProjects/packageJsonConfig/package.json#L10). Config options are the same as the module instantiation object, except for plugins. Plugins should be an array containing mixed-type values. A plugin value can be a:\n- String that is the name of the plugin\n- Or an array with plugin name first, and plugin options second\n\n```json\n{\n  \"name\": \"my-great-package\",\n  \"dependencies\": {\n    \"@iopipe/trace\": \"^0.2.0\",\n    \"@iopipe/profiler\": \"^0.1.0\"\n  },\n  \"iopipe\": {\n    \"token\": \"wow_token\",\n    \"plugins\": [\n      \"@iopipe/trace\",\n      [\"@iopipe/profiler\", {\"enabled\": true}]\n    ]\n  }\n}\n```\n\n**IMPORTANT**: You must install the plugins as dependencies for them to load properly in your environment.\n\n## Extends Configuration\nNot recommended for webpack/bundlers due to dynamic require.\n\nYou can configure iopipe within a package.json or rc file by referencing a `extends` config package. [An example of that is here](https://github.com/iopipe/iopipe-js-core/blob/master/testProjects/extendConfig/package.json#L15). Config options are the same as the module instantiation object, except for plugins. Plugins should be an array containing mixed-type values. A plugin value can be a:\n- String that is the name of the plugin\n- Or an array with plugin name first, and plugin options second\n\nFor an example of a config package, check out [@iopipe/config](https://github.com/iopipe/iopipe-js-config).\n\n**IMPORTANT**: You must install the config package and plugins as dependencies for them to load properly in your environment.\n\n# License\n\nApache 2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiopipe%2Fiopipe-js-core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiopipe%2Fiopipe-js-core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiopipe%2Fiopipe-js-core/lists"}