--- title: "Node.js | Grafana Pyroscope documentation" description: "Instrumenting Node.js applications for continuous profiling." --- # 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](/docs/pyroscope/next/configure-client/profile-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](/products/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: ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```none npm install @pyroscope/nodejs # or yarn add @pyroscope/nodejs ``` ## Configure the Node.js client Add the following code to your application: JavaScript ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```javascript const Pyroscope = require('@pyroscope/nodejs'); Pyroscope.init({ serverAddress: 'http://pyroscope:4040', appName: 'myNodeService', // Enable CPU time collection for wall profiles // This is required for CPU profiling functionality // wall: { // collectCpuTime: true // } }); Pyroscope.start() ``` > Note > > If you’d prefer, you can use Pull mode using [Grafana Alloy](/docs/pyroscope/next/configure-client/grafana-alloy/go_pull/). ### Configuration options Expand table | Init parameter | ENVIRONMENT VARIABLE | Type | DESCRIPTION | |--------------------------------|-------------------------------------------|--------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------| | `appName:` | `PYROSCOPE_APPLICATION_NAME` | String | Sets the `service_name` label | | `serverAddress:` | `PYROSCOPE_SERVER_ADDRESS` | String | URL of the Pyroscope Server | | `basicAuthUser:` | n/a | String | Username for basic auth / Grafana Cloud stack user ID (Default `""`) | | `basicAuthPassword:` | n/a | String | Password for basic auth / Grafana Cloud API key (Default `""`) | | `flushIntervalMs:` | `PYROSCOPE_FLUSH_INTERVAL_MS` | Number | Interval when profiles are sent to the server (Default `60000`) | | `heapSamplingIntervalBytes` | `PYROSCOPE_HEAP_SAMPLING_INTERVAL_BYTES` | Number | Average number of bytes between samples. (Default `524288`) | | `heapStackDepth:` | `PYROSCOPE_HEAP_STACK_DEPTH` | Number | Maximum stack depth for heap samples (Default `64`) | | `wall.SamplingDurationMs:` | `PYROSCOPE_WALL_SAMPLING_DURATION_MS` | Number | Duration of a single wall profile (Default `60000`) | | `wall.SamplingIntervalMicros:` | `PYROSCOPE_WALL_SAMPLING_INTERVAL_MICROS` | Number | Interval of how often wall samples are collected (Default `10000` | | `wall.CollectCpuTime:` | `PYROSCOPE_WALL_COLLECT_CPU_TIME` | Boolean | Required for CPU profiling. Enable CPU time collection as part of the wall profiler (Default `false`) | | `tags:` | n/a | [LabelSet](https://github.com/DataDog/pprof-nodejs/blob/v5.3.0/ts/src/v8-types.ts#L59-L61) | Static labels applying to all profiles collected (Default `{}`) | | `sourceMapper:` | n/a | [SourceMapper](https://github.com/DataDog/pprof-nodejs/blob/v5.3.0/ts/src/sourcemapper/sourcemapper.ts#L152) | Provide 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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```javascript Pyroscope.init({ serverAddress: 'http://pyroscope:4040', appName: 'myNodeService', tags: { region: ENV['region'] }, }); Pyroscope.start() ``` #### Dynamic labels for Wall/CPU profiles In Wall and CPU profiles, labels can also be attached dynamically and help to separate different code paths: JavaScript ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```javascript Pyroscope.wrapWithLabels({ vehicle: 'bike' }, () => slowCode() ); ``` ## Send data to Pyroscope OSS or Grafana Cloud JavaScript ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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. ### Locate the URL, user, and password in Grafana Cloud Profiles When you configure Alloy or your SDK, you need to provide the URL, user, and password for your Grafana Cloud stack. This information is located in the **Pyroscope** section of your Grafana Cloud stack. 1. Navigate to your Grafana Cloud stack. 2. Select **Details** next to your stack. 3. Locate the **Pyroscope** section and select **Details**. 4. Copy the **URL**, **User**, and **Password** values in the **Configure the client and data source using Grafana credentials** section. 5. Use these values to complete the configuration. As an alternative, you can also create a Cloud Access Policy and generate a token to use instead of the user and password. For more information, refer to [Create a Cloud Access Policy](/docs/grafana-cloud/security-and-account-management/authentication-and-permissions/access-policies/create-access-policies/). ## Troubleshoot Setting `DEBUG` env to `pyroscope` provides additional debugging information. Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash DEBUG=pyroscope node index.js ```