feat: Capture thread state by calling global function

Author: timfish

.eslintrc.js

@@ -2,7 +2,7 @@ module.exports = {
   extends: ['@sentry-internal/sdk'],
   env: {
     node: true,
-    es6: true,
+    es2020: true
   },
   parserOptions: {
     sourceType: 'module',

README.md

@@ -107,23 +107,26 @@ Set up automatic detection of blocked event loops:
 
 ### 1. Set up thread heartbeats
 
-Send regular heartbeats with optional state information:
+Send regular heartbeats:
 
 ```ts
 import {
   registerThread,
   threadPoll,
 } from "@sentry-internal/node-native-stacktrace";
 
+// Register a global function called `__get_thread_state_callback__` that is called when
+// event loop is blocked to get the current thread state. This must return a serializable object.
+globalThis.__get_thread_state_callback__ = () => {
+  return { some_property: "some_value" };
+};
+
 // Register this thread
 registerThread();
 
-// Send heartbeats every 200ms with optional state
+// Send heartbeats every 200ms
 setInterval(() => {
-  threadPoll({
-    endpoint: "/api/current-request",
-    userId: getCurrentUserId(),
-  });
+  threadPoll();
 }, 200);
 ```
 
@@ -187,14 +190,10 @@ type StackFrame = {
 };
 ```
 
-#### `threadPoll<State>(state?: State, disableLastSeen?: boolean): void`
+#### `threadPoll<State>(disableLastSeen?: boolean): void`
 
-Sends a heartbeat from the current thread with optional state information. The
-state object will be serialized and included as a JavaScript object with the
-corresponding stack trace.
+Sends a heartbeat from the current thread.
 
-- `state` (optional): An object containing state information to include with the
-  stack trace.
 - `disableLastSeen` (optional): If `true`, disables the tracking of the last
   seen time for this thread.
 

module.cc

@@ -16,16 +16,14 @@ using namespace v8;
 using namespace node;
 using namespace std::chrono;
 
-static const int kMaxStackFrames = 255;
+static const int kMaxStackFrames = 50;
 
 // Structure to hold information for each thread/isolate
 struct ThreadInfo {
   // Thread name
   std::string thread_name;
   // Last time this thread was seen in milliseconds since epoch
   milliseconds last_seen;
-  // Some JSON serialized state for the thread
-  std::string state;
 };
 
 static std::mutex threads_mutex;
@@ -41,21 +39,26 @@ struct JsStackFrame {
 };
 
 // Type alias for a vector of JsStackFrame
-using JsStackTrace = std::vector<JsStackFrame>;
+using JsStackFrames = std::vector<JsStackFrame>;
+
+struct JsStackTrace {
+  // The frames in the stack trace
+  std::vector<JsStackFrame> frames;
+  // JSON serialized string of the state
+  std::string state;
+};
 
 struct ThreadResult {
   std::string thread_name;
-  std::string state;
-  JsStackTrace stack_frames;
+  JsStackTrace stack_trace;
 };
 
-// Function to be called when an isolate's execution is interrupted
-static void ExecutionInterrupted(Isolate *isolate, void *data) {
-  auto promise = static_cast<std::promise<JsStackTrace> *>(data);
+// Function to get stack frames from a V8 stack trace
+JsStackFrames GetStackFrames(Isolate *isolate) {
   auto stack = StackTrace::CurrentStackTrace(isolate, kMaxStackFrames,
                                              StackTrace::kDetailed);
 
-  JsStackTrace frames;
+  JsStackFrames frames;
   if (!stack.IsEmpty()) {
     for (int i = 0; i < stack->GetFrameCount(); i++) {
       auto frame = stack->GetFrame(isolate, i);
@@ -89,7 +92,45 @@ static void ExecutionInterrupted(Isolate *isolate, void *data) {
     }
   }
 
-  promise->set_value(frames);
+  return frames;
+}
+
+// Function to fetch the thread state from the isolate by calling a global
+// function called __get_thread_state_callback__
+std::string GetThreadState(Isolate *isolate) {
+  auto callback_name =
+      v8::String::NewFromUtf8(isolate, "__get_thread_state_callback__",
+                              v8::NewStringType::kNormal)
+          .ToLocalChecked();
+  auto context = isolate->GetCurrentContext();
+  auto callback =
+      context->Global()->Get(context, callback_name).ToLocalChecked();
+
+  if (callback->IsFunction()) {
+    v8::TryCatch try_catch(isolate);
+
+    auto result = Local<Function>::Cast(callback)->Call(
+        context, Undefined(isolate), 0, {});
+
+    MaybeLocal<String> maybe_json =
+        v8::JSON::Stringify(context, result.ToLocalChecked());
+
+    if (!maybe_json.IsEmpty()) {
+      v8::String::Utf8Value utf8_state(isolate, maybe_json.ToLocalChecked());
+      if (*utf8_state) {
+        return *utf8_state;
+      }
+    }
+  }
+
+  return "";
+}
+
+// Function to be called when an isolate's execution is interrupted
+static void ExecutionInterrupted(Isolate *isolate, void *data) {
+  auto promise = static_cast<std::promise<JsStackTrace> *>(data);
+
+  promise->set_value({GetStackFrames(isolate), GetThreadState(isolate)});
 }
 
 // Function to capture the stack trace of a single isolate
@@ -116,12 +157,11 @@ void CaptureStackTraces(const FunctionCallbackInfo<Value> &args) {
       if (thread_isolate == capture_from_isolate)
         continue;
       auto thread_name = thread_info.thread_name;
-      auto state = thread_info.state;
 
       futures.emplace_back(std::async(
           std::launch::async,
-          [thread_name, state](Isolate *isolate) -> ThreadResult {
-            return ThreadResult{thread_name, state, CaptureStackTrace(isolate)};
+          [thread_name](Isolate *isolate) -> ThreadResult {
+            return ThreadResult{thread_name, CaptureStackTrace(isolate)};
           },
           thread_isolate));
     }
@@ -137,9 +177,9 @@ void CaptureStackTraces(const FunctionCallbackInfo<Value> &args) {
             .ToLocalChecked();
 
     Local<Array> jsFrames =
-        Array::New(capture_from_isolate, result.stack_frames.size());
-    for (size_t i = 0; i < result.stack_frames.size(); ++i) {
-      const auto &frame = result.stack_frames[i];
+        Array::New(capture_from_isolate, result.stack_trace.frames.size());
+    for (size_t i = 0; i < result.stack_trace.frames.size(); ++i) {
+      const auto &frame = result.stack_trace.frames[i];
       Local<Object> frameObj = Object::New(capture_from_isolate);
       frameObj
           ->Set(current_context,
@@ -189,9 +229,10 @@ void CaptureStackTraces(const FunctionCallbackInfo<Value> &args) {
               jsFrames)
         .Check();
 
-    if (!result.state.empty()) {
+    if (!result.stack_trace.state.empty()) {
       v8::MaybeLocal<v8::String> stateStr = v8::String::NewFromUtf8(
-          capture_from_isolate, result.state.c_str(), NewStringType::kNormal);
+          capture_from_isolate, result.stack_trace.state.c_str(),
+          NewStringType::kNormal);
       if (!stateStr.IsEmpty()) {
         v8::MaybeLocal<v8::Value> maybeStateVal =
             v8::JSON::Parse(current_context, stateStr.ToLocalChecked());
@@ -243,8 +284,7 @@ void RegisterThread(const FunctionCallbackInfo<Value> &args) {
     std::lock_guard<std::mutex> lock(threads_mutex);
     auto found = threads.find(isolate);
     if (found == threads.end()) {
-      threads.emplace(isolate,
-                      ThreadInfo{thread_name, milliseconds::zero(), ""});
+      threads.emplace(isolate, ThreadInfo{thread_name, milliseconds::zero()});
       // Register a cleanup hook to remove this thread when the isolate is
       // destroyed
       node::AddEnvironmentCleanupHook(isolate, Cleanup, isolate);
@@ -280,32 +320,17 @@ steady_clock::time_point GetUnbiasedMonotonicTime() {
 // Function to track a thread and set its state
 void ThreadPoll(const FunctionCallbackInfo<Value> &args) {
   auto isolate = args.GetIsolate();
-  auto context = isolate->GetCurrentContext();
-
-  std::string state_str;
-  if (args.Length() > 0 && args[0]->IsValue()) {
-    MaybeLocal<String> maybe_json = v8::JSON::Stringify(context, args[0]);
-    if (!maybe_json.IsEmpty()) {
-      v8::String::Utf8Value utf8_state(isolate, maybe_json.ToLocalChecked());
-      state_str = *utf8_state ? *utf8_state : "";
-    } else {
-      state_str = "";
-    }
-  } else {
-    state_str = "";
-  }
 
   bool disable_last_seen = false;
-  if (args.Length() > 1 && args[1]->IsBoolean()) {
-    disable_last_seen = args[1]->BooleanValue(isolate);
+  if (args.Length() > 0 && args[0]->IsBoolean()) {
+    disable_last_seen = args[0]->BooleanValue(isolate);
   }
 
   {
     std::lock_guard<std::mutex> lock(threads_mutex);
     auto found = threads.find(isolate);
     if (found != threads.end()) {
       auto &thread_info = found->second;
-      thread_info.state = state_str;
       if (disable_last_seen) {
         thread_info.last_seen = milliseconds::zero();
       } else {

src/index.ts

@@ -25,7 +25,7 @@ type StackFrame = {
 
 interface Native {
   registerThread(threadName: string): void;
-  threadPoll(state?: object, disableLastSeen?: boolean): void;
+  threadPoll(disableLastSeen?: boolean): void;
   captureStackTrace<S = unknown>(): Record<string, Thread<S>>;
   getThreadsLastSeen(): Record<string, number>;
 }
@@ -186,12 +186,11 @@ export function registerThread(threadName: string = String(threadId)): void {
 /**
  * Tells the native module that the thread is still running and updates the state.
  *
- * @param state Optional state to pass to the native module.
  * @param disableLastSeen If true, disables the last seen tracking for this thread.
  */
-export function threadPoll(state?: object, disableLastSeen?: boolean): void {
-  if (typeof state === 'object' || disableLastSeen) {
-    native.threadPoll(state, disableLastSeen);
+export function threadPoll(disableLastSeen?: boolean): void {
+  if (disableLastSeen) {
+    native.threadPoll(disableLastSeen);
   } else {
     native.threadPoll();
   }

test/stalled-disabled.js

@@ -2,10 +2,14 @@ const { Worker } = require('node:worker_threads');
 const { longWork } = require('./long-work.js');
 const { registerThread, threadPoll } = require('@sentry-internal/node-native-stacktrace');
 
+globalThis.__get_thread_state_callback__ = () => {
+  return { some_property: 'some_value' };
+}
+
 registerThread();
 
 setInterval(() => {
-  threadPoll({ some_property: 'some_value' }, true);
+  threadPoll(true);
 }, 200).unref();
 
 const watchdog = new Worker('./test/stalled-watchdog.js');

test/stalled.js

@@ -2,10 +2,14 @@ const { Worker } = require('node:worker_threads');
 const { longWork } = require('./long-work.js');
 const { registerThread, threadPoll } = require('@sentry-internal/node-native-stacktrace');
 
+globalThis.__get_thread_state_callback__ = () => {
+  return { some_property: 'some_value' };
+}
+
 registerThread();
 
 setInterval(() => {
-  threadPoll({ some_property: 'some_value' });
+  threadPoll();
 }, 200).unref();
 
 const watchdog = new Worker('./test/stalled-watchdog.js');