AWS Lambda metrics, tracing, & analytics for Node.js
Clone or download
Latest commit 939e450 Nov 20, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci fix(promise rejection handling): Adding back in promise rejection han… Sep 10, 2018
.github Add issue template Mar 5, 2018
acceptance feat(labels): Add .metric and .label syntax Apr 4, 2018
src test(collision): Remove intermittently working collision test Nov 19, 2018
testProjects feat(Parameterize URL in geFileUploadMeta): Allow url param in getFil… Nov 15, 2018
util chore(lint): use iopipe-scripts for linting Mar 8, 2018
.babelrc Add regenerator (#174) Sep 13, 2017
.dockerignore Break up report.send() into prepare() and send() (#233) Mar 5, 2018
.gitignore feat(Parameterize URL in geFileUploadMeta): Allow url param in getFil… Nov 15, 2018
.mailmap Add mailcap file; add Erica Mar 28, 2017
.npmignore Integration test (#142) Jun 9, 2017
.npmrc-ci Circle 2 (#284) Aug 13, 2018
CONTRIBUTING.md docs(Contrib): Contributing.md addition Nov 16, 2018
Dockerfile Break up report.send() into prepare() and send() (#233) Mar 5, 2018
LICENSE Update LICENSE names & dates Mar 28, 2017
Makefile Break up report.send() into prepare() and send() (#233) Mar 5, 2018
README.md docs(README): Nov 20, 2018
docker-compose.yml Break up report.send() into prepare() and send() (#233) Mar 5, 2018
package.json fix(promise rejection handling): Adding back in promise rejection han… Sep 10, 2018
serverless.yml fix acceptance test by moving serverless up a dir (#188) Dec 6, 2017
webpack.config.js Whitelist babel requires for webpacking (#187) Dec 6, 2017
yarn.lock fix(unhandled promise rejection handling): Removing unhandled promise… Sep 4, 2018

README.md

IOpipe Agent for JavaScript


Coverage Status npm version styled with prettier semantic-release

IOpipe is a serverless DevOps platform for organizations building event-driven architectures in AWS 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.

Note: this library is a lower-level implementation than the package you might likely be looking for. Enjoy pre-bundled plugins like tracing and event info with @iopipe/iopipe

Installation

Install using your package manager of choice,

npm install @iopipe/core

or

yarn add @iopipe/core

If you are using the Serverless Framework to deploy your lambdas, check out our serverless plugin.

Usage

Configure the library with your project token (register for access), and it will automatically monitor and collect metrics from your applications running on AWS Lambda.

Example:

const iopipeLib = require('@iopipe/core');

const iopipe = iopipeLib({ token: 'PROJECT_TOKEN' });

exports.handler = iopipe((event, context) => {
  context.succeed('This is my serverless function!');
});

Custom metrics

You may add custom metrics to an invocation using context.iopipe.metric to add either string or numerical values. Keys have a maximum length of 256 characters, and string values are limited to 1024.

Example:

const iopipeLib = require('@iopipe/core');

const iopipe = iopipeLib({ token: 'PROJECT_TOKEN' });

exports.handler = iopipe((event, context) => {
  context.iopipe.metric('key', 'some-value');
  context.iopipe.metric('another-key', 42);
  context.succeed('This is my serverless function!');
});

Labels

You can label invocations using context.iopipe.label to label an invocation with a string value, with a limit of 128 characters.

Example:

const iopipeLib = require('@iopipe/core');

const iopipe = iopipeLib({ token: 'PROJECT_TOKEN' });

exports.handler = iopipe((event, context) => {
  context.iopipe.label('something-important-happened');
  context.succeed('This is my serverless function!');
});

Configuration

Methods

You 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).

  1. Module instantiation object
  2. IOPIPE_* environment variables
  3. An .iopiperc file
  4. An iopipe package.json entry
  5. An extends key referencing a config package
  6. Default values

Options

token (string: required)

If not supplied, the environment variable $IOPIPE_TOKEN will be used if present. Find your project token.

debug (bool: optional = false)

Debug 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.

const iopipe = require('@iopipe/core')({
  token: 'PROJECT_TOKEN',
  debug: true
});

exports.handler = iopipe((event, context, callback) => {
  // Do things here. We'll log info to STDOUT.
});

networkTimeout (int: optional = 5000)

The 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.

const iopipe = require('@iopipe/core')({ token: 'PROJECT_TOKEN', networkTimeout: 30000})

timeoutWindow (int: optional = 150)

By 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.

const iopipe = require('@iopipe/core')({ token: 'PROJECT_TOKEN', timeoutWindow: 0})

plugins (array: optional)

Note that if you use the @iopipe/iopipe package, 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:

Example:

const tracePlugin = require('@iopipe/trace');

const iopipe = require('@iopipe/core')({
  token: 'PROJECT_TOKEN',
  plugins: [tracePlugin()]
});

exports.handler = iopipe((event, context, callback) => {
  // Run your fn here
});

enabled (boolean: optional = True)

Conditionally enable/disable the agent. The environment variable $IOPIPE_ENABLED will also be checked.

RC File Configuration

Not recommended for webpack/bundlers due to dynamic require.

You can configure iopipe via an .iopiperc RC file. An example of that is here. 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:

  • String that is the name of the plugin
  • Or an array with plugin name first, and plugin options second
{
  "token": "wow_token",
  "plugins": [
    "@iopipe/trace",
    ["@iopipe/profiler", {"enabled": true}]
  ]
}

IMPORTANT: You must install the plugins as dependencies for them to load properly in your environment.

package.json Configuration

Not recommended for webpack/bundlers due to dynamic require.

You can configure iopipe within a iopipe package.json entry. An example of that is here. 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:

  • String that is the name of the plugin
  • Or an array with plugin name first, and plugin options second
{
  "name": "my-great-package",
  "dependencies": {
    "@iopipe/trace": "^0.2.0",
    "@iopipe/profiler": "^0.1.0"
  },
  "iopipe": {
    "token": "wow_token",
    "plugins": [
      "@iopipe/trace",
      ["@iopipe/profiler", {"enabled": true}]
    ]
  }
}

IMPORTANT: You must install the plugins as dependencies for them to load properly in your environment.

Extends Configuration

Not recommended for webpack/bundlers due to dynamic require.

You can configure iopipe within a package.json or rc file by referencing a extends config package. An example of that is here. 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:

  • String that is the name of the plugin
  • Or an array with plugin name first, and plugin options second

For an example of a config package, check out @iopipe/config.

IMPORTANT: You must install the config package and plugins as dependencies for them to load properly in your environment.

License

Apache 2.0