Koa integration guide

Add Bugsnag to your Koa applications.

Installation

Install Bugsnag using npm:

npm install bugsnag --save

NOTE: When executing coffeecript code directly using the coffee executable, Bugsnag cannot notify about uncaught exceptions that occur at the top level of your app. This is due to a design decision for the coffee executable.

To avoid this issue, make sure to compile your coffeescript files into JavaScript before running your app.

Basic configuration

1. Require Bugsnag in your app

bugsnag = require("bugsnag")

2. Register the Bugsnag notifier with your API key

bugsnag.register("your-api-key-here")

3. Add the Koa handler

app.on("error", bugsnag.koaHandler)

Reporting unhandled errors

Capturing Asynchronous Errors

Bugsnag can automatically capture both synchronous and asynchronous errors in your code if you wrap it in an autoNotify function.

Note: If you are using the bugsnag.requestHandler middleware for Express or Connect, we automatically wrap your requests with autoNotify.

coffeescript bugsnag.autoNotify(() -> # Your code here ) `

Additionally, you can pass options into autoNotify that will be used as default options for the notify call to any errors. See reporting handled errors for available options.

bugsnag.autoNotify({ context: "thisContext" }, () ->
  # Your code here
)

The autoNotify function creates a Node.js Domain which automatically routes all uncaught errors to Bugsnag.

Capturing Errors in Callback Functions

Many callback functions in Node are called with an error as the first argument. Bugsnag can intercept these errors if you wrap your callback with bugsnag.intercept:

functionWithCallback(bugsnag.intercept((argument) ->
  # Your code here
))

If the first argument is non-null, Bugsnag will be automatically notified of the error, and your callback will not be executed. The first argument is never passed to your callback, since it is assumed to be the error argument.

Using Promises

If you’re using a promises library such as Bluebird or when.js, you can listen to unhandled promise rejections. See this document for more details.

process.on('unhandledRejection', (err, promise) ->
    console.error("Unhandled rejection: " + (err && err.stack || err))
    bugsnag.notify(err)
)

Reporting handled errors

To send non-fatal exceptions to Bugsnag, you can pass any Error object or string to the notify method:

bugsnag.notify(new Error("Non-fatal"))

When reporting handled exceptions, it’s often helpful to send us custom diagnostic data or to adjust the severity of particular errors. For more information, see reporting handled errors.

Sending diagnostic data

Bugsnag will automatically capture a full stack trace for every exception. It is often helpful to send us additional application-specific diagnostic data. This will be displayed as additional tabs in the error dashboard.

All errors

You can apply additional metadata for all errors by adding it to the notification in the onBeforeNotify callback:

bugsnag.onBeforeNotify((notification) ->

    metaData = notification.events[0].metaData

    # modify meta-data
    metaData.subsystem = { name: "Your subsystem name" }
)

For more information, see customizing error reports.

Individual errors

You can send additional metadata with an individual error by supplying it as part of the options to the notify call:

bugsnag.notify(new Error("Something went badly wrong"), {
  subsystem: {
    name: "Your subsystem name"
  }
})

For more information, see reporting handled errors.

Identifying users

In order to correlate errors with customer reports, or to see a list of users who experienced each error, it is helpful to capture and display user information on your Bugsnag dashboard.

The user id can also be set using the userId property in a notify call or onBeforeNotify callback:

bugsnag.notify(new Error("Something went badly wrong"), { userId: "bob-hoskins" })

Additional user data can also be added by setting a user metadata field:

bugsnag.notify(new Error("Something went badly wrong"), {
  user: {
    id: "bob-hoskins",
    name: "Bob Hoskins",
    email: "bob@example.com"
  }
})

Note: For Express/Connect apps we automatically set the user id to the ip address of the current request.

User data can also be set on a per-request basis using the requestData property. See customizing error reports for details

Next steps