Skip to main content


Node.js is an open-source, cross-platform, back-end JavaScript runtime environment that runs on the V8 engine and executes JavaScript code outside a web browser. Pyroscope use internal V8 profiler to collect profiling data

Supported platforms#

Spy NameTypeLinuxmacOSWindowsDocker

Profiling NodeJS application#


This current version of the NodeJS integration requires you to run pyroscope server version 0.15.4 or higher.

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

npm install @pyroscope/nodejs
# oryarn add @pyroscope/nodejs

Then add the following code to your application:

const Pyroscope = require('@pyroscope/nodejs');
Pyroscope.init({  serverAddress: 'http://pyroscope:4040',  appName: 'myNodeService'});


It is possible to add tags (labels) to the profiling data. These tags can be used to filter the data in the UI. Dynamic tagging isn't supported yet

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


You may set DEBUG env to pyroscope and see debugging information which can help you understand if everything is OK.

DEBUG=pyroscope node index.js

Pull Mode#

NodeJS integration also supports pull mode. For that to work you will need to make sure you have profiling routes (/debug/pprof/profile and /debug/pprof/heap) enabled in your http server. For that you may use our expressMiddleware or create endpoints yourself

const Pyroscope, { expressMiddleware } = require('@pyroscope/nodejs');

Note: you don't need to .start() but you'll need to .init()

Scrape configuration#

You will need to add the following content to your pyroscope/server.yml Pyroscope config file. See the Server config documentation for more information on where this config is located by default on your system.

---# A list of scrape configurations.scrape-configs:  # The job name assigned to scraped profiles by default.  - job-name: pyroscope
    # The list of profiles to be scraped from the targets.    enabled-profiles: [cpu, mem]
    # List of labeled statically configured targets for this job.    static-configs:      - application: my-nodejsapp-name        spy-name: nodespy         targets:          - hostname:6060        labels:          env: dev
  • application is the name of the application being profiled. Mandatory field.
  • spy-name should be set to nodespy for NodeJS applications . Mandatory field.
  • targets lists application instances. It is important to avoid mixing profiles of different applications.


Check out the examples directory in our repository to learn more ๐Ÿ”ฅ