Get started with Express

Getting Opbeat set up for your Express 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.


$ 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 express, 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 express = require('express')
var app = express()

app.get('/', function (req, res) {
  res.send('Hello World!')

// any errors caught by Express can be logged by Opbeat as well


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 Express application and record any uncaught exceptions.

Note: must be added to the middleware stack before any other error handling middlewares or there’s a chance that the error will never get to Opbeat.

Express errors

Express works by funnelling all incoming http requests through a series of middleware (one of which being your router). If an error is either thrown synchronously inside one of the middleware functions or is passed as the first argument to the middleware next() function, it will be passed to the Express error handler.

It’s recommended that you register Opbeat as an Express error handler. In the case where you have multiple Express error handlers, the Opbeat error handler should be the first in the chain to ensure that it will receive the error correctly.

var opbeat = require('opbeat').start()
var express = require('express')

var app = express()

// Your regular middleware and router...

// Add the Opbeat middleware after your regular middleware

// ...but before any other error handler
app.use(function (err, req, res, next) {
  // Custom error handling goes here

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.

Ignore ‘404 Not Found’ errors

By default Express will treat http requests that do not match any route as an error. This is a good idea in development, but usually not something you want in production. To avoid sending “404 Not Found” errors to Opbeat, make sure you handle those before they reach the Opbeat middleware.

// Your regular middleware and router...

// Put a catch-all route handler as the very last route handler
app.use(function (req, res) {
  // If we reach this point it means that no prior route matched.
  // This means that we should render a "404 Not Found" page. Notice
  // that we do not call next() here as we don't want to forward the
  // request to the error handler below.

  // Send a 404 to the user
  res.status(404).send('This isn\'t the page you\'re looking for..')

// After the 404 Not Found handler, add the Opbeat error handler


See the Compatibility article for details.


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