v8: add cpu profile options

PR-URL: #62684
Reviewed-By: Stephen Belanger <admin@stephenbelanger.com>
Reviewed-By: theanarkh <theratliter@gmail.com>

Author: IlyasShabi

doc/api/v8.md

@@ -1771,21 +1771,25 @@ writeString('hello');
 writeString('你好');
 ```
 
-## `v8.startCpuProfile()`
+## `v8.startCpuProfile([options])`
 
 <!-- YAML
 added:
   - v25.0.0
   - v24.12.0
 -->
 
+* `options` {Object}
+  * `sampleInterval` {number} Requested sampling interval in milliseconds. **Default:** `0`.
+  * `maxBufferSize` {integer} Maximum number of samples to keep before older
+    entries are discarded. **Default:** `4294967295`.
 * Returns: {SyncCPUProfileHandle}
 
 Starting a CPU profile then return a `SyncCPUProfileHandle` object.
 This API supports `using` syntax.
 
 ```cjs
-const handle = v8.startCpuProfile();
+const handle = v8.startCpuProfile({ sampleInterval: 1, maxBufferSize: 10_000 });
 const profile = handle.stop();
 console.log(profile);
 ```

doc/api/worker_threads.md

@@ -1962,12 +1962,16 @@ this matches its values.
 
 If the worker has stopped, the return value is an empty object.
 
-### `worker.startCpuProfile()`
+### `worker.startCpuProfile([options])`
 
 <!-- YAML
 added: v24.8.0
 -->
 
+* `options` {Object}
+  * `sampleInterval` {number} Requested sampling interval in milliseconds. **Default:** `0`.
+  * `maxBufferSize` {integer} Maximum number of samples to retain.
+    **Default:** `4294967295`.
 * Returns: {Promise}
 
 Starting a CPU profile then return a Promise that fulfills with an error
@@ -1982,7 +1986,7 @@ const worker = new Worker(`
   `, { eval: true });
 
 worker.on('online', async () => {
-  const handle = await worker.startCpuProfile();
+  const handle = await worker.startCpuProfile({ sampleInterval: 1 });
   const profile = await handle.stop();
   console.log(profile);
   worker.terminate();

lib/internal/v8/cpu_profiler.js

@@ -0,0 +1,56 @@
+'use strict';
+
+const {
+  MathFloor,
+} = primordials;
+
+const {
+  validateNumber,
+  validateObject,
+} = require('internal/validators');
+
+const kMicrosPerMilli = 1_000;
+const kMaxSamplingIntervalUs = 0x7FFFFFFF;
+const kMaxSamplingIntervalMs = kMaxSamplingIntervalUs / kMicrosPerMilli;
+const kMaxSamplesUnlimited = 0xFFFF_FFFF;
+
+function normalizeCpuProfileOptions(options = {}) {
+  validateObject(options, 'options');
+
+  // TODO(ishabi): add support for 'mode' and 'filterContext' options
+  const {
+    sampleInterval,
+    maxBufferSize,
+  } = options;
+
+  let samplingIntervalMicros = 0;
+  if (sampleInterval !== undefined) {
+    validateNumber(sampleInterval,
+                   'options.sampleInterval',
+                   0,
+                   kMaxSamplingIntervalMs);
+    samplingIntervalMicros = MathFloor(sampleInterval * kMicrosPerMilli);
+    if (sampleInterval > 0 && samplingIntervalMicros === 0) {
+      samplingIntervalMicros = 1;
+    }
+  }
+
+  const size = maxBufferSize;
+  let normalizedMaxSamples = kMaxSamplesUnlimited;
+  if (size !== undefined) {
+    validateNumber(size,
+                   'options.maxBufferSize',
+                   1,
+                   kMaxSamplesUnlimited);
+    normalizedMaxSamples = MathFloor(size);
+  }
+
+  return {
+    samplingIntervalMicros,
+    maxSamples: normalizedMaxSamples,
+  };
+}
+
+module.exports = {
+  normalizeCpuProfileOptions,
+};

lib/internal/worker.js

@@ -71,7 +71,6 @@ const {
   validateObject,
   validateNumber,
 } = require('internal/validators');
-let normalizeHeapProfileOptions;
 const {
   throwIfBuildingSnapshot,
 } = require('internal/v8/startup_snapshot');
@@ -111,6 +110,8 @@ const dc = require('diagnostics_channel');
 const workerThreadsChannel = dc.channel('worker_threads');
 
 let cwdCounter;
+let normalizeHeapProfileOptions;
+let normalizeCpuProfileOptions;
 
 const environmentData = new SafeMap();
 
@@ -574,9 +575,16 @@ class Worker extends EventEmitter {
     });
   }
 
-  // TODO(theanarkh): add options, such as sample_interval, CpuProfilingMode
-  startCpuProfile() {
-    const startTaker = this[kHandle]?.startCpuProfile();
+  startCpuProfile(options) {
+    normalizeCpuProfileOptions ??=
+      require('internal/v8/cpu_profiler').normalizeCpuProfileOptions;
+    const {
+      samplingIntervalMicros,
+      maxSamples,
+    } = normalizeCpuProfileOptions(options);
+    const startTaker = this[kHandle]?.startCpuProfile(
+      samplingIntervalMicros,
+      maxSamples);
     return new Promise((resolve, reject) => {
       if (!startTaker) return reject(new ERR_WORKER_NOT_RUNNING());
       startTaker.ondone = (err, id) => {

lib/v8.js

@@ -53,6 +53,9 @@ const {
 const {
   normalizeHeapProfileOptions,
 } = require('internal/v8/heap_profile');
+const {
+  normalizeCpuProfileOptions,
+} = require('internal/v8/cpu_profiler');
 
 let profiler = {};
 if (internalBinding('config').hasInspector) {
@@ -214,10 +217,17 @@ class SyncHeapProfileHandle {
 
 /**
  * Starting CPU Profile.
+ * @param {object} [options]
+ * @param {number} [options.sampleInterval]
+ * @param {number} [options.maxBufferSize]
  * @returns {SyncCPUProfileHandle}
  */
-function startCpuProfile() {
-  const id = _startCpuProfile();
+function startCpuProfile(options) {
+  const {
+    samplingIntervalMicros,
+    maxSamples,
+  } = normalizeCpuProfileOptions(options);
+  const id = _startCpuProfile(samplingIntervalMicros, maxSamples);
   return new SyncCPUProfileHandle(id);
 }
 

src/env.cc

@@ -2264,14 +2264,18 @@ void Environment::RunWeakRefCleanup() {
   isolate()->ClearKeptObjects();
 }
 
-v8::CpuProfilingResult Environment::StartCpuProfile() {
+v8::CpuProfilingResult Environment::StartCpuProfile(
+    const CpuProfileOptions& options) {
   HandleScope handle_scope(isolate());
   if (!cpu_profiler_) {
     cpu_profiler_ = v8::CpuProfiler::New(isolate());
   }
-  v8::CpuProfilingResult result = cpu_profiler_->Start(
-      v8::CpuProfilingOptions{v8::CpuProfilingMode::kLeafNodeLineNumbers,
-                              v8::CpuProfilingOptions::kNoSampleLimit});
+  v8::CpuProfilingOptions start_options(
+      v8::CpuProfilingMode::kLeafNodeLineNumbers,
+      options.max_samples,
+      options.sampling_interval_us);
+  v8::CpuProfilingResult result =
+      cpu_profiler_->Start(std::move(start_options));
   if (result.status == v8::CpuProfilingStatus::kStarted) {
     pending_profiles_.push_back(result.id);
   }

src/env.h

@@ -1053,7 +1053,7 @@ class Environment final : public MemoryRetainer {
 
   inline void RemoveHeapSnapshotNearHeapLimitCallback(size_t heap_limit);
 
-  v8::CpuProfilingResult StartCpuProfile();
+  v8::CpuProfilingResult StartCpuProfile(const CpuProfileOptions& options);
   v8::CpuProfile* StopCpuProfile(v8::ProfilerId profile_id);
 
   // Field identifiers for exit_info_

src/node_v8.cc

@@ -250,7 +250,8 @@ void SetFlagsFromString(const FunctionCallbackInfo<Value>& args) {
 void StartCpuProfile(const FunctionCallbackInfo<Value>& args) {
   Environment* env = Environment::GetCurrent(args);
   Isolate* isolate = env->isolate();
-  CpuProfilingResult result = env->StartCpuProfile();
+  CpuProfileOptions options = ParseCpuProfileOptions(args);
+  CpuProfilingResult result = env->StartCpuProfile(options);
   if (result.status == CpuProfilingStatus::kErrorTooManyProfilers) {
     return THROW_ERR_CPU_PROFILE_TOO_MANY(isolate,
                                           "There are too many CPU profiles");

src/node_worker.cc

@@ -923,6 +923,7 @@ void Worker::StartCpuProfile(const FunctionCallbackInfo<Value>& args) {
   Worker* w;
   ASSIGN_OR_RETURN_UNWRAP(&w, args.This());
   Environment* env = w->env();
+  CpuProfileOptions options = ParseCpuProfileOptions(args);
 
   AsyncHooks::DefaultTriggerAsyncIdScope trigger_id_scope(w);
   Local<Object> wrap;
@@ -935,9 +936,9 @@ void Worker::StartCpuProfile(const FunctionCallbackInfo<Value>& args) {
   BaseObjectPtr<WorkerCpuProfileTaker> taker =
       MakeDetachedBaseObject<WorkerCpuProfileTaker>(env, wrap);
 
-  bool scheduled = w->RequestInterrupt([taker = std::move(taker),
-                                        env](Environment* worker_env) mutable {
-    CpuProfilingResult result = worker_env->StartCpuProfile();
+  bool scheduled = w->RequestInterrupt([taker = std::move(taker), env, options](
+                                           Environment* worker_env) mutable {
+    CpuProfilingResult result = worker_env->StartCpuProfile(options);
     env->SetImmediateThreadsafe(
         [taker = std::move(taker), result = result](Environment* env) mutable {
           Isolate* isolate = env->isolate();

src/util.cc

@@ -894,4 +894,18 @@ HeapProfileOptions ParseHeapProfileOptions(
   return options;
 }
 
+CpuProfileOptions ParseCpuProfileOptions(
+    const v8::FunctionCallbackInfo<v8::Value>& args) {
+  CpuProfileOptions options;
+  CHECK_LE(args.Length(), 2);
+  if (args.Length() > 0) {
+    CHECK(args[0]->IsInt32());
+    options.sampling_interval_us = args[0].As<v8::Int32>()->Value();
+  }
+  if (args.Length() > 1) {
+    CHECK(args[1]->IsUint32());
+    options.max_samples = args[1].As<v8::Uint32>()->Value();
+  }
+  return options;
+}
 }  // namespace node