Instrumenting node.js with NewRelic

When working with node at scale it is imperative to have insight into your node processes: how much memory and CPU are in use, what your average throughput is, how long response times are, etc. Without this information you are completely in the dark when diagnosing problems in production. It’s easy enough to gather these statistics when working locally but local behavior is seldom helpful when you’re tasked with diagnosing performance problems in production. This is why instrumentation tools like NewRelic are important; they give you real time insight into how your application is behaving wherever you deployed it!

Tracking Web Requests

If your application serves web requests via express or similar you’re in luck, simply adding `require(‘newrelic’);` to the beginning of your main script and setting up the `newrelic.js` config file will enable request analytics (see the getting started documentation for specifics). In order to surface information about CPU and memory you will need to install the companion @newrelic/native-metrics module, but again there’s no special configuration that you need to begin gaining insights to your application.

Tracking Non-Web Requests

What if you want to track behavior that happens outside of a web request, or if your application serves no web requests? In that case you will need to take advantage of the NewRelic API to add tracking information to the routines you are interested in. That may sound a little daunting at first, and the documentation is admittedly not very clear about how to do this, but don’t abandon ship yet, we’ll walk through a simple example together.

First, you will need to locate the operation you wish to track. I suggest trying not to group too many transactions together if possible as this can make locating problems more difficult. After you have located the entry and exit points for the code you will need to wrap the transaction with the `newrelic.createBackgroundTransaction` method and end it with the `newrelic.endTransaction` method. All of the code that you wish to track must execute in the callback passed into `createBackgroundTransaction()` so you will need to take care with async code.

Here is a simple example of tracking a non-web transaction:

Note that regardless of whether the transaction ultimately succeeds or fails you must call `endTransaction()`, this is how NewRelic knows it can stop tracking your background work. You also need to take care while naming your transactions, too many names can cause problems in NewRelic and make tracing specific types of operations difficult. For this reason, the `createBackgroundTransaction()` method provides an optional `group` parameter so that transactions that are discrete but similar can be logically grouped together.

If all goes well, you’ll be able to dive into your non-web transactions with pretty graphs like these:

You will have greater insight into what is actually happening during runtime and can line up server statistics with log events to help isolate memory leaks or CPU spikes. Your applications will be more robust and easier to debug and your users (and support team) will be happier for it!