AWS Lambda

BugSnag can automatically report unhandled errors and capture useful metadata in AWS Lambda functions.

This documentation is for version 7+ of the BugSnag JavaScript notifier. If you are using older versions, we recommend upgrading to the latest release using our Upgrade guide. Documentation for the previous release can be found on our legacy pages.

Installation

Install and configure @bugsnag/js, then install the AWS Lambda plugin using npm or yarn:

yarn add @bugsnag/plugin-aws-lambda
# or
npm install --save @bugsnag/plugin-aws-lambda

Usage

To start BugSnag with the AWS Lambda integration, pass the plugin to Bugsnag.start along with the Koa plugin:

const Bugsnag = require('@bugsnag/js')
const BugsnagPluginAwsLambda = require('@bugsnag/plugin-aws-lambda')
const BugsnagPluginKoa = require('@bugsnag/plugin-koa')

Bugsnag.start({
  apiKey: 'YOUR_API_KEY',
  plugins: [BugsnagPluginAwsLambda, BugsnagPluginKoa],
  otherOptions: value
})

In the part of your application where the Koa server is configured, obtain and use the Koa middleware:

const app = new Koa()
const middleware = Bugsnag.getPlugin('koa')

// This must be the first piece of middleware in the stack.
// It can only capture errors in downstream middleware
app.use(middleware.requestHandler)

/* all other middleware and application routes go here */

// This handles any errors that Koa catches
app.on('error', middleware.errorHandler)

Finally, start handling errors in your Lambda function by wrapping your application with BugSnag’s handler. For example, using the serverless-http library:

const serverless = require('serverless-http')

const bugsnagHandler = Bugsnag.getPlugin('awsLambda').createHandler()

exports.handler = bugsnagHandler(serverless(app))

BugSnag should always be the outermost handler in your application to ensure all errors are captured.

Automatically captured data

BugSnag will automatically capture the Lambda function’s context in the “AWS Lambda Context” tab on every error.

You can remove individual items from context using redactedKeys:

Bugsnag.start({
  redactedKeys: ['invokedFunctionArn']
})

You can also remove the tab entirely:

Bugsnag.clearMetadata('AWS Lambda context')

Session tracking

A session will be reported automatically each time your Lambda function is called.

This behavior can be disabled using the autoTrackSessions configuration option.

Configuration

The BugSnag AWS Lambda plugin can be configured by passing options to createHandler.

flushTimeoutMs

BugSnag will wait for events and sessions to be delivered before allowing the Lambda function to exit. This option can be used to control the maximum amount of time to wait before timing out.

By default, BugSnag will timeout after 2000 milliseconds.

const bugsnagHandler = Bugsnag.getPlugin('awsLambda').createHandler({
  flushTimeoutMs: 5000
})

If a timeout does occur, BugSnag will log a warning and events & sessions may not be delivered.

lambdaTimeoutNotifyMs

BugSnag will send a handled event to your dashboard to notify you of timeouts in a Lambda function, just before a timeout occurs. This option can be used to control the number of milliseconds before a timeout that BugSnag should be notified.

By default, BugSnag will notify 1000 milliseconds before the Lambda timeout.

const bugsnagHandler = Bugsnag.getPlugin('awsLambda').createHandler({
  lambdaTimeoutNotifyMs: 2000
})

Set this value to 0 to disable the automatic notification.

If this value is too low, BugSnag may not be notified of timeouts because the Lambda function could be stopped before the notification is delivered.