From 70860a4452e9b28647fe7bedd58c7bd76345293b Mon Sep 17 00:00:00 2001 From: JonasBa Date: Thu, 13 Mar 2025 10:20:17 -0400 Subject: [PATCH 1/9] docs: update continuous profiling docs --- .../common/profiling/node-profiling.mdx | 58 +++++++++++++++++-- 1 file changed, 53 insertions(+), 5 deletions(-) diff --git a/docs/platforms/javascript/common/profiling/node-profiling.mdx b/docs/platforms/javascript/common/profiling/node-profiling.mdx index 9e4f18c97c4eb..985528dd84e33 100644 --- a/docs/platforms/javascript/common/profiling/node-profiling.mdx +++ b/docs/platforms/javascript/common/profiling/node-profiling.mdx @@ -35,6 +35,12 @@ You have to have the (minimum ## Enabling Profiling +Profiling supports two manin modes - manual and trace lifecycle. The two modes are mutually exclusive, and cannot be used at the same time. In manual mode, the profiling data collection can be managed via calls to Sentry.profiler.startProfileSession and Sentry.profiler.stopProfileSession. In this mode, you are entirely in the in control of when the profiler runs. + +Trace lifecycle mode differs in the sense that the profiler manages it's own start and stop calls, which are based on the logic of active spans. In this mode, the profiler continues to run while there is at least one active span, and stops when there are no active spans. + +### Enabling Automatic Trace Profiling + To enable profiling, add `@sentry/profiling-node` to your imports and set up `nodeProfilingIntegration` in your Sentry config. ```javascript {diff} @@ -47,24 +53,65 @@ Sentry.init({ + nodeProfilingIntegration(), ], tracesSampleRate: 1.0, -+ // Set sampling rate for profiling - this is relative to tracesSampleRate -+ profilesSampleRate: 1.0, ++ profileLifecycle: 'trace', }); // 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: +// All spans (unless those discarded by sampling) will have profiling data attached to them. Sentry.startSpan( { op: "rootSpan", name: "My root span", }, () => { - // Any code in this callback will be profiled. + // The code executed here will be profiled } ); ``` +### Enabling Manual Trace Profiling + +To enable profiling, add `@sentry/profiling-node` to your imports and set up `nodeProfilingIntegration` in your Sentry config. + +```javascript {diff} +const { nodeProfilingIntegration } = require("@sentry/profiling-node"); + +Sentry.init({ + dsn: "___PUBLIC_DSN___", + integrations: [ + // Add our Profiling integration ++ nodeProfilingIntegration(), + ], + tracesSampleRate: 1.0, ++ profileLifecycle: 'manual', // default can be omitted +}); + +// All spans (unless those discarded by sampling) will have profiling data attached to them. +Sentry.profiler.startProfileSession(); +// Code executed between these two calls will be profiled +Sentry.profiler.stopProfileSession(); +``` + +### Managing profile sampling rates + +Sentry SDK supports an additional `profileSessionSampleRate` that will enable or disable profiling for the entire session. This can be used if you want to control session sampling rates at the service level. The sampling decision is evaluated only once at SDK init, and it controls whether all calls to the profiler will be enabled or disabled. + +This is useful for cases where you deploy your service N times, but would only like for a subset of those services to be profiled. + +```javascript {diff} +const { nodeProfilingIntegration } = require("@sentry/profiling-node"); + +Sentry.init({ + dsn: "___PUBLIC_DSN___", + integrations: [ + // Add our Profiling integration + nodeProfilingIntegration(), + ], + tracesSampleRate: 1.0, ++ profileSessionSampleRate: 0.0 // All profiling is disabled +}); + + ## How Does It Work? Under the hood, the Sentry profiler uses V8's [CpuProfiler](https://v8docs.nodesource.com/node-18.2/d2/d34/classv8_1_1_cpu_profiler.html) to collect stack samples. This means that `sentry/profiling-node` is written as a [native add-on](https://nodejs.org/docs/latest-v18.x/api/addons.html) 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. @@ -81,3 +128,4 @@ Starting from version `0.1.0`, the `@sentry/profiling-node` package precompiles - 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](https://github.com/getsentry/sentry-javascript) repository. +``` From 9d03403952bb181b5eedf3d7ac700382c7622c5e Mon Sep 17 00:00:00 2001 From: JonasBa Date: Thu, 13 Mar 2025 14:50:40 -0400 Subject: [PATCH 2/9] add profileSessionSampleRate --- .../javascript/common/profiling/node-profiling.mdx | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/platforms/javascript/common/profiling/node-profiling.mdx b/docs/platforms/javascript/common/profiling/node-profiling.mdx index 985528dd84e33..a654ca2fff49d 100644 --- a/docs/platforms/javascript/common/profiling/node-profiling.mdx +++ b/docs/platforms/javascript/common/profiling/node-profiling.mdx @@ -53,6 +53,7 @@ Sentry.init({ + nodeProfilingIntegration(), ], tracesSampleRate: 1.0, ++ profileSessionSampleRate: 1.0, + profileLifecycle: 'trace', }); @@ -83,7 +84,8 @@ Sentry.init({ + nodeProfilingIntegration(), ], tracesSampleRate: 1.0, -+ profileLifecycle: 'manual', // default can be omitted ++ profileSessionSampleRate: 1.0, ++ profileLifecycle: 'manual', }); // All spans (unless those discarded by sampling) will have profiling data attached to them. @@ -94,9 +96,9 @@ Sentry.profiler.stopProfileSession(); ### Managing profile sampling rates -Sentry SDK supports an additional `profileSessionSampleRate` that will enable or disable profiling for the entire session. This can be used if you want to control session sampling rates at the service level. The sampling decision is evaluated only once at SDK init, and it controls whether all calls to the profiler will be enabled or disabled. +Sentry SDK supports an additional `profileSessionSampleRate` that will enable or disable profiling for the entire session. This can be used if you want to control session sampling rates at the service level as the sampling decision is evaluated only once at SDK init. -This is useful for cases where you deploy your service N times, but would only like for a subset of those services to be profiled. +This is useful for cases where you deploy your service many times, but would only like a subset of those services to be profiled. ```javascript {diff} const { nodeProfilingIntegration } = require("@sentry/profiling-node"); @@ -108,7 +110,7 @@ Sentry.init({ nodeProfilingIntegration(), ], tracesSampleRate: 1.0, -+ profileSessionSampleRate: 0.0 // All profiling is disabled ++ profileSessionSampleRate: 0.0 }); From 0216d8bd5c28126693697f6b7161022988e21f74 Mon Sep 17 00:00:00 2001 From: Jonas Date: Thu, 13 Mar 2025 15:04:11 -0400 Subject: [PATCH 3/9] Update docs/platforms/javascript/common/profiling/node-profiling.mdx --- docs/platforms/javascript/common/profiling/node-profiling.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/javascript/common/profiling/node-profiling.mdx b/docs/platforms/javascript/common/profiling/node-profiling.mdx index a654ca2fff49d..2a12d26d39554 100644 --- a/docs/platforms/javascript/common/profiling/node-profiling.mdx +++ b/docs/platforms/javascript/common/profiling/node-profiling.mdx @@ -35,7 +35,7 @@ You have to have the (minimum ## Enabling Profiling -Profiling supports two manin modes - manual and trace lifecycle. The two modes are mutually exclusive, and cannot be used at the same time. In manual mode, the profiling data collection can be managed via calls to Sentry.profiler.startProfileSession and Sentry.profiler.stopProfileSession. In this mode, you are entirely in the in control of when the profiler runs. +Profiling supports two main modes - manual and trace lifecycle. The two modes are mutually exclusive, and cannot be used at the same time. In manual mode, the profiling data collection can be managed via calls to Sentry.profiler.startProfileSession and Sentry.profiler.stopProfileSession. In this mode, you are entirely in the in control of when the profiler runs. Trace lifecycle mode differs in the sense that the profiler manages it's own start and stop calls, which are based on the logic of active spans. In this mode, the profiler continues to run while there is at least one active span, and stops when there are no active spans. From 44b7dd6fe716c36e879e17537f26f92d81842f35 Mon Sep 17 00:00:00 2001 From: Jonas Date: Thu, 13 Mar 2025 15:37:40 -0400 Subject: [PATCH 4/9] Update docs/platforms/javascript/common/profiling/node-profiling.mdx Co-authored-by: Pierre Massat --- docs/platforms/javascript/common/profiling/node-profiling.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/javascript/common/profiling/node-profiling.mdx b/docs/platforms/javascript/common/profiling/node-profiling.mdx index 2a12d26d39554..37bc19b864aad 100644 --- a/docs/platforms/javascript/common/profiling/node-profiling.mdx +++ b/docs/platforms/javascript/common/profiling/node-profiling.mdx @@ -37,7 +37,7 @@ You have to have the (minimum Profiling supports two main modes - manual and trace lifecycle. The two modes are mutually exclusive, and cannot be used at the same time. In manual mode, the profiling data collection can be managed via calls to Sentry.profiler.startProfileSession and Sentry.profiler.stopProfileSession. In this mode, you are entirely in the in control of when the profiler runs. -Trace lifecycle mode differs in the sense that the profiler manages it's own start and stop calls, which are based on the logic of active spans. In this mode, the profiler continues to run while there is at least one active span, and stops when there are no active spans. +In `trace` mode, the profiler manages its own start and stop calls, which are based on spans: the profiler continues to run while there is at least one active span, and stops when there are no active spans. ### Enabling Automatic Trace Profiling From edf9a893f366104b056302bf044394a909e754b2 Mon Sep 17 00:00:00 2001 From: Jonas Date: Thu, 13 Mar 2025 15:37:50 -0400 Subject: [PATCH 5/9] Update docs/platforms/javascript/common/profiling/node-profiling.mdx Co-authored-by: Pierre Massat --- docs/platforms/javascript/common/profiling/node-profiling.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/javascript/common/profiling/node-profiling.mdx b/docs/platforms/javascript/common/profiling/node-profiling.mdx index 37bc19b864aad..ba978b54033e6 100644 --- a/docs/platforms/javascript/common/profiling/node-profiling.mdx +++ b/docs/platforms/javascript/common/profiling/node-profiling.mdx @@ -70,7 +70,7 @@ Sentry.startSpan( ); ``` -### Enabling Manual Trace Profiling +### Enabling Manual Lifecycle Profiling To enable profiling, add `@sentry/profiling-node` to your imports and set up `nodeProfilingIntegration` in your Sentry config. From a438bd41c8e09a115bace56f21795566c40202b8 Mon Sep 17 00:00:00 2001 From: Jonas Date: Thu, 13 Mar 2025 15:38:05 -0400 Subject: [PATCH 6/9] Update docs/platforms/javascript/common/profiling/node-profiling.mdx Co-authored-by: Pierre Massat --- docs/platforms/javascript/common/profiling/node-profiling.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/platforms/javascript/common/profiling/node-profiling.mdx b/docs/platforms/javascript/common/profiling/node-profiling.mdx index ba978b54033e6..5efea9e6feaad 100644 --- a/docs/platforms/javascript/common/profiling/node-profiling.mdx +++ b/docs/platforms/javascript/common/profiling/node-profiling.mdx @@ -35,7 +35,9 @@ You have to have the (minimum ## Enabling Profiling -Profiling supports two main modes - manual and trace lifecycle. The two modes are mutually exclusive, and cannot be used at the same time. In manual mode, the profiling data collection can be managed via calls to Sentry.profiler.startProfileSession and Sentry.profiler.stopProfileSession. In this mode, you are entirely in the in control of when the profiler runs. +Profiling supports two modes - `manual` and `trace`. The two modes are mutually exclusive, and cannot be used at the same time. + +In `manual` mode, the profiling data collection can be managed via calls to `Sentry.profiler.startProfileSession` and `Sentry.profiler.stopProfileSession`. You are entirely in the in control of when the profiler runs. In `trace` mode, the profiler manages its own start and stop calls, which are based on spans: the profiler continues to run while there is at least one active span, and stops when there are no active spans. From 5d00cbd7c49e87dc8edd74eccd762ad23ed40fca Mon Sep 17 00:00:00 2001 From: Jonas Date: Thu, 13 Mar 2025 15:38:21 -0400 Subject: [PATCH 7/9] Update docs/platforms/javascript/common/profiling/node-profiling.mdx Co-authored-by: Pierre Massat --- docs/platforms/javascript/common/profiling/node-profiling.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/javascript/common/profiling/node-profiling.mdx b/docs/platforms/javascript/common/profiling/node-profiling.mdx index 5efea9e6feaad..e6de5569e9011 100644 --- a/docs/platforms/javascript/common/profiling/node-profiling.mdx +++ b/docs/platforms/javascript/common/profiling/node-profiling.mdx @@ -41,7 +41,7 @@ In `manual` mode, the profiling data collection can be managed via calls to `Sen In `trace` mode, the profiler manages its own start and stop calls, which are based on spans: the profiler continues to run while there is at least one active span, and stops when there are no active spans. -### Enabling Automatic Trace Profiling +### Enabling Trace Lifecycle Profiling To enable profiling, add `@sentry/profiling-node` to your imports and set up `nodeProfilingIntegration` in your Sentry config. From be8860d819e34b863d1f15c1e7690256d1093a0d Mon Sep 17 00:00:00 2001 From: Jonas Date: Thu, 13 Mar 2025 15:38:29 -0400 Subject: [PATCH 8/9] Update docs/platforms/javascript/common/profiling/node-profiling.mdx Co-authored-by: Pierre Massat --- docs/platforms/javascript/common/profiling/node-profiling.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/platforms/javascript/common/profiling/node-profiling.mdx b/docs/platforms/javascript/common/profiling/node-profiling.mdx index e6de5569e9011..af931d64dd138 100644 --- a/docs/platforms/javascript/common/profiling/node-profiling.mdx +++ b/docs/platforms/javascript/common/profiling/node-profiling.mdx @@ -132,4 +132,3 @@ Starting from version `0.1.0`, the `@sentry/profiling-node` package precompiles - 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](https://github.com/getsentry/sentry-javascript) repository. -``` From a552a06ef400bb46e0a27b786e4d8b590d342491 Mon Sep 17 00:00:00 2001 From: JonasBa Date: Mon, 24 Mar 2025 06:22:24 -0400 Subject: [PATCH 9/9] fix start and stop naming --- .../javascript/common/profiling/node-profiling.mdx | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/platforms/javascript/common/profiling/node-profiling.mdx b/docs/platforms/javascript/common/profiling/node-profiling.mdx index af931d64dd138..5e8ff41fef4b5 100644 --- a/docs/platforms/javascript/common/profiling/node-profiling.mdx +++ b/docs/platforms/javascript/common/profiling/node-profiling.mdx @@ -37,7 +37,7 @@ You have to have the (minimum Profiling supports two modes - `manual` and `trace`. The two modes are mutually exclusive, and cannot be used at the same time. -In `manual` mode, the profiling data collection can be managed via calls to `Sentry.profiler.startProfileSession` and `Sentry.profiler.stopProfileSession`. You are entirely in the in control of when the profiler runs. +In `manual` mode, the profiling data collection can be managed via calls to `Sentry.profiler.startProfiler` and `Sentry.profiler.stopProfiler`. You are entirely in the in control of when the profiler runs. In `trace` mode, the profiler manages its own start and stop calls, which are based on spans: the profiler continues to run while there is at least one active span, and stops when there are no active spans. @@ -91,9 +91,9 @@ Sentry.init({ }); // All spans (unless those discarded by sampling) will have profiling data attached to them. -Sentry.profiler.startProfileSession(); +Sentry.profiler.startProfiler(); // Code executed between these two calls will be profiled -Sentry.profiler.stopProfileSession(); +Sentry.profiler.stopProfiler(); ``` ### Managing profile sampling rates @@ -132,3 +132,4 @@ Starting from version `0.1.0`, the `@sentry/profiling-node` package precompiles - 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](https://github.com/getsentry/sentry-javascript) repository. +```