Set Up Profiling

By default, Sentry error events will not get trace context unless you configure the scope with the transaction, as illustrated in the example below.

Installation

npm install @sentry/node @sentry/profiling-node --save

Enabling Profiling

To enable profiling, import @sentry/profiling-node, add ProfilingIntegration to your integrations, and set the profilesSampleRate.

const Sentry = require("@sentry/node");
const { nodeProfilingIntegration } = require("@sentry/profiling-node");

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  integrations: [
    // Add our Profiling integration
    nodeProfilingIntegration(),
  ],
  tracesSampleRate: 1.0,

  // Set profilesSampleRate to 1.0 to profile every transaction.
  // Since profilesSampleRate is relative to tracesSampleRate,
  // the final profiling rate can be computed as tracesSampleRate * profilesSampleRate
  // For example, a tracesSampleRate of 0.5 and profilesSampleRate of 0.5 would
  // result in 25% of transactions being profiled (0.5*0.5=0.25)
  profilesSampleRate: 1.0,
});

// Profiling happens automatically after setting it up with `Sentry.init()`.
// All spans captured in your application will have profiling data attached to them.
// You can also manually capture spans with `startSpan`, as shown below:
Sentry.startSpan(
  {
    op: "rootSpan",
    name: "My root span",
  },
  () => {
    // Any code in this callback will be profiled.
  },
);

Alternatively, instead of a profilesSampleRate your can also provide a profilesSampler function:

const Sentry = require("@sentry/node");
const { nodeProfilingIntegration } = require("@sentry/profiling-node");

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  integrations: [
    // Add our Profiling integration
    nodeProfilingIntegration(),
  ],
  tracesSampleRate: 1.0,

  // This function will be called for every sampled span
  // to determine if it should be profiled
  profilesSampler: (samplingContext) => {
    return 1.0;
  },
});

Enable Continuous Profiling

(New in version 8.28.0)

The current profiling implementation stops the profiler automatically after 30 seconds (unless you manually stop it earlier). Naturally, this limitation makes it difficult to get full coverage of your app's execution. We now offer an experimental continuous mode, where profiling data is periodically uploaded while running, with no limit on how long the profiler may run.

To get started with continuous profiling, you can start and stop the profiler directly with Sentry.profiler.startProfiler and Sentry.profiler.stopProfiler.

const Sentry = require("@sentry/node");

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
});

Sentry.profiler.startProfiler();

// run some code here

Sentry.profiler.stopProfiler();

These new APIs do not offer any sampling functionality—every call to start the profiler will run and start sending profiling data. If you are interested in reducing the amount of profiles that run, you must take care to do it at the callsites.

Continuous profiling has implications for your org's billing structure. This feature is only available for subscription plans that enrolled after June 5, 2024.

How Does It Work?

Under the hood, the Sentry profiler uses V8's CpuProfiler to collect stack samples. This means that sentry/profiling-node is written as a native add-on for Node and won't run in environments like Deno or Bun. Profiling enhances tracing by providing profiles for individual transactions. This allows you to look at higher level performance information like transaction and span durations before diving deeper and looking at profiles.

Runtime Flags

There are three runtime flags you can set that control the behavior of the profiler. Two of the flags relate to how the SDK resolves the profiler binaries. The third alters how the underlying profiler is initialized by v8.

• SENTRY_PROFILER_BINARY_PATH

This flag sets the profiler binary path and bypasses arch, platform, and libc checks. It can be useful in some build configurations if you want to override which binary is required at runtime.

• SENTRY_PROFILER_BINARY_DIR

Acts similarly to the flag above, however, this flag only specifies the directory where the binaries are located and defers to the runtime to resolve the correct binary depending on the arch, platform, and libc version.

• SENTRY_PROFILER_LOGGING_MODE

The default mode of the v8 CpuProfiler is kEagerLogging, which enables the profiler even when no profiles are active—this is good because it makes calls to startProfgiler faster with the tradeoff of constant CPU overhead. This behavior can be controlled via the SENTRY_PROFILER_LOGGING_MODE environment variable with values of eager|lazy. If you opt to use the lazy-logging mode, calls to startProfiler may be slow. (Depending on environment and node version, it can be in the order of a few hundred ms.)

Here's an example of starting a server with lazy-logging mode:

# Run profiler in lazy mode
SENTRY_PROFILER_LOGGING_MODE=lazy node server.js

Precompiled Binaries

Starting from version 0.1.0, the @sentry/profiling-node package precompiles binaries for a number of common architectures. This minimizes the tooling required to run the package and avoids compiling the package from source in most cases, which speeds up installation. Currently, we ship prebuilt binaries for the following architectures and Node versions:

• macOS arm64: Node v16, v18, v20, v22
• macOS x64: Node v16, v18, v20, v22
• Linux arm64 (musl): Node v16, v18, v20, v22
• Linux x64 (glibc): Node v16, v18, v20, v22
• Windows x64: Node v16, v18, v20, v22

The set of common architectures should cover a wide variety of use cases, but if you have feedback or experience different behavior, please open an issue in the Sentry JavaScript SDK repository.