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

# Using yarn
yarn add @sentry/node @sentry/profiling-node

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

Enabling Profiling

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

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

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  integrations: [
    // Add our Profiling integration
    new ProfilingIntegration(),
  ],
  tracesSampleRate: 1.0,
  // Set sampling rate for profiling - this is relative to tracesSampleRate
  profilesSampleRate: 1.0,
});

const transaction = Sentry.startTransaction({
  op: "transaction",
  name: "My Transaction",
});

// Any code executed between startTransaction and transaction.finish
// will now be automatically profiled.

transaction.finish();

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

Runtime Flags

The Profiling package enables you to run the profiler in either eager or lazy mode. When a profile is started while no other profiles are running, the default profiling mode (lazy) sometimes causes startProfiling calls to take a long time (sometimes in the range of a couple hundred milliseconds). The benefit of lazy logging is that it doesn't add any overhead when profiles aren't running.

If this behavior is prohibitive for your use case, you can set the environment flag shown below, which will cause the profiler to run in eager mode. Eager mode improves the performance of calls to startProfiling, but the tradeoff is small, constant CPU overhead.

# Run profiler in eager mode
SENTRY_PROFILER_LOGGING_MODE=eager node script.js

We recommend you have your own CPU resource-monitoring in place, because the actual resource use could be environment-dependent.

Precompiled Binaries

Starting from version 0.1.0, @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. 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 on the sentry/profiling-node repository.