Opbeat is joining forces with Elastic – Learn more about Elastic APM

Get started with hapi

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

Watch a short screencast about how to get started with Opbeat in your Node.js app.


$ 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 hapi, http, etc.

This means that you should probably require and start it in your applications main file (usually index.js, server.js or app.js).

Here’s a simple hapi example with Opbeat installed:

// 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 Hapi = require('hapi')

var server = new Hapi.Server()

  host: 'localhost',
  port: 8000

  method: 'GET',
  path: '/hello',
  handler: function (request, reply) {
    return reply('hello world')


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

Advanced configuration

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.

Full documentation

Performance monitoring

Opbeat automatically measures the performance of your hapi application. It records traces for database queries, external HTTP requests and other slow operations that happens during requests to your hapi app.

By default Opbeat will trace the most common modules. To trace other events, you can use custom traces. For information about custom traces, see the Custom traces in Node.js article.

Traces are grouped in transactions - by default one for each incoming HTTP request. But it’s possible to create custom transactions not associated with an HTTP request. See the Custom transactions in Node.js article for details.

Unknown routes

When viewing the performance metrics of your application on Opbeat, you might see some transactions named “unknown route”. This indicates that the Opbeat agent detected an incomming HTTP request to your application, but didn’t know which route in your hapi app the HTTP request matched.

This might simply be 404 requests, which by design doesn’t match any route, or it might be a symptom that Opbeat wasn’t set up correctly. If you see this or can’t get any meaningful metrics to show up, please follow the Troubleshooting Guide.

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.

Filter sensitive information

By default the Opbeat agent will filter common sensitive information before sending errors and metrics to the Opbeat servers.

It’s possible for you to tweak these defaults or remove any information you don’t want to send to Opbeat:

  • By default the Opbeat agent will not log the body of sampled HTTP requests. To enable this, use the logBody config option

  • By default the Opbeat agent will filter certain HTTP headers known to contain sensitive information. To disable this, use the filterHttpHeaders config option

  • To apply custom filters, use the opbeat.addFilter() function

Add your own data

Opbeat will keep track of the active HTTP request and will link it to errors and recorded transaction metrics when they are sent to Opbeat. This allows you to see details about which request resulted in a particular error or which requests cause a certain HTTP endpoint to be slow.

But in many cases, information about the HTTP request it self isn’t enough. To add even more metadata to errors and transactions, use one of the two functions below:

  • opbeat.setUserContext() - Call this to enrich collected performance data and errors with information about the user/client

  • opbeat.setExtraContext() - Call this to enrich collected performance data and errors with any information that you think will help you debug performance issues and errors


See the Compatibility article for details.


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