github.com/grafana/pyroscope@v1.18.0/docs/sources/configure-client/language-sdks/nodejs.md (about)

     1  ---
     2  title: "Node.js"
     3  menuTitle: "Node.js"
     4  description: "Instrumenting Node.js applications for continuous profiling."
     5  weight: 80
     6  aliases:
     7    - /docs/phlare/latest/configure-client/language-sdks/nodejs
     8  ---
     9  
    10  # Node.js
    11  
    12  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.
    13  
    14  {{< admonition type="note" >}}
    15  Refer to [Available profiling types](https://grafana.com/docs/pyroscope/<PYROSCOPE_VERSION>/configure-client/profile-types/) for a list of profile types supported by each language.
    16  {{< /admonition >}}
    17  
    18  ## Before you begin
    19  
    20  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-for-continuous-profiling/) (requires a free Grafana Cloud account).
    21  
    22  The Pyroscope server can be a local server for development or a remote server for production use.
    23  
    24  ## Add Node.js profiling to your application
    25  
    26  To start profiling a Node.js application, you need to include the npm module in your app:
    27  
    28  ```
    29  npm install @pyroscope/nodejs
    30  
    31  # or
    32  yarn add @pyroscope/nodejs
    33  ```
    34  
    35  ## Configure the Node.js client
    36  
    37  Add the following code to your application:
    38  
    39  ```javascript
    40  const Pyroscope = require('@pyroscope/nodejs');
    41  
    42  Pyroscope.init({
    43      serverAddress: 'http://pyroscope:4040',
    44      appName: 'myNodeService',
    45      // Enable CPU time collection for wall profiles
    46      // This is required for CPU profiling functionality
    47      // wall: {
    48      //   collectCpuTime: true
    49      // }
    50  });
    51  
    52  Pyroscope.start()
    53  ```
    54  
    55  [comment]: <> (TODO This needs its own page like https://grafana.com/docs/pyroscope/latest/configure-client/grafana-alloy/go_pull/)
    56  {{< admonition type="note" >}}
    57  If you'd prefer, you can use Pull mode using [Grafana Alloy](https://grafana.com/docs/pyroscope/<PYROSCOPE_VERSION>/configure-client/grafana-alloy/go_pull/).
    58  {{< /admonition >}}
    59  
    60  
    61  ### Configuration options
    62  
    63  | Init parameter                | ENVIRONMENT VARIABLE                      | Type           | DESCRIPTION                                                                       |
    64  |-------------------------------|-------------------------------------------|----------------|-----------------------------------------------------------------------------------|
    65  | `appName:`                    | `PYROSCOPE_APPLICATION_NAME`              | String         | Sets the `service_name` label                                                     |
    66  | `serverAddress:`              | `PYROSCOPE_SERVER_ADDRESS`                | String         | URL of the Pyroscope Server                                                       |
    67  | `basicAuthUser:`              | n/a                                       | String         | Username for basic auth / Grafana Cloud stack user ID (Default `""`)              |
    68  | `basicAuthPassword:`          | n/a                                       | String         | Password for basic auth / Grafana Cloud API key (Default `""`)                    |
    69  | `flushIntervalMs:`            | `PYROSCOPE_FLUSH_INTERVAL_MS`             | Number         | Interval when profiles are sent to the server (Default `60000`)                   |
    70  | `heapSamplingIntervalBytes`   | `PYROSCOPE_HEAP_SAMPLING_INTERVAL_BYTES`  | Number         | Average number of bytes between samples. (Default `524288`)                       |
    71  | `heapStackDepth:`             | `PYROSCOPE_HEAP_STACK_DEPTH`              | Number         | Maximum stack depth for heap samples (Default `64`)                               |
    72  | `wall.SamplingDurationMs:`     | `PYROSCOPE_WALL_SAMPLING_DURATION_MS`     | Number         | Duration of a single wall profile (Default `60000`)                               |
    73  | `wall.SamplingIntervalMicros:` | `PYROSCOPE_WALL_SAMPLING_INTERVAL_MICROS` | Number         | Interval of how often wall samples are collected (Default `10000`                 |
    74  | `wall.CollectCpuTime:`         | `PYROSCOPE_WALL_COLLECT_CPU_TIME`         | Boolean        | Required for CPU profiling. Enable CPU time collection as part of the wall profiler (Default `false`)                    |
    75  | `tags:`                       | n/a                                       | [LabelSet]     | Static labels applying to all profiles collected (Default `{}`)                   |
    76  | `sourceMapper:`               | n/a                                       | [SourceMapper] | Provide source file mapping information (Default `undefined`)                     |
    77  
    78  [LabelSet]:https://github.com/DataDog/pprof-nodejs/blob/v5.3.0/ts/src/v8-types.ts#L59-L61
    79  [SourceMapper]:https://github.com/DataDog/pprof-nodejs/blob/v5.3.0/ts/src/sourcemapper/sourcemapper.ts#L152
    80  
    81  
    82  ### Add profiling labels to Node.js applications
    83  
    84  #### Static labels
    85  
    86  You can add static labels to the profiling data.
    87  These labels can be used to filter the data in the UI and apply for all profiles collected.
    88  Common static labels include:
    89  
    90  * `hostname`
    91  * `region`
    92  * `team`
    93  
    94  ```javascript
    95  Pyroscope.init({
    96    serverAddress: 'http://pyroscope:4040',
    97    appName: 'myNodeService',
    98    tags: {
    99      region: ENV['region']
   100    },
   101  });
   102  
   103  Pyroscope.start()
   104  ```
   105  
   106  #### Dynamic labels for Wall/CPU profiles
   107  
   108  In Wall and CPU profiles, labels can also be attached dynamically and help to separate different code paths:
   109  
   110  ```javascript
   111  Pyroscope.wrapWithLabels({ vehicle: 'bike' }, () =>
   112    slowCode()
   113  );
   114  ```
   115  
   116  ## Send data to Pyroscope OSS or Grafana Cloud
   117  
   118  ```javascript
   119  Pyroscope.init({
   120    serverAddress: 'http://pyroscope:4040',
   121    appName: 'myNodeService',
   122    tags: {
   123      region: ENV['region']
   124    },
   125    basicAuthUser: ENV['PYROSCOPE_BASIC_AUTH_USER'],
   126    basicAuthPassword: ENV['PYROSCOPE_BASIC_AUTH_PASSWORD'],
   127    // Optional Pyroscope tenant ID (only needed if using multi-tenancy). Not needed for Grafana Cloud.
   128    // tenantID: ENV['PYROSCOPE_TENANT_ID'],
   129  });
   130  
   131  Pyroscope.start()
   132  ```
   133  
   134  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.
   135  
   136  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.
   137  
   138  If your Pyroscope server has multi-tenancy enabled, you’ll need to configure a tenant ID. Replace `tenantID` with your Pyroscope tenant ID.
   139  
   140  ### Locate the URL, user, and password in Grafana Cloud Profiles
   141  
   142  [//]: # 'Shared content for URl location in Grafana Cloud Profiles'
   143  [//]: # 'This content is located in /pyroscope/docs/sources/shared/locate-url-pw-user-cloud-profiles.md'
   144  
   145  {{< docs/shared source="pyroscope" lookup="locate-url-pw-user-cloud-profiles.md" version="latest" >}}
   146  
   147  ## Troubleshoot
   148  
   149  Setting `DEBUG` env to `pyroscope` provides additional debugging information.
   150  
   151  ```bash
   152  DEBUG=pyroscope node index.js
   153  ```