Get started with Koa

Getting Opbeat set up for your Koa app is easy, and there are various ways you can tweak it to fit to your needs.

Follow the guide below and refer to the API documentation for all the advanced stuff.

Koa doesn’t have a built in router, so we can’t support Koa directly since we rely on router information for full support. We currently support the most popular Koa router called koa-router.

If you use another router with your Koa application, please contact Support so we can make sure to support your stack. In the mean time you can configure Opbeat to work with any stack.


$ npm install opbeat --save


It’s important that the Opbeat agent is started before you require any other modules in your Node.js application - i.e. before koa, before http, even before Babel if you use that.

// add this to the VERY top of the first file loaded in your app
var opbeat = require('opbeat').start({
  appId: '<app id>',
  organizationId: '<org id>',
  secretToken: '<token>'

var app = require('koa')()
var router = require('koa-router')()

router.get('/', function *(next) {
  this.body = 'Hello World'



In the above example we initialize the agent by calling the start() function. This function takes an optional options object used to configure the agent. Any option not supplied via the options object can instead be configured using environment variables. So if you prefer, you can set the following three environment variables:

OPBEAT_APP_ID=<app id>

And then just start the agent like so:

// Start the Opbeat agent before any thing else in your app
var opbeat = require('opbeat').start()

See all possible configuration options in the API documentation.

The Opbeat agent will now monitor the performance of your Koa application and record any uncaught exceptions.

Manual error logging

By default the Opbeat agent will watch for uncaught exceptions and send them to Opbeat automatically. But in most cases errors are not thrown but returned via a callback, caught by a promise or simply manually created. Those errors will not automatically be sent to Opbeat. To manually send an error to Opbeat, simply call opbeat.captureError():

var err = new Error('Ups, something broke!')


For advanced logging of errors, including adding extra meta-data to the error, see the API documentation.


See the Compatibility article for details.


If you can’t get the Opbeat agent to work as expected, please follow the Troubleshooting Guide.