Node.js Profiling

Getting started guide

Create StackImpact account

Sign up for a free trial account at

Supported environment

  • Linux, OS X or Windows. Node.js v4.0.0 or higher.
  • CPU profiler is disabled by default for Node.js v7.0.0 to v8.9.3 due to memory leak in underlying V8’s CPU profiler. To enable, add cpuProfilerDisabled: false to startup options.
  • Allocation profiler supports Node.js v6.0.0 and higher. The allocation profiler is disabled by default, since V8’s heap sampling is still experimental and is seen to result in segmentation faults. To enable, add allocationProfilerDisabled: false to startup options.
  • Async profiler supports Node.js v8.1.0 and higher.

Installing the agent

Install the Node.js agent by running

npm install stackimpact

And import the package in your application

const stackimpact = require('stackimpact');

Configuring the agent

Start the agent in the main thread by specifying the agent key and application name. The agent key can be found in your account’s Configuration section.

let agent = stackimpact.start({
  agentKey: 'agent key here',
  appName: 'MyNodejsApp'

All initialization options:

  • agentKey (Required) The API key for communication with the StackImpact servers.
  • appName (Required) A name to identify and group application data. Typically, a single codebase, deployable unit or executable module corresponds to one application.
  • appVersion (Optional) Sets application version, which can be used to associate profiling information with the source code release.
  • appEnvironment (Optional) Used to differentiate applications in different environments.
  • hostName (Optional) By default, host name will be the OS hostname.
  • autoProfiling (Optional) If set to false, disables automatic profiling and reporting. agent.profile() should be used instead. Useful for environments without support for timers or background tasks.
  • debug (Optional) Enables debug logging.
  • cpuProfilerDisabled, allocationProfilerDisabled, asyncProfilerDisabled, errorProfilerDisabled (Optional) Disables respective profiler when true.
  • includeAgentFrames (Optional) Set to true to not exclude agent stack frames from profiles.

Programmatic profiling


Use agent.profile() to instruct the agent when to start and stop profiling. The agent decides if and which profiler is activated. Normally, this method should be used in repeating code, such as request or event handlers. If autoProfiling is disabled, this method will also periodically report the profiling data to the Dashboard. Usage example:

const span = agent.profile();

// your code here

span.stop(() => {
    // stoppped

Is no callback is provided, stop() method returns a promise.

Shutting down the agent

Use agent.destroy() to stop the agent if necessary, e.g. to allow application to exit.

Analyzing performance data in the Dashboard

Once your application is restarted, you can start observing continuously recorded CPU, memory, I/O, and other hot spot profiles, execution bottlenecks as well as process metrics in the Dashboard.



To enable debug logging, add debug: true to startup options. If the debug log doesn’t give you any hints on how to fix a problem, please report it to our support team in your account’s Support section.