From 4797934e6a50f63dc09579c3ca8d382adfbc82bd Mon Sep 17 00:00:00 2001
From: theanarkh <theratliter@gmail.com>
Date: Sun, 10 Aug 2025 15:17:05 +0800
Subject: [PATCH] worker: add cpu profile APIs for worker

---
 doc/api/errors.md                             |  30 ++++
 doc/api/worker_threads.md                     |  30 ++++
 lib/internal/worker.js                        |  36 +++++
 src/async_wrap.h                              |   1 +
 src/env.cc                                    |  36 +++++
 src/env.h                                     |   7 +
 src/env_properties.h                          |   1 +
 src/node_errors.h                             |   3 +
 src/node_worker.cc                            | 149 +++++++++++++++++-
 src/node_worker.h                             |   2 +
 src/util.h                                    |  21 +++
 test/parallel/test-worker-cpu-profile.js      |  73 +++++++++
 test/sequential/test-async-wrap-getasyncid.js |   1 +
 typings/internalBinding/worker.d.ts           |   1 +
 14 files changed, 390 insertions(+), 1 deletion(-)
 create mode 100644 test/parallel/test-worker-cpu-profile.js

diff --git a/doc/api/errors.md b/doc/api/errors.md
index 7cd23e05a21701..962e011bea5bd5 100644
--- a/doc/api/errors.md
+++ b/doc/api/errors.md
@@ -826,6 +826,36 @@ when an error occurs (and is caught) during the creation of the
 context, for example, when the allocation fails or the maximum call stack
 size is reached when the context is created.
 
+<a id="ERR_CPU_PROFILE_ALREADY_STARTED"></a>
+
+### `ERR_CPU_PROFILE_ALREADY_STARTED`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+The CPU profile with the given name is already started.
+
+<a id="ERR_CPU_PROFILE_NOT_STARTED"></a>
+
+### `ERR_CPU_PROFILE_NOT_STARTED`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+The CPU profile with the given name is not started.
+
+<a id="ERR_CPU_PROFILE_TOO_MANY"></a>
+
+### `ERR_CPU_PROFILE_TOO_MANY`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+There are too many CPU profiles being collected.
+
 <a id="ERR_CRYPTO_ARGON2_NOT_SUPPORTED"></a>
 
 ### `ERR_CRYPTO_ARGON2_NOT_SUPPORTED`
diff --git a/doc/api/worker_threads.md b/doc/api/worker_threads.md
index d287bef25f21f8..f937a2004b7cb8 100644
--- a/doc/api/worker_threads.md
+++ b/doc/api/worker_threads.md
@@ -1957,6 +1957,36 @@ this matches its values.
 
 If the worker has stopped, the return value is an empty object.
 
+### `worker.startCpuProfile(name)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* name: {string}
+* Returns: {Promise}
+
+Starting a CPU profile with the given `name`, then return a Promise that fulfills
+with an error or an object which has a `stop` method. Calling the `stop` method will
+stop collecting the profile, then return a Promise that fulfills with an error or the
+profile data.
+
+```cjs
+const { Worker } = require('node:worker_threads');
+
+const worker = new Worker(`
+  const { parentPort } = require('worker_threads');
+  parentPort.on('message', () => {});
+  `, { eval: true });
+
+worker.on('online', async () => {
+  const handle = await worker.startCpuProfile('demo');
+  const profile = await handle.stop();
+  console.log(profile);
+  worker.terminate();
+});
+```
+
 ### `worker.stderr`
 
 <!-- YAML
diff --git a/lib/internal/worker.js b/lib/internal/worker.js
index 2457db85dd3fe8..bed1527921681b 100644
--- a/lib/internal/worker.js
+++ b/lib/internal/worker.js
@@ -506,6 +506,42 @@ class Worker extends EventEmitter {
       };
     });
   }
+
+  // TODO(theanarkh): add options, such as sample_interval, CpuProfilingMode
+  startCpuProfile(name) {
+    validateString(name, 'name');
+    const startTaker = this[kHandle]?.startCpuProfile(name);
+    return new Promise((resolve, reject) => {
+      if (!startTaker) return reject(new ERR_WORKER_NOT_RUNNING());
+      startTaker.ondone = (err) => {
+        if (err) {
+          return reject(err);
+        }
+        let promise = null;
+        const stop = () => {
+          if (promise) {
+            return promise;
+          }
+          const stopTaker = this[kHandle]?.stopCpuProfile(name);
+          return promise = new Promise((resolve, reject) => {
+            if (!stopTaker) return reject(new ERR_WORKER_NOT_RUNNING());
+            stopTaker.ondone = (status, profile) => {
+              if (err) {
+                return reject(err);
+              }
+              resolve(profile);
+            };
+          });
+        };
+        resolve({
+          stop,
+          async [SymbolAsyncDispose]() {
+            await stop();
+          },
+        });
+      };
+    });
+  }
 }
 
 /**
diff --git a/src/async_wrap.h b/src/async_wrap.h
index 0eec5f3f1a7a5b..1d7522f6ffe6e2 100644
--- a/src/async_wrap.h
+++ b/src/async_wrap.h
@@ -79,6 +79,7 @@ namespace node {
   V(UDPWRAP)                                                                   \
   V(SIGINTWATCHDOG)                                                            \
   V(WORKER)                                                                    \
+  V(WORKERCPUPROFILE)                                                          \
   V(WORKERCPUUSAGE)                                                            \
   V(WORKERHEAPSNAPSHOT)                                                        \
   V(WORKERHEAPSTATISTICS)                                                      \
diff --git a/src/env.cc b/src/env.cc
index 052d3ba0b5a782..0253004c80cb03 100644
--- a/src/env.cc
+++ b/src/env.cc
@@ -1062,6 +1062,13 @@ Environment::~Environment() {
   }
 
   delete external_memory_accounter_;
+  if (cpu_profiler_) {
+    for (auto& it : pending_profiles_) {
+      cpu_profiler_->Stop(it.second);
+    }
+    cpu_profiler_->Dispose();
+    cpu_profiler_ = nullptr;
+  }
 }
 
 void Environment::InitializeLibuv() {
@@ -2225,4 +2232,33 @@ void Environment::MemoryInfo(MemoryTracker* tracker) const {
 void Environment::RunWeakRefCleanup() {
   isolate()->ClearKeptObjects();
 }
+
+v8::CpuProfilingResult Environment::StartCpuProfile(std::string_view name) {
+  HandleScope handle_scope(isolate());
+  if (!cpu_profiler_) {
+    cpu_profiler_ = v8::CpuProfiler::New(isolate());
+  }
+  Local<Value> title =
+      node::ToV8Value(context(), name, isolate()).ToLocalChecked();
+  v8::CpuProfilingResult result =
+      cpu_profiler_->Start(title.As<String>(), true);
+  if (result.status == v8::CpuProfilingStatus::kStarted) {
+    pending_profiles_.emplace(name, result.id);
+  }
+  return result;
+}
+
+v8::CpuProfile* Environment::StopCpuProfile(std::string_view name) {
+  if (!cpu_profiler_) {
+    return nullptr;
+  }
+  auto it = pending_profiles_.find(std::string(name));
+  if (it == pending_profiles_.end()) {
+    return nullptr;
+  }
+  v8::CpuProfile* profile = cpu_profiler_->Stop(it->second);
+  pending_profiles_.erase(it);
+  return profile;
+}
+
 }  // namespace node
diff --git a/src/env.h b/src/env.h
index 5540ae6b6f0a9e..753dc5ec422d4d 100644
--- a/src/env.h
+++ b/src/env.h
@@ -49,6 +49,7 @@
 #include "util.h"
 #include "uv.h"
 #include "v8-external-memory-accounter.h"
+#include "v8-profiler.h"
 #include "v8.h"
 
 #if HAVE_OPENSSL
@@ -1048,6 +1049,9 @@ class Environment final : public MemoryRetainer {
 
   inline void RemoveHeapSnapshotNearHeapLimitCallback(size_t heap_limit);
 
+  v8::CpuProfilingResult StartCpuProfile(std::string_view name);
+  v8::CpuProfile* StopCpuProfile(std::string_view name);
+
   // Field identifiers for exit_info_
   enum ExitInfoField {
     kExiting = 0,
@@ -1244,6 +1248,9 @@ class Environment final : public MemoryRetainer {
   // track of the BackingStore for a given pointer.
   std::unordered_map<char*, std::unique_ptr<v8::BackingStore>>
       released_allocated_buffers_;
+
+  v8::CpuProfiler* cpu_profiler_ = nullptr;
+  std::unordered_map<std::string, v8::ProfilerId> pending_profiles_;
 };
 
 }  // namespace node
diff --git a/src/env_properties.h b/src/env_properties.h
index 3687027c8ae939..cd4ee578ce8ee0 100644
--- a/src/env_properties.h
+++ b/src/env_properties.h
@@ -486,6 +486,7 @@
   V(tcp_constructor_template, v8::FunctionTemplate)                            \
   V(tty_constructor_template, v8::FunctionTemplate)                            \
   V(write_wrap_template, v8::ObjectTemplate)                                   \
+  V(worker_cpu_profile_taker_template, v8::ObjectTemplate)                     \
   V(worker_cpu_usage_taker_template, v8::ObjectTemplate)                       \
   V(worker_heap_snapshot_taker_template, v8::ObjectTemplate)                   \
   V(worker_heap_statistics_taker_template, v8::ObjectTemplate)                 \
diff --git a/src/node_errors.h b/src/node_errors.h
index 09fe51d6f79825..27116ecade138d 100644
--- a/src/node_errors.h
+++ b/src/node_errors.h
@@ -48,6 +48,9 @@ void OOMErrorHandler(const char* location, const v8::OOMDetails& details);
   V(ERR_CLOSED_MESSAGE_PORT, Error)                                            \
   V(ERR_CONSTRUCT_CALL_REQUIRED, TypeError)                                    \
   V(ERR_CONSTRUCT_CALL_INVALID, TypeError)                                     \
+  V(ERR_CPU_PROFILE_ALREADY_STARTED, Error)                                    \
+  V(ERR_CPU_PROFILE_NOT_STARTED, Error)                                        \
+  V(ERR_CPU_PROFILE_TOO_MANY, Error)                                           \
   V(ERR_CRYPTO_CUSTOM_ENGINE_NOT_SUPPORTED, Error)                             \
   V(ERR_CRYPTO_INITIALIZATION_FAILED, Error)                                   \
   V(ERR_CRYPTO_INVALID_ARGON2_PARAMS, TypeError)                               \
diff --git a/src/node_worker.cc b/src/node_worker.cc
index e00a5d60d1295c..b1ebcc64740e91 100644
--- a/src/node_worker.cc
+++ b/src/node_worker.cc
@@ -12,6 +12,7 @@
 #include "permission/permission.h"
 #include "util-inl.h"
 #include "v8-cppgc.h"
+#include "v8-profiler.h"
 
 #include <memory>
 #include <string>
@@ -23,6 +24,9 @@ using v8::Array;
 using v8::ArrayBuffer;
 using v8::Boolean;
 using v8::Context;
+using v8::CpuProfile;
+using v8::CpuProfilingResult;
+using v8::CpuProfilingStatus;
 using v8::Float64Array;
 using v8::FunctionCallbackInfo;
 using v8::FunctionTemplate;
@@ -495,7 +499,6 @@ Worker::~Worker() {
   CHECK(stopped_);
   CHECK_NULL(env_);
   CHECK(!tid_.has_value());
-
   Debug(this, "Worker %llu destroyed", thread_id_.id);
 }
 
@@ -897,6 +900,132 @@ void Worker::CpuUsage(const FunctionCallbackInfo<Value>& args) {
   }
 }
 
+class WorkerCpuProfileTaker final : public AsyncWrap {
+ public:
+  WorkerCpuProfileTaker(Environment* env, Local<Object> obj)
+      : AsyncWrap(env, obj, AsyncWrap::PROVIDER_WORKERCPUPROFILE) {}
+
+  SET_NO_MEMORY_INFO()
+  SET_MEMORY_INFO_NAME(WorkerCpuProfileTaker)
+  SET_SELF_SIZE(WorkerCpuProfileTaker)
+};
+
+void Worker::StartCpuProfile(const FunctionCallbackInfo<Value>& args) {
+  Worker* w;
+  ASSIGN_OR_RETURN_UNWRAP(&w, args.This());
+  Environment* env = w->env();
+
+  CHECK(args[0]->IsString());
+  node::Utf8Value name(env->isolate(), args[0]);
+
+  AsyncHooks::DefaultTriggerAsyncIdScope trigger_id_scope(w);
+  Local<Object> wrap;
+  if (!env->worker_cpu_profile_taker_template()
+           ->NewInstance(env->context())
+           .ToLocal(&wrap)) {
+    return;
+  }
+
+  BaseObjectPtr<WorkerCpuProfileTaker> taker =
+      MakeDetachedBaseObject<WorkerCpuProfileTaker>(env, wrap);
+
+  bool scheduled = w->RequestInterrupt([taker = std::move(taker),
+                                        name = name.ToString(),
+                                        env](Environment* worker_env) mutable {
+    CpuProfilingResult result = worker_env->StartCpuProfile(name);
+    env->SetImmediateThreadsafe(
+        [taker = std::move(taker),
+         status = result.status](Environment* env) mutable {
+          Isolate* isolate = env->isolate();
+          HandleScope handle_scope(isolate);
+          Context::Scope context_scope(env->context());
+          AsyncHooks::DefaultTriggerAsyncIdScope trigger_id_scope(taker.get());
+          Local<Value> argv[] = {
+              Null(isolate),  // error
+          };
+          if (status == CpuProfilingStatus::kAlreadyStarted) {
+            argv[0] = ERR_CPU_PROFILE_ALREADY_STARTED(
+                isolate, "CPU profile already started");
+          } else if (status == CpuProfilingStatus::kErrorTooManyProfilers) {
+            argv[0] = ERR_CPU_PROFILE_TOO_MANY(
+                isolate, "There are too many CPU profiles");
+          }
+          taker->MakeCallback(env->ondone_string(), arraysize(argv), argv);
+        },
+        CallbackFlags::kUnrefed);
+  });
+
+  if (scheduled) {
+    args.GetReturnValue().Set(wrap);
+  }
+}
+
+void Worker::StopCpuProfile(const FunctionCallbackInfo<Value>& args) {
+  Worker* w;
+  ASSIGN_OR_RETURN_UNWRAP(&w, args.This());
+
+  Environment* env = w->env();
+  CHECK(args[0]->IsString());
+  node::Utf8Value name(env->isolate(), args[0]);
+
+  AsyncHooks::DefaultTriggerAsyncIdScope trigger_id_scope(w);
+  Local<Object> wrap;
+  if (!env->worker_cpu_profile_taker_template()
+           ->NewInstance(env->context())
+           .ToLocal(&wrap)) {
+    return;
+  }
+
+  BaseObjectPtr<WorkerCpuProfileTaker> taker =
+      MakeDetachedBaseObject<WorkerCpuProfileTaker>(env, wrap);
+
+  bool scheduled = w->RequestInterrupt([taker = std::move(taker),
+                                        name = name.ToString(),
+                                        env](Environment* worker_env) mutable {
+    bool found = false;
+    auto json_out_stream = std::make_unique<node::JSONOutputStream>();
+    CpuProfile* profile = worker_env->StopCpuProfile(name);
+    if (profile) {
+      profile->Serialize(json_out_stream.get(),
+                         CpuProfile::SerializationFormat::kJSON);
+      profile->Delete();
+      found = true;
+    }
+    env->SetImmediateThreadsafe(
+        [taker = std::move(taker),
+         json_out_stream = std::move(json_out_stream),
+         found](Environment* env) mutable {
+          Isolate* isolate = env->isolate();
+          HandleScope handle_scope(isolate);
+          Context::Scope context_scope(env->context());
+          AsyncHooks::DefaultTriggerAsyncIdScope trigger_id_scope(taker.get());
+          Local<Value> argv[] = {
+              Null(isolate),       // error
+              Undefined(isolate),  // profile
+          };
+          if (found) {
+            Local<Value> result;
+            if (!ToV8Value(env->context(),
+                           json_out_stream->out_stream().str(),
+                           isolate)
+                     .ToLocal(&result)) {
+              return;
+            }
+            argv[1] = result;
+          } else {
+            argv[0] =
+                ERR_CPU_PROFILE_NOT_STARTED(isolate, "CPU profile not started");
+          }
+          taker->MakeCallback(env->ondone_string(), arraysize(argv), argv);
+        },
+        CallbackFlags::kUnrefed);
+  });
+
+  if (scheduled) {
+    args.GetReturnValue().Set(wrap);
+  }
+}
+
 class WorkerHeapStatisticsTaker : public AsyncWrap {
  public:
   WorkerHeapStatisticsTaker(Environment* env, Local<Object> obj)
@@ -1189,6 +1318,8 @@ void CreateWorkerPerIsolateProperties(IsolateData* isolate_data,
     SetProtoMethod(isolate, w, "loopStartTime", Worker::LoopStartTime);
     SetProtoMethod(isolate, w, "getHeapStatistics", Worker::GetHeapStatistics);
     SetProtoMethod(isolate, w, "cpuUsage", Worker::CpuUsage);
+    SetProtoMethod(isolate, w, "startCpuProfile", Worker::StartCpuProfile);
+    SetProtoMethod(isolate, w, "stopCpuProfile", Worker::StopCpuProfile);
 
     SetConstructorFunction(isolate, target, "Worker", w);
   }
@@ -1234,6 +1365,20 @@ void CreateWorkerPerIsolateProperties(IsolateData* isolate_data,
     isolate_data->set_worker_cpu_usage_taker_template(wst->InstanceTemplate());
   }
 
+  {
+    Local<FunctionTemplate> wst = NewFunctionTemplate(isolate, nullptr);
+
+    wst->InstanceTemplate()->SetInternalFieldCount(
+        WorkerCpuProfileTaker::kInternalFieldCount);
+    wst->Inherit(AsyncWrap::GetConstructorTemplate(isolate_data));
+
+    Local<String> wst_string =
+        FIXED_ONE_BYTE_STRING(isolate, "WorkerCpuProfileTaker");
+    wst->SetClassName(wst_string);
+    isolate_data->set_worker_cpu_profile_taker_template(
+        wst->InstanceTemplate());
+  }
+
   SetMethod(isolate, target, "getEnvMessagePort", GetEnvMessagePort);
 }
 
@@ -1311,6 +1456,8 @@ void RegisterExternalReferences(ExternalReferenceRegistry* registry) {
   registry->Register(Worker::LoopStartTime);
   registry->Register(Worker::GetHeapStatistics);
   registry->Register(Worker::CpuUsage);
+  registry->Register(Worker::StartCpuProfile);
+  registry->Register(Worker::StopCpuProfile);
 }
 
 }  // anonymous namespace
diff --git a/src/node_worker.h b/src/node_worker.h
index 54e76e5f98b26b..28f3ca3eedd4ef 100644
--- a/src/node_worker.h
+++ b/src/node_worker.h
@@ -82,6 +82,8 @@ class Worker : public AsyncWrap {
   static void GetHeapStatistics(
       const v8::FunctionCallbackInfo<v8::Value>& args);
   static void CpuUsage(const v8::FunctionCallbackInfo<v8::Value>& args);
+  static void StartCpuProfile(const v8::FunctionCallbackInfo<v8::Value>& args);
+  static void StopCpuProfile(const v8::FunctionCallbackInfo<v8::Value>& args);
 
  private:
   bool CreateEnvMessagePort(Environment* env);
diff --git a/src/util.h b/src/util.h
index 0719f7370fe64a..ad7138c4e2ba0c 100644
--- a/src/util.h
+++ b/src/util.h
@@ -26,6 +26,7 @@
 
 #include "uv.h"
 #include "v8-inspector.h"
+#include "v8-profiler.h"
 #include "v8.h"
 
 #include "node.h"
@@ -45,6 +46,7 @@
 #include <optional>
 #include <ranges>
 #include <set>
+#include <sstream>
 #include <string>
 #include <string_view>
 #include <type_traits>
@@ -1010,6 +1012,25 @@ v8::Maybe<int> GetValidFileMode(Environment* env,
                                 v8::Local<v8::Value> input,
                                 uv_fs_type type);
 
+class JSONOutputStream final : public v8::OutputStream {
+ public:
+  JSONOutputStream() = default;
+
+  int GetChunkSize() override { return 65536; }
+
+  void EndOfStream() override {}
+
+  WriteResult WriteAsciiChunk(char* data, const int size) override {
+    out_stream_.write(data, size);
+    return kContinue;
+  }
+
+  std::ostringstream& out_stream() { return out_stream_; }
+
+ private:
+  std::ostringstream out_stream_;
+};
+
 #ifdef _WIN32
 // Returns true if OS==Windows and filename ends in .bat or .cmd,
 // case insensitive.
diff --git a/test/parallel/test-worker-cpu-profile.js b/test/parallel/test-worker-cpu-profile.js
new file mode 100644
index 00000000000000..302feca2776298
--- /dev/null
+++ b/test/parallel/test-worker-cpu-profile.js
@@ -0,0 +1,73 @@
+'use strict';
+const common = require('../common');
+const assert = require('assert');
+const { Worker } = require('worker_threads');
+
+const worker = new Worker(`
+  const { parentPort } = require('worker_threads');
+  parentPort.on('message', () => {});
+  `, { eval: true });
+
+[
+  -1,
+  1.1,
+  NaN,
+  undefined,
+  {},
+  [],
+  null,
+  function() {},
+  Symbol(),
+  true,
+  Infinity,
+].forEach((name) => {
+  try {
+    worker.startCpuProfile(name);
+  } catch (e) {
+    assert.ok(/ERR_INVALID_ARG_TYPE/i.test(e.code));
+  }
+});
+
+const name = 'demo';
+
+worker.on('online', common.mustCall(async () => {
+  {
+    const handle = await worker.startCpuProfile(name);
+    JSON.parse(await handle.stop());
+    // Stop again
+    JSON.parse(await handle.stop());
+  }
+
+  {
+    const [handle1, handle2] = await Promise.all([
+      worker.startCpuProfile('demo1'),
+      worker.startCpuProfile('demo2'),
+    ]);
+    const [profile1, profile2] = await Promise.all([
+      handle1.stop(),
+      handle2.stop(),
+    ]);
+    JSON.parse(profile1);
+    JSON.parse(profile2);
+  }
+
+  {
+    // Calling startCpuProfile twice with same name will throw an error
+    await worker.startCpuProfile(name);
+    try {
+      await worker.startCpuProfile(name);
+    } catch (e) {
+      assert.ok(/ERR_CPU_PROFILE_ALREADY_STARTED/i.test(e.code));
+    }
+    // Does not need to stop the profile because it will be stopped
+    // automatically when the worker is terminated
+  }
+
+  worker.terminate();
+}));
+
+worker.once('exit', common.mustCall(async () => {
+  await assert.rejects(worker.startCpuProfile(name), {
+    code: 'ERR_WORKER_NOT_RUNNING'
+  });
+}));
diff --git a/test/sequential/test-async-wrap-getasyncid.js b/test/sequential/test-async-wrap-getasyncid.js
index 6d454b40f0146f..7f4acbf966c76f 100644
--- a/test/sequential/test-async-wrap-getasyncid.js
+++ b/test/sequential/test-async-wrap-getasyncid.js
@@ -64,6 +64,7 @@ const { getSystemErrorName } = require('util');
     delete providers.WORKERHEAPSNAPSHOT;
     delete providers.WORKERHEAPSTATISTICS;
     delete providers.WORKERCPUUSAGE;
+    delete providers.WORKERCPUPROFILE;
     delete providers.BLOBREADER;
     delete providers.RANDOMPRIMEREQUEST;
     delete providers.CHECKPRIMEREQUEST;
diff --git a/typings/internalBinding/worker.d.ts b/typings/internalBinding/worker.d.ts
index 9dfd9776cec41c..7a609ca29a5b9e 100644
--- a/typings/internalBinding/worker.d.ts
+++ b/typings/internalBinding/worker.d.ts
@@ -17,6 +17,7 @@ declare namespace InternalWorkerBinding {
     takeHeapSnapshot(): object;
     getHeapStatistics(): Promise<object>;
     cpuUsage(): Promise<object>;
+    startCpuProfile(name): Promise<object>;
     loopIdleTime(): number;
     loopStartTime(): number;
   }