Node VM measurements

New Relic APM for Node.js collects key metric timeslice data from the Node virtual machine (V8). These metrics give you insight into Node VM behavior and help you improve your application's performance. The agent also collects CPU metrics, which are often analyzed together with garbage collection (GC) metrics.

Requirements and compatibility

New Relic requires an additional native module to collect Node VM metric timeslice data related to garbage collection, memory, and CPU. Note as of Node v6.1.0 the native module is not required to collect CPU metrics as the agent collects them via process.cpuUsage().

The native module can be used with:

  • New Relic Node.js version 1.35.1 or higher
  • Node v0.12, v0.12, v4 or higher
  • NPM v2.0.0 or higher

The native module must be compiled (see the node-gyp package) on your deployment platform. The following are prerequisites for installing native Node modules:

Platform Prerequisites
Unix/Linux Python (v2.7 recommended), make, C/C++ compiler (such as GCC)
Mac OS Python (v2.7 recommended), Xcode
Windows Python 2.7, Visual C++ Build Environment

If you have problems installing New Relic's Node.js agent, follow the installation troubleshooting procedures.

Install the native module

To install the native module:

  1. Ensure a supported version of Node is installed. Recommendation: Use the latest LTS version (currently v6). Do not use versions lower than the minimum supported version for the @newrelic/native-metrics module (0.12).
  2. To get all currently available metrics, ensure you're running agent (the newrelic module) 1.37.0 or higher.
  3. To install the native metrics module, use either of these methods:

    • Run the npm install @newrelic/native-metrics --save command.

      OR

    • Add the module to your app's package.json file.

  4. Restart your app.

The Node.js agent automatically detects that the native metrics module is installed and starts using it.

View Node VM data

To view Node VM metric timeslice data with New Relic Insights' Metric Explorer:

  1. From insights.newrelic.com, select Data Explorer > Metrics, then select the application you want to monitor.
  2. Select one of the available metrics.
nodejs-gc-metric-explorer.png
Insights > Data Explorer > Metrics: Here is an example of using the Insights Data Explorer to chart the average duration of garbage collection over time.

Measurement details

Not all data can be collected across all Node versions. In general, you will get the most complete data if you are on the most recent LTS version of Node.

Time in garbage collection

Available on: Agent v1.35.1 and higher; Node v0.12, v4 and higher; @newrelic/native-metrics v1.0.0 and higher

The amount of time spent in garbage collection (all types used by V8) by your Node process. Time is measured both as a cumulative metric, as GC/System/Pauses, and bucketed by garbage collection type as GC/<type>.

Possible garbage collection types include:

GC type Description
Scavenge The most common garbage collection method. Node will typically trigger one of these every time the VM is idle.
MarkSweepCompact The heaviest type of garbage collection V8 may do. If you see many of these happening you will need to either keep fewer objects around in your process or increase V8's heap limit.
IncrementalMarking A phased garbage collection that interleaves collection with application logic to reduce the amount of time the application is paused. Only in Node v6 or higher.
ProcessWeakCallbacks After a garbage collection occurs, V8 will call any weak reference callbacks registered for objects that have been freed. This measurement is from the start of the first weak callback to the end of the last for a given garbage collection. Only in Node v6 or higher.
Memory

Available on: Agent v1.36.0 and higher; Node v0.8, v0.10, v0.12, v4 and higher

The agent collects the following metrics related to memory usage:

Metric Description
Memory/Physical The total physical memory (in MB) used by the Node process. It is recorded using the process.memoryUsage().rss Node API.
Memory/Heap/Max The total heap (in MB) allocated by V8 for storing Javascript objects. It is recorded using the process.memoryUsage().heapTotal Node API.
Memory/Heap/Used The amount of V8 heap (in MB) currently used by the app. It is recorded using the process.memoryUsage().heapUsed Node API.
Memory/Heap/Free The amount of V8 memory (in MB) that is allocated but not used. This is a derived metric (heapTotal - heapUsed).
Memory/NonHeap/Used The amount of memory other than V8 heap (in MB). This is a derived metric (rss - heapTotal). This metric is useful for finding memory leaks outside of V8 heap, for example with buffers or streams.
CPU

Available on:

  • On Node >= v6.1.0, Agent v1.34.0 and higher
  • On Node v0.12 - v6.0.0, Agent v1.35.2 with @newrelic/native-metrics v1.0.0 and higher.

CPU metrics are collected on Node v6.1.0 and higher using the process.cpuUsage() Node API. For older versions of Node, the additional native module must be installed. For installation, see the Native module installation section.

The agent collects the following metrics related to CPU:

Metric Description
CPU/User Time The time spent by CPU executing the user code. It is recorded in seconds.
CPU/User/Utilization

The time spent executing the user code (CPU/User Time) divided by wall clock time and the number of logical processors.

Because the Node runtime always uses only one core, the max value reported by this metric will be 100 divided by the number of cores.

CPU/System Time The time spent by CPU in the system kernel in relation to the Node process.
CPU/System/Utilization

The time spent in the system kernel (CPU/System Time) divided by wall clock time and the number of logical processors.

Because the Node runtime always uses only one core, the max value reported by this metric will be 100 divided by number of cores.

Event Loop

Available on: Agent v1.37.0 and higher; @newrelic/native-metrics v2.1.0 and higher; Node v0.12, v4 and higher

Performance metrics for the Node event loop. Collection of event loop metrics requires the installation of an additional native module. For installation, see the Native module installation section.

The agent collects the following event loop metrics:

Metric Description
Nodejs/EventLoop/CPU/Usage

The total CPU time spent actively executing in each event loop tick. This includes executing your application's callbacks, but also the runtime itself. Reported in units of seconds.

An abnormally long event loop tick indicates unbroken synchronous execution that may be a target for optimization (e.g. recursive process.nextTick calls).

For more help

Additional documentation resources include:

Join the discussion about Node.js monitoring in the New Relic Online Technical Community! The Technical Community is a public platform to discuss and troubleshoot your New Relic toolset.

If you need additional help, get support at support.newrelic.com.