ref: document all profiler runtime flags (#11382)

JonasBa · andreiborza · lizokm · web-flow · commit c7438a2ad221 · 2024-09-19T20:32:08.000Z
* ref: document all profiler runtime flags

* Update docs/platforms/javascript/guides/aws-lambda/profiling/index.mdx

Co-authored-by: Andrei &lt;168741329+andreiborza@users.noreply.github.com&gt;

* Update docs/platforms/javascript/guides/aws-lambda/profiling/index.mdx

Co-authored-by: Andrei &lt;168741329+andreiborza@users.noreply.github.com&gt;

* use note for advanced use case warning

* use include

* Update includes/profiling-node-runtime-flags.mdx

Co-authored-by: Liza Mock &lt;liza.mock@sentry.io&gt;

* Update includes/profiling-node-runtime-flags.mdx

Co-authored-by: Liza Mock &lt;liza.mock@sentry.io&gt;

* link to v8

---------

Co-authored-by: Andrei &lt;168741329+andreiborza@users.noreply.github.com&gt;
Co-authored-by: Liza Mock &lt;liza.mock@sentry.io&gt;
diff --git a/docs/platforms/javascript/guides/aws-lambda/profiling/index.mdx b/docs/platforms/javascript/guides/aws-lambda/profiling/index.mdx
@@ -71,18 +71,7 @@ Sentry.startSpan(
 
 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.
 
-## Runtime Flags
-
-The default mode of the v8 CpuProfiler is [kEagerLogging](https://v8docs.nodesource.com/node-18.2/d2/dc3/namespacev8.html#a874b4921ddee43bef58d8538e3149374) which enables the profiler even when no profiles are active—this is good because it makes calls to `startProfiling` fast 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 `startProfiling` 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:
-
-```bash
-# Run profiler in lazy mode
-SENTRY_PROFILER_LOGGING_MODE=lazy node server.js
-```
-
-We recommend you have your own CPU resource-monitoring in place, because the actual resource use could be environment-dependent.
+<Include name="profiling-node-runtime-flags.mdx" />
 
 ## Precompiled Binaries
 
diff --git a/docs/platforms/javascript/guides/azure-functions/profiling/index.mdx b/docs/platforms/javascript/guides/azure-functions/profiling/index.mdx
@@ -71,18 +71,7 @@ Sentry.startSpan(
 
 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.
 
-## Runtime Flags
-
-The default mode of the v8 CpuProfiler is [kEagerLogging](https://v8docs.nodesource.com/node-18.2/d2/dc3/namespacev8.html#a874b4921ddee43bef58d8538e3149374) which enables the profiler even when no profiles are active—this is good because it makes calls to `startProfiling` fast 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 `startProfiling` 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:
-
-```bash
-# Run profiler in lazy mode
-SENTRY_PROFILER_LOGGING_MODE=lazy node server.js
-```
-
-We recommend you have your own CPU resource-monitoring in place, because the actual resource use could be environment-dependent.
+<Include name="profiling-node-runtime-flags.mdx" />
 
 ## Precompiled Binaries
 
diff --git a/docs/platforms/javascript/guides/connect/profiling/index.mdx b/docs/platforms/javascript/guides/connect/profiling/index.mdx
@@ -71,18 +71,7 @@ Sentry.startSpan(
 
 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.
 
-## Runtime Flags
-
-The default mode of the v8 CpuProfiler is [kEagerLogging](https://v8docs.nodesource.com/node-18.2/d2/dc3/namespacev8.html#a874b4921ddee43bef58d8538e3149374) which enables the profiler even when no profiles are active—this is good because it makes calls to `startProfiling` fast 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 `startProfiling` 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:
-
-```bash
-# Run profiler in lazy mode
-SENTRY_PROFILER_LOGGING_MODE=lazy node server.js
-```
-
-We recommend you have your own CPU resource-monitoring in place, because the actual resource use could be environment-dependent.
+<Include name="profiling-node-runtime-flags.mdx" />
 
 ## Precompiled Binaries
 
diff --git a/docs/platforms/javascript/guides/express/profiling/index.mdx b/docs/platforms/javascript/guides/express/profiling/index.mdx
@@ -71,18 +71,7 @@ Sentry.startSpan(
 
 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.
 
-## Runtime Flags
-
-The default mode of the v8 CpuProfiler is [kEagerLogging](https://v8docs.nodesource.com/node-18.2/d2/dc3/namespacev8.html#a874b4921ddee43bef58d8538e3149374) which enables the profiler even when no profiles are active—this is good because it makes calls to `startProfiling` fast 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 `startProfiling` 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:
-
-```bash
-# Run profiler in lazy mode
-SENTRY_PROFILER_LOGGING_MODE=lazy node server.js
-```
-
-We recommend you have your own CPU resource-monitoring in place, because the actual resource use could be environment-dependent.
+<Include name="profiling-node-runtime-flags.mdx" />
 
 ## Precompiled Binaries
 
diff --git a/docs/platforms/javascript/guides/fastify/profiling/index.mdx b/docs/platforms/javascript/guides/fastify/profiling/index.mdx
@@ -71,18 +71,7 @@ Sentry.startSpan(
 
 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.
 
-## Runtime Flags
-
-The default mode of the v8 CpuProfiler is [kEagerLogging](https://v8docs.nodesource.com/node-18.2/d2/dc3/namespacev8.html#a874b4921ddee43bef58d8538e3149374) which enables the profiler even when no profiles are active—this is good because it makes calls to `startProfiling` fast 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 `startProfiling` 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:
-
-```bash
-# Run profiler in lazy mode
-SENTRY_PROFILER_LOGGING_MODE=lazy node server.js
-```
-
-We recommend you have your own CPU resource-monitoring in place, because the actual resource use could be environment-dependent.
+<Include name="profiling-node-runtime-flags.mdx" />
 
 ## Precompiled Binaries
 
diff --git a/docs/platforms/javascript/guides/gcp-functions/profiling/index.mdx b/docs/platforms/javascript/guides/gcp-functions/profiling/index.mdx
@@ -71,18 +71,7 @@ Sentry.startSpan(
 
 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.
 
-## Runtime Flags
-
-The default mode of the v8 CpuProfiler is [kEagerLogging](https://v8docs.nodesource.com/node-18.2/d2/dc3/namespacev8.html#a874b4921ddee43bef58d8538e3149374) which enables the profiler even when no profiles are active—this is good because it makes calls to `startProfiling` fast 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 `startProfiling` 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:
-
-```bash
-# Run profiler in lazy mode
-SENTRY_PROFILER_LOGGING_MODE=lazy node server.js
-```
-
-We recommend you have your own CPU resource-monitoring in place, because the actual resource use could be environment-dependent.
+<Include name="profiling-node-runtime-flags.mdx" />
 
 ## Precompiled Binaries
 
diff --git a/docs/platforms/javascript/guides/hapi/profiling/index.mdx b/docs/platforms/javascript/guides/hapi/profiling/index.mdx
@@ -71,18 +71,7 @@ Sentry.startSpan(
 
 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.
 
-## Runtime Flags
-
-The default mode of the v8 CpuProfiler is [kEagerLogging](https://v8docs.nodesource.com/node-18.2/d2/dc3/namespacev8.html#a874b4921ddee43bef58d8538e3149374) which enables the profiler even when no profiles are active—this is good because it makes calls to `startProfiling` fast 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 `startProfiling` 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:
-
-```bash
-# Run profiler in lazy mode
-SENTRY_PROFILER_LOGGING_MODE=lazy node server.js
-```
-
-We recommend you have your own CPU resource-monitoring in place, because the actual resource use could be environment-dependent.
+<Include name="profiling-node-runtime-flags.mdx" />
 
 ## Precompiled Binaries
 
diff --git a/docs/platforms/javascript/guides/koa/profiling/index.mdx b/docs/platforms/javascript/guides/koa/profiling/index.mdx
@@ -71,18 +71,7 @@ Sentry.startSpan(
 
 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.
 
-## Runtime Flags
-
-The default mode of the v8 CpuProfiler is [kEagerLogging](https://v8docs.nodesource.com/node-18.2/d2/dc3/namespacev8.html#a874b4921ddee43bef58d8538e3149374) which enables the profiler even when no profiles are active—this is good because it makes calls to `startProfiling` fast 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 `startProfiling` 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:
-
-```bash
-# Run profiler in lazy mode
-SENTRY_PROFILER_LOGGING_MODE=lazy node server.js
-```
-
-We recommend you have your own CPU resource-monitoring in place, because the actual resource use could be environment-dependent.
+<Include name="profiling-node-runtime-flags.mdx" />
 
 ## Precompiled Binaries
 
diff --git a/docs/platforms/javascript/guides/nestjs/profiling/index.mdx b/docs/platforms/javascript/guides/nestjs/profiling/index.mdx
@@ -71,18 +71,7 @@ Sentry.startSpan(
 
 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.
 
-## Runtime Flags
-
-The default mode of the v8 CpuProfiler is [kEagerLogging](https://v8docs.nodesource.com/node-18.2/d2/dc3/namespacev8.html#a874b4921ddee43bef58d8538e3149374) which enables the profiler even when no profiles are active—this is good because it makes calls to `startProfiling` fast 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 `startProfiling` 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:
-
-```bash
-# Run profiler in lazy mode
-SENTRY_PROFILER_LOGGING_MODE=lazy node server.js
-```
-
-We recommend you have your own CPU resource-monitoring in place, because the actual resource use could be environment-dependent.
+<Include name="profiling-node-runtime-flags.mdx" />
 
 ## Precompiled Binaries
 
diff --git a/docs/platforms/javascript/guides/node/profiling/index.mdx b/docs/platforms/javascript/guides/node/profiling/index.mdx
@@ -131,18 +131,7 @@ Continuous profiling has implications for your org's billing structure. This fea
 
 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.
 
-## Runtime Flags
-
-The default mode of the v8 CpuProfiler is [kEagerLogging](https://v8docs.nodesource.com/node-18.2/d2/dc3/namespacev8.html#a874b4921ddee43bef58d8538e3149374) which enables the profiler even when no profiles are active—this is good because it makes calls to `startProfiling` fast 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 `startProfiling` 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:
-
-```bash
-# Run profiler in lazy mode
-SENTRY_PROFILER_LOGGING_MODE=lazy node server.js
-```
-
-We recommend you have your own CPU resource-monitoring in place, because the actual resource use could be environment-dependent.
+<Include name="profiling-node-runtime-flags.mdx" />
 
 ## Precompiled Binaries
 
diff --git a/includes/profiling-node-runtime-flags.mdx b/includes/profiling-node-runtime-flags.mdx
@@ -0,0 +1,25 @@
+
+## 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](https://v8docs.nodesource.com/).
+
+<Note>
+These flags are intended for advanced use cases only. Setting them isn't required for most use cases.
+</Note>
+
+- 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](https://v8docs.nodesource.com/node-18.2/d2/dc3/namespacev8.html#a874b4921ddee43bef58d8538e3149374), which enables the profiler even when no profiles are active—this is good because it makes calls to `startProfiling` fast 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 `startProfiling` 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:
+
+  ```bash
+  # Run profiler in lazy mode
+  SENTRY_PROFILER_LOGGING_MODE=lazy node server.js
