node: implement new continuous profiling API spec

docs/migration/continuous-profiling.md

@@ -0,0 +1,28 @@
+# Continuous Profiling API Changes
+
+The continuous profiling API has been redesigned to give developers more explicit control over profiling sessions while maintaining ease of use. This guide outlines the key changes.
+
+## New Profiling Modes
+
+### profileLifecycle Option
+
+We've introduced a new `profileLifecycle` option that allows you to explicitly set how profiling sessions are managed:
+
+- `manual` (default) - You control profiling sessions using the API methods
+- `trace` - Profiling sessions are automatically tied to traces
+
+Previously, the profiling mode was implicitly determined by initialization options. Now you can clearly specify your intended behavior.
+
+## New Sampling Controls
+
+### profileSessionSampleRate
+
+We've introduced `profileSessionSampleRate` to control what percentage of SDK instances will collect profiles. This is evaluated once during SDK initialization. This is particularly useful for:
+
+- Controlling profiling costs across distributed services
+- Managing profiling in serverless environments where you may only want to profile a subset of instances
+
+### Deprecations
+
+The `profilesSampleRate` option has been deprecated in favor of the new sampling controls.
+The `profilesSampler` option hsa been deprecated in favor of manual profiler control.

packages/core/src/types-hoist/profiling.ts

@@ -14,7 +14,14 @@ export interface ProfilingIntegration<T extends Client> extends Integration {
 }
 
 export interface Profiler {
+  /**
+   * Starts the profiler.
+   */
   startProfiler(): void;
+
+  /**
+   * Stops the profiler.
+   */
   stopProfiler(): void;
 }
 

packages/node/src/types.ts

@@ -26,6 +26,8 @@ export interface BaseNodeOptions {
 
   /**
    * Sets profiling sample rate when @sentry/profiling-node is installed
+   *
+   * @deprecated
    */
   profilesSampleRate?: number;
 
@@ -39,9 +41,27 @@ export interface BaseNodeOptions {
    *
    * @returns A sample rate between 0 and 1 (0 drops the profile, 1 guarantees it will be sent). Returning `true` is
    * equivalent to returning 1 and returning `false` is equivalent to returning 0.
+   *
+   * @deprecated
    */
   profilesSampler?: (samplingContext: SamplingContext) => number | boolean;
 
+  /**
+   * Sets profiling session sample rate - only evaluated once per SDK initialization.
+   * @default 0
+   */
+  profileSessionSampleRate?: number;
+
+  /**
+   * Set the lifecycle of the profiler.
+   *
+   * - `manual`: The profiler will be manually started and stopped.
+   * - `trace`: The profiler will be automatically started when when a span is sampled and stopped when there are no more sampled spans.
+   *
+   * @default 'manual'
+   */
+  profileLifecycle?: 'manual' | 'trace';
+
   /** Sets an optional server name (device name) */
   serverName?: string;