• /
  • Log in
  • Free account

Node.js VM measurements

New Relic's Node.js agent collects key metric timeslice data from the Node.js virtual machine (V8). These metrics give you insight into Node.js 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.

What you need

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

The native module can be used with:

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

To compile the native module on your deployment platform, follow the node-gyp package procedures. Prerequisites to install native Node modules include:




Python (v2.7 recommended, v3.x.x not supported), make, C/C++ compiler (such as GCC)


Python (v2.7 recommended, v3.x.x not supported), Xcode


Python (v2.7 recommended, v3.x.x not supported), Visual C++ Build Environment

If you have problems installing our Node.js agent, follow the installation troubleshooting procedures.

Install the native module

As of v2.0.0 of the New Relic Node.js agent, the native module has become an optional dependency that attempts to install automatically.

During installation, the native module first attempts to build from source on the target machine. If the build fails, Node outputs a stack trace to the console that you can typically ignore. For Linux environments running supported versions of Node, the agent then attempts to download and install a pre-built binary.

It is possible to prevent the agent from attempting to download and install a pre-built binary. Instead, it will only attempt to build the native module. Do this by setting the NR_NATIVE_METRICS_NO_DOWNLOAD environment variable to true before installation with either NPM or Yarn.

npm install @newrelic/native-metrics
yarn add @newrelic/native-metrics

Alternatively, use the --no-download flag which works with NPM.

npm install @newrelic/native-metrics --no-download

If the build fails with NR_NATIVE_METRICS_NO_DOWNLOAD=true or the --no-download flag set, the optional native module will not be installed.

If both environment variables are set, NR_NATIVE_METRICS_NO_BUILD will override NR_NATIVE_METRICS_NO_DOWNLOAD.

If you're using an older version, upgrade to the latest agent version, or install the native module manually:

  1. Ensure a supported version of Node.js is installed. Recommendation: Use the latest LTS version. Do not use versions lower than the minimum supported version for the @newrelic/native-metrics module (v4 or higher).

  2. To get all currently available metrics, ensure you are running the newrelic module for agent 1.37.0 or higher.

  3. Windows users: Run the following command:

    npm install --global windows-build-tools

    If this step doesn't work, follow Option 2 in the node-gyp module on GitHub for manual installation instructions.

  4. To install the native metrics module, use either of these methods:

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


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

  5. Restart your app.

The Node.js agent automatically detects if the native metrics module is installed and starts using it. If you'd like to avoid installation of the native module completely, you can use the following NPM or Yarn arguments.

npm install newrelic --no-optional
yarn add newrelic --ignore-optional

Pre-built binaries

To skip the build step and only attempt to download a pre-built binary, and to avoid seeing build errors in the console, set the NR_NATIVE_METRICS_NO_BUILD environment variable to true before installation.


If working behind a firewall, you can cache pre-built binaries by setting the NR_NATIVE_METRICS_DOWNLOAD_HOST and NR_NATIVE_METRICS_REMOTE_PATH environment variables before installation.

export NR_NATIVE_METRICS_DOWNLOAD_HOST=http://your-internal-cache/
export NR_NATIVE_METRICS_REMOTE_PATH=path/to/download/folder/

Once you've set environment variables, installation can then proceed.

npm install @newrelic/native-metrics
yarn add @newrelic/native-metrics

View Node.js VM data

To view curated charts with Node.js VM data, go to one.newrelic.com > APM > (select an app) > Node VMs. For more information, see the Node.js VMs statistics page.

The data is also available in the data explorer: To access the data explorer, go to one.newrelic.com and at the top of the page, click the Query your data icon.

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.

For more help

If you need more help, check out these support and learning resources:

Create issueEdit page
Copyright © 2021 New Relic Inc.