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.

const Sentry = require("@sentry/node");
// Note: You MUST import @sentry/tracing package before @sentry/profiling-node
require("@sentry/tracing");
const {ProfilingIntegration} = require("@sentry/profiling-node");

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  integrations: [
    // Add our Profilling integration
    new ProfilingIntegration(),
  ],
  tracesSampleRate: 1.0,
  // Set sampling rate for profiling
  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.

If you have feedback or experience different behavior, please open an issue on sentry/profiling-node repository.