Announcing Per-Request Custom Metadata for Node.js

Today we released v4.8.0 of the Opbeat Node.js Agent. It includes two new features that can help you when debugging performance issues and errors. Learn how to get the most out of them in this blog post.

Contextual user data example

As always, you can check the file in the root of our GitHub repository to see the important changes in each new release. Todays release have drastically improved your ability to add and get context to the collected performance metrics and errors on

User Context

When we released contextual information in Performance transactions we gave the Node.js agent the ability to automatically detect and report information about the active user to each transaction. With v4.8.0 this user data is now also added to errors.

We look for the active user on the HTTP request object by checking for common framework specific properties like user, auth or session. But if those properties don’t exist or doesn’t conform to the format we expect, you can easily tell the agent who the active user is using the new opbeat.setUserContext() function.

Say you have a middleware which loads the logged in user from your database. All you have to do now is simply call opbeat.setUserContext with the details:

  username: user.username,

Read the API documentation for more details.

Extra Context

Sometimes you need some extra information to be able to better debug an error or track down a performance bottleneck. With the new opbeat.setExtraContext() function this is now very easy to add.

Simply call opbeat.setExtraContext() at any point during the request/response life cycle with the metadata you want to associate with the request. We’ll make sure to collect and associate it with any errors that happen during the request and show it under the collected transaction in the Performance section on

  openDbSockets: db.pool.length

Read the API documentation for more details.

Filtering sensitive information

Though not technically part of this release, I thought it would be worth mentioning in this blog post that you can filter all the data that is being sent to in case you need to remove certain sensitive information. To do so, simply add a filtering function using opbeat.addFilter().

Read the API documentation for more details.

Upgrade now

To get these new features in your app, make sure you are running version 4.8.0 or higher of the Opbeat Node.js agent. If you still haven’t upgraded to version 4.x, simply follow our upgrade guide.

About the author
Thomas Watson is our Node.js lead, speaker and commited open source contributor.
You can follow him on Twitter or GitHub.