--- title: Node.js VM measurements source: https://docs.newrelic.com/docs/apm/agents/nodejs-agent/extend-your-instrumentation/nodejs-vm-measurements --- New Relic's Node.js agent collects key [metric timeslice data](https://docs.newrelic.com/docs/data-analysis/metrics/analyze-your-metrics/data-collection-metric-timeslice-event-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 [#requirements] Some Node.js VM metrics are collected by default using built-in Node.js APIs, while others require the optional [`@newrelic/native-metrics`](https://www.npmjs.com/package/@newrelic/native-metrics) package: - **Default samplers (no native module required):** Memory (`Memory/*`), event loop queue wait time (`Events/wait`), and CPU (`CPU/*`) are always collected using `process.memoryUsage()`, `setTimeout` lag measurement, and `process.cpuUsage()` respectively. - **Native module samplers:** Garbage collection (`GC/*`) and precise event loop CPU usage (`Nodejs/EventLoop/CPU/Usage`) require `@newrelic/native-metrics`. If the module is not installed or fails to load, these metrics will not appear and the agent will continue running with default samplers only. 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](https://www.npmjs.com/package/node-gyp) 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](https://docs.newrelic.com/docs/agents/nodejs-agent/troubleshooting/troubleshooting-your-nodejs-installation) procedures. ## Install the native module [#install-modules] 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](https://docs.newrelic.com/docs/agents/nodejs-agent/installation-configuration/upgrade-nodejs-agent), 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](https://github.com/nodejs/node-gyp#option-2) 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 [#prebuilt-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 [#view-data] To view curated charts with Node.js VM data, go to **[one.newrelic.com > All capabilities](https://one.newrelic.com/all-capabilities) > APM & services > (select an app) > Node VMs**. For more information, see the [Node.js VMs statistics page](https://docs.newrelic.com/docs/agents/nodejs-agent/supported-features/node-vms-statistics-page). The data is also available in [metrics and events](https://docs.newrelic.com/docs/query-your-data/explore-query-data/data-explorer/introduction-data-explorer). ## Measurement details [#garbage] > #### 💡 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. **Time in garbage collection** > #### ⚠️ IMPORTANT > > Requires `@newrelic/native-metrics`. This metric is not collected by default. Available on: - Node.js agent v1.35.1 or higher - Node.js v4 or higher - New Relic Node.js `@newrelic/native-metrics` v1.0.0 or higher The amount of time spent in garbage collection (all types used by V8) by your Node.js process. Time is measured both as a cumulative metric, as `GC/System/Pauses`, and bucketed by garbage collection type as `GC/`. Possible garbage collection types include: | **GC type** | **Description** | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Scavenge` | The most common garbage collection method. Node.js 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.js 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.js v6 or higher. | **Memory** > #### 💡 TIP > > Collected by default. No native module required. Available on: - Node.js agent v1.36.0 or higher - Node.js v4 or higher The New Relic Node.js agent collects the following metrics related to memory usage: | **Metric** | **Description** | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Memory/Physical` | The total physical memory (in MB) used by the Node.js process. It is recorded using the `process.memoryUsage().rss` Node.js 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.js 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.js 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** > #### 💡 TIP > > Collected by default on Node.js v6.1.0 or higher. No native module required. Available on: - Node.js >= v6.1.0, Agent v1.34.0 or higher - Node.js v4 - v6.0.0, Agent v1.35.2 with `@newrelic/native-metrics` v1.0.0 or higher CPU metrics are collected on Node.js v6.1.0 or higher using the `process.cpuUsage()` Node.js API. For older versions of Node, the [additional native module must be installed](https://docs.newrelic.com/docs/agents/nodejs-agent/supported-features/node-vm-measurements#h2-Installation). 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.js 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.js 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.js runtime always uses only one core, the max value reported by this metric will be 100 divided by number of cores. | **Event Loop** > #### ⚠️ IMPORTANT > > Requires `@newrelic/native-metrics`. This metric is not collected by default. Available on: - Node.js agent v1.37.0 or higher - `@newrelic/native-metrics` v2.1.0 or higher - Node.js v4 or higher Performance metrics for the Node.js event loop. Collection of event loop metrics requires [installation of an additional native module](https://docs.newrelic.com/docs/agents/nodejs-agent/supported-features/node-vm-measurements#h2-Installation). 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; for example, recursive `process.nextTick` calls). |