katiebayes/iopipe-js

Build and run serverless apps with confidence on AWS Lambda with Tracing, Profiling, Metrics, Monitoring, and more.

✨Special Announcement: We've Joined New Relic Serverless! Get ready to function faster with full visibility into your serverless applications—and everything else. Read our founders' note to learn more.

IOpipe Agent & Bundled Plugins

This package provides the IOpipe agent and plugins pre-bundled.

Installation & usage

Install via npm:

npm install --save @iopipe/iopipe

Or via yarn:

yarn add @iopipe/iopipe

Then require this module, passing it an object with your project token (get a free account), and it will automatically monitor and collect metrics from your applications running on AWS Lambda.

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

Example:

const iopipe = require('@iopipe/iopipe')({ token: 'PROJECT_TOKEN' });

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

By default this package will enable @iopipe/trace and @iopipe/event-info plugins. It also includes the @iopipe/profiler plugin, which is disabled by default. For more information on how to use IOpipe and these plugins, see the documentation below:

• IOpipe Documentation
• IOpipe Tracing Plugin Documentation
• IOpipe Event Info Plugin Documentation
• IOpipe Profiler Plugin Documentation

Example With Tracing, Custom Metrics, and Labels (ES6 Module Format):

import iopipe, {mark, metric, label} from '@iopipe/iopipe';

exports.handler = iopipe()(async (event, context) => {
  // add a trace measurement for the database call
  mark.start('db-call');
  // fetch some data from the database
  const rows = await sql(`select * from dogs where status = 'goodboy'`);
  mark.end('db-call');

  // add a custom metric for IOpipe search and alerts
  metric('rows-from-db', rows.length);

  // add a label to this invocation for easy filter/sort on dashboard.iopipe.com
  label('used-db-cache');

  context.succeed('This is my serverless function!');
});

Lambda Layers

IOpipe publishes AWS Lambda Layers which are publicly available on AWS. Using a framework that supports lambda layers (such as SAM or Serverless), you can use the following ARNs for your runtime:

• nodejs10.x: arn:aws:lambda:$REGION:146318645305:layer:IOpipeNodeJS10:$VERSION_NUMBER
• nodejs8.10: arn:aws:lambda:$REGION:146318645305:layer:IOpipeNodeJS810:$VERSION_NUMBER

Where $REGION is your AWS region and $VERSION_NUMBER is an integer representing the IOpipe release. You can get the version number via the Releases page.

Then in your SAM template (for example), you can add:

Globals:
  Function:
    Layers:
        - arn:aws:lambda:us-east-1:146318645305:layer:IOpipeNodeJS810:1

And the IOpipe library will be included in your function automatically.

You can also wrap your IOpipe functions without a code change using layers. For example, in your SAM template you can do the following:

Resources:
  YourFunctionHere:
    Type: 'AWS::Serverless::Function'
    Properties:
      CodeUri: path/to/your/code
      # Automatically wraps the handler with IOpipe
      Handler: @iopipe/iopipe.handler
      Runtime: nodejs8.10
      Environment:
        Variables:
          # Specifies which handler IOpipe should run
          IOPIPE_HANDLER: path/to/your.handler

Or with the Serverless framework:

functions:
  your-function-here:
    environment:
        IOPIPE_HANDLER: path/to/your.handler
    handler: @iopipe/iopipe.handler
    layers:
      - arn:aws:lambda:us-east-1:146318645305:layer:IOpipeNodeJS810:1
    runtime: nodejs8.10

Troubleshooting

Lambda layers: Lambda can't find the file @iopipe/iopipe.js

If you're seeing this error, it's likely that the node runtime isn't resolving NPM_PATH for the @iopipe/iopipe module in /opt/nodejs/node_modules.

These steps should fix the problem:

1. Create an iopipe_wrapper.js script in your project's root.
2. The script's contents should be module.exports = require('@iopipe/iopipe');. (And that's all that needs to be in it.)
3. Update the handler for your layer declaration to iopipe_wrapper.handler.

License

Apache 2.0