• Log inStart now

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.js 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.js 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.js modules include:

Platform

Prerequisites

Unix/Linux

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

macOS

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

Windows

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.js 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.

bash
$
export NR_NATIVE_METRICS_NO_DOWNLOAD=true
bash
$
npm install @newrelic/native-metrics
bash
$
yarn add @newrelic/native-metrics

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

bash
$
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:

    bash
    $
    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.

      OR

    • 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.

bash
$
npm install newrelic --no-optional
bash
$
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.

bash
$
export NR_NATIVE_METRICS_NO_BUILD=true

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.

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

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

bash
$
npm install @newrelic/native-metrics
bash
$
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 & services > (select an app) > Node VMs. For more information, see the Node.js VMs statistics page.

The data is also available in metrics and events.

Measurement details

Tip

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

Copyright © 2022 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.