Menu

Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.

Open source

Node.js

Enhance your Node.js application’s performance with our Node.js Profiler. Seamlessly integrated with Pyroscope, it provides real-time insights into your application’s operation, helping you identify and resolve performance bottlenecks. This integration is key for Node.js developers aiming to boost efficiency, reduce latency, and maintain optimal application performance.

Note

Refer to Available profiling types for a list of profile types supported by each language.

Before you begin

To capture and analyze profiling data, you need either a hosted Pyroscope OSS server or a hosted Pyroscope instance with Grafana Cloud Profiles (requires a free Grafana Cloud account).

The Pyroscope server can be a local server for development or a remote server for production use.

Add Node.js profiling to your application

To start profiling a Node.js application, you need to include the npm module in your app:

npm install @pyroscope/nodejs

# or
yarn add @pyroscope/nodejs

Configure the Node.js client

Add the following code to your application:

JavaScript
const Pyroscope = require('@pyroscope/nodejs');

Pyroscope.init({
  serverAddress: 'http://pyroscope:4040',
  appName: 'myNodeService'
});

Pyroscope.start()

Note

If you’d prefer, you can use Pull mode using Grafana Alloy (recommended) or Grafana Agent (legacy).

Configuration options

Init parameterENVIRONMENT VARIABLETypeDESCRIPTION
`appName:PYROSCOPE_APPLICATION_NAMEStringSets the service_name label
serverAddress:PYROSCOPE_SERVER_ADDRESSStringURL of the Pyroscope Server
basicAuthUser:n/aStringUsername for basic auth / Grafana Cloud stack user ID (Default "")
basicAuthPassword:n/aStringPassword for basic auth / Grafana Cloud API key (Default "")
flushIntervalMs:PYROSCOPE_FLUSH_INTERVAL_MSNumberInterval when profiles are sent to the server (Default 60000)
heapSamplingIntervalBytesPYROSCOPE_HEAP_SAMPLING_INTERVAL_BYTESNumberAverage number of bytes between samples. (Default 524288)
heapStackDepth:PYROSCOPE_HEAP_STACK_DEPTHNumberMaximum stack depth for heap samples (Default 64)
wallSamplingDurationMs:PYROSCOPE_WALL_SAMPLING_DURATION_MSNumberDuration of a single wall profile (Default 60000)
wallSamplingIntervalMicros:PYROSCOPE_WALL_SAMPLING_INTERVAL_MICROSNumberInterval of how often wall samples are collected (Default 10000
wallCollectCpuTime:PYROSCOPE_WALL_COLLECT_CPU_TIMEBooleanEnable CPU time collection for wall profiles (Default false)
tags:n/aLabelSetStatic labels applying to all profiles collected (Default {})
sourceMapper:n/aSourceMapperProvide source file mapping information (Default undefined)

Add profiling labels to Node.js applications

Static labels

You can add static labels to the profiling data. These labels can be used to filter the data in the UI and apply for all profiles collected. Common static labels include:

  • hostname
  • region
  • team
JavaScript
Pyroscope.init({
  serverAddress: 'http://pyroscope:4040',
  appName: 'myNodeService',
  tags: {
    region: ENV['region']
  },
});

Pyroscope.start()

Dynamic labels for Wall/CPU profiles

In Wall/CPU profiles, labels can also be attached dynamically and help to separate different code paths:

JavaScript
Pyroscope.wrapWithLabels({ vehicle: 'bike' }, () =>
  slowCode()
);

Send data to Pyroscope OSS or Grafana Cloud

JavaScript
Pyroscope.init({
  serverAddress: 'http://pyroscope:4040',
  appName: 'myNodeService',
  tags: {
    region: ENV['region']
  },
  basicAuthUser: ENV['PYROSCOPE_BASIC_AUTH_USER'],
  basicAuthPassword: ENV['PYROSCOPE_BASIC_AUTH_PASSWORD'],
  // Optional Pyroscope tenant ID (only needed if using multi-tenancy). Not needed for Grafana Cloud.
  // tenantID: ENV['PYROSCOPE_TENANT_ID'],
});

Pyroscope.start()

To configure the Node.js SDK to send data to Pyroscope, replace the serverAddress placeholder with the appropriate server URL. This could be the Grafana Cloud Pyroscope URL or your own custom Pyroscope server URL.

If you need to send data to Grafana Cloud, you’ll have to configure HTTP Basic authentication. Replace basicAuthUser with your Grafana Cloud stack user ID and basicAuthPassword with your Grafana Cloud API key.

If your Pyroscope server has multi-tenancy enabled, you’ll need to configure a tenant ID. Replace tenantID with your Pyroscope tenant ID.

Troubleshoot

Setting DEBUG env to pyroscope provides additional debugging information.

bash
DEBUG=pyroscope node index.js