src: add --trace-sigterm to print a stack trace on SIGTERM

Neither `--report-on-signal` nor a `process.on('SIGTERM')` handler runs
while JavaScript is stuck, which is exactly when a trace is wanted: a
pod whose liveness probe stopped responding gets terminated with
SIGTERM, and there is currently no way to find out where it was stuck.

Print the stack trace from an interrupt instead, like `--trace-sigint`
does. The signal is watched through libuv on a dedicated thread and
event loop rather than through a signal handler of our own, so that it
stays multiplexed with `process.on('SIGTERM')` handlers: applications
that shut down gracefully are the ones most likely to have a handler
installed, and disabling the trace for them would defeat the purpose.

Watching the signal takes its default disposition away, so restore it
and re-raise once the trace has been printed, unless the application
handles SIGTERM itself, in which case libuv has already delivered the
signal to its handler as well.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Fixes: #56879
Signed-off-by: Orgad Shaneh <orgad.shaneh@audiocodes.com>

Author: orgads

doc/api/cli.md

@@ -3333,6 +3333,19 @@ added:
 
 Prints a stack trace on SIGINT.
 
+### `--trace-sigterm`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+Prints a stack trace on SIGTERM.
+
+Unlike a `SIGTERM` handler installed with `process.on('SIGTERM')`, the trace is
+also printed while JavaScript is stuck, for example in an infinite loop. If
+the application does not handle `SIGTERM` itself, the process is terminated by
+the signal as usual once the trace has been printed.
+
 ### `--trace-sync-io`
 
 <!-- YAML
@@ -3969,6 +3982,7 @@ one is included in the list below.
 * `--trace-exit`
 * `--trace-require-module`
 * `--trace-sigint`
+* `--trace-sigterm`
 * `--trace-sync-io`
 * `--trace-tls`
 * `--trace-uncaught`

doc/node-config-schema.json

@@ -716,6 +716,10 @@
               "type": "boolean",
               "description": "enable printing JavaScript stacktrace on SIGINT"
             },
+            "trace-sigterm": {
+              "type": "boolean",
+              "description": "enable printing JavaScript stacktrace on SIGTERM"
+            },
             "trace-sync-io": {
               "type": "boolean",
               "description": "show stack trace when use of sync IO is detected after the first tick"

doc/node.1

@@ -1609,6 +1609,13 @@ from the \fBnode_modules\fR folder is excluded.
 .It Fl -trace-sigint
 Prints a stack trace on SIGINT.
 .
+.It Fl -trace-sigterm
+Prints a stack trace on SIGTERM.
+Unlike a \fBSIGTERM\fR handler installed with \fBprocess.on('SIGTERM')\fR, the trace is
+also printed while JavaScript is stuck, for example in an infinite loop. If
+the application does not handle \fBSIGTERM\fR itself, the process is terminated by
+the signal as usual once the trace has been printed.
+.
 .It Fl -trace-sync-io
 Prints a stack trace whenever synchronous I/O is detected after the first turn
 of the event loop.
@@ -2211,6 +2218,8 @@ one is included in the list below.
 .It
 \fB--trace-sigint\fR
 .It
+\fB--trace-sigterm\fR
+.It
 \fB--trace-sync-io\fR
 .It
 \fB--trace-tls\fR

src/node.cc

@@ -46,6 +46,7 @@
 #include "node_snapshot_builder.h"
 #include "node_v8_platform-inl.h"
 #include "node_version.h"
+#include "node_watchdog.h"
 
 #if HAVE_OPENSSL
 #include "ncrypto.h"
@@ -248,6 +249,9 @@ void Environment::InitializeDiagnostics() {
   if (options_->trace_promises) {
     isolate_->SetPromiseHook(TracePromises);
   }
+  if (is_main_thread() && per_process::cli_options->trace_sigterm) {
+    TraceSigtermWatchdog::Enable(this);
+  }
 }
 
 static

src/node_options.cc

@@ -1520,6 +1520,11 @@ PerProcessOptionsParser::PerProcessOptionsParser(
             &PerProcessOptions::trace_sigint,
             kAllowedInEnvvar);
 
+  AddOption("--trace-sigterm",
+            "enable printing JavaScript stacktrace on SIGTERM",
+            &PerProcessOptions::trace_sigterm,
+            kAllowedInEnvvar);
+
   Insert(iop, &PerProcessOptions::get_per_isolate_options);
 
   AddOption("--node-memory-debug",

src/node_options.h

@@ -395,6 +395,7 @@ class PerProcessOptions : public Options {
   // TODO(addaleax): Some of these could probably be per-Environment.
   std::string use_largepages = "off";
   bool trace_sigint = false;
+  bool trace_sigterm = false;
   std::vector<std::string> cmdline;
 
   inline PerIsolateOptions* get_per_isolate_options();

src/node_watchdog.cc

@@ -20,6 +20,7 @@
 // USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 #include <algorithm>
+#include <csignal>
 
 #include "async_wrap-inl.h"
 #include "debug_utils-inl.h"
@@ -34,6 +35,7 @@ namespace node {
 using v8::Context;
 using v8::FunctionCallbackInfo;
 using v8::FunctionTemplate;
+using v8::HandleScope;
 using v8::Isolate;
 using v8::Local;
 using v8::Object;
@@ -228,6 +230,88 @@ void TraceSigintWatchdog::HandleInterrupt() {
   raise(SIGINT);
 }
 
+// Whether the main event loop watches `SIGTERM`, i.e. whether the application
+// installed its own handler through `process.on('SIGTERM')`.
+static bool HasSigtermListener(uv_loop_t* loop) {
+  bool found = false;
+  uv_walk(
+      loop,
+      [](uv_handle_t* handle, void* arg) {
+        if (handle->type == UV_SIGNAL && uv_is_active(handle) &&
+            reinterpret_cast<uv_signal_t*>(handle)->signum == SIGTERM) {
+          *static_cast<bool*>(arg) = true;
+        }
+      },
+      &found);
+  return found;
+}
+
+void TraceSigtermWatchdog::Enable(Environment* env) {
+  env->AddCleanupHook(
+      [](void* arg) { delete static_cast<TraceSigtermWatchdog*>(arg); },
+      new TraceSigtermWatchdog(env));
+}
+
+TraceSigtermWatchdog::TraceSigtermWatchdog(Environment* env) : env_(env) {
+  CHECK_EQ(uv_loop_init(&loop_), 0);
+  CHECK_EQ(uv_signal_init(&loop_, &signal_), 0);
+  signal_.data = this;
+  CHECK_EQ(uv_signal_start(
+               &signal_,
+               [](uv_signal_t* handle, int) {
+                 static_cast<TraceSigtermWatchdog*>(handle->data)->OnSignal();
+               },
+               SIGTERM),
+           0);
+  CHECK_EQ(
+      uv_async_init(
+          &loop_, &stop_, [](uv_async_t* handle) { uv_stop(handle->loop); }),
+      0);
+  CHECK_EQ(uv_thread_create(&thread_, Run, this), 0);
+}
+
+TraceSigtermWatchdog::~TraceSigtermWatchdog() {
+  CHECK_EQ(uv_async_send(&stop_), 0);
+  CHECK_EQ(uv_thread_join(&thread_), 0);
+
+  uv_close(reinterpret_cast<uv_handle_t*>(&signal_), nullptr);
+  uv_close(reinterpret_cast<uv_handle_t*>(&stop_), nullptr);
+
+  // UV_RUN_DEFAULT so that libuv has a chance to clean up.
+  uv_run(&loop_, UV_RUN_DEFAULT);
+
+  CheckedUvLoopClose(&loop_);
+}
+
+void TraceSigtermWatchdog::Run(void* arg) {
+  uv_thread_setname("SigtermWatchdog");
+  TraceSigtermWatchdog* wd = static_cast<TraceSigtermWatchdog*>(arg);
+
+  // The loop is stopped by the async handle.
+  uv_run(&wd->loop_, UV_RUN_DEFAULT);
+}
+
+void TraceSigtermWatchdog::OnSignal() {
+  // The callback runs on the main thread, either from a V8 interrupt (while
+  // JavaScript is running, which is where the stack trace comes from) or from
+  // the event loop, whichever gets there first.
+  env_->RequestInterrupt([](Environment* env) {
+    HandleScope handle_scope(env->isolate());
+    FPrintF(stderr,
+            "TERMINATE: Script execution was interrupted by `SIGTERM`\n");
+    PrintCurrentStackTrace(env->isolate());
+
+    // Watching the signal took the default disposition away, so restore it
+    // here. Applications that handle `SIGTERM` themselves are not affected:
+    // libuv has already delivered this signal to their handler as well.
+    if (!HasSigtermListener(env->event_loop())) {
+      ResetStdio();
+      signal(SIGTERM, SIG_DFL);
+      raise(SIGTERM);
+    }
+  });
+}
+
 #ifdef __POSIX__
 void* SigintWatchdogHelper::RunSigintWatchdog(void* arg) {
   uv_thread_setname("SigintWatchdog");

src/node_watchdog.h

@@ -117,6 +117,34 @@ class TraceSigintWatchdog : public HandleWrap, public SigintWatchdogBase {
   SignalFlags signal_flag_ = SignalFlags::None;
 };
 
+// Prints the JavaScript stack trace of the main thread when `SIGTERM` is
+// received, then lets `SIGTERM` take its usual course. It runs its own event
+// loop on a dedicated thread, because the main event loop is not reached while
+// JavaScript is stuck (which is exactly when the trace is interesting).
+// Watching the signal through libuv (rather than sigaction()) keeps it
+// multiplexed with `process.on('SIGTERM')` handlers.
+class TraceSigtermWatchdog {
+ public:
+  // Enables the watchdog for the lifetime of `env`.
+  static void Enable(Environment* env);
+
+ private:
+  explicit TraceSigtermWatchdog(Environment* env);
+  ~TraceSigtermWatchdog();
+
+  TraceSigtermWatchdog(const TraceSigtermWatchdog&) = delete;
+  TraceSigtermWatchdog& operator=(const TraceSigtermWatchdog&) = delete;
+
+  static void Run(void* arg);
+  void OnSignal();
+
+  Environment* env_;
+  uv_loop_t loop_;
+  uv_signal_t signal_;
+  uv_async_t stop_;
+  uv_thread_t thread_;
+};
+
 class SigintWatchdogHelper {
  public:
   static SigintWatchdogHelper* GetInstance() { return &instance; }

test/parallel/test-trace-sigterm.js

@@ -0,0 +1,56 @@
+'use strict';
+
+// Verifies that `--trace-sigterm` prints the JavaScript stack trace of a
+// process that is stuck in an infinite loop, both when the process handles
+// `SIGTERM` itself and when it does not.
+
+const common = require('../common');
+
+if (common.isWindows)
+  common.skip('SIGTERM is not sent to processes on Windows');
+
+const assert = require('assert');
+const { spawn } = require('child_process');
+
+const kMessage = 'TERMINATE: Script execution was interrupted by `SIGTERM`';
+// The frames are written separately from the message above.
+const kStackFrame = /^ {4}at .*test-trace-sigterm\.js:\d+/m;
+
+if (process.argv[2] === 'child') {
+  if (process.argv[3] === 'handled')
+    process.on('SIGTERM', () => {});
+  process.kill(process.pid, 'SIGTERM');
+  while (true) {
+    // Stuck, so that the trace has to come from an interrupt.
+  }
+}
+
+function run(mode, expectedSignal) {
+  const child = spawn(
+    process.execPath,
+    ['--trace-sigterm', __filename, 'child', mode],
+    { stdio: ['ignore', 'ignore', 'pipe'] });
+
+  let stderr = '';
+  child.stderr.setEncoding('utf8');
+  child.stderr.on('data', (chunk) => {
+    stderr += chunk;
+    // The handled case stays stuck, because its handler never gets to run.
+    if (mode === 'handled' && kStackFrame.test(stderr))
+      child.kill('SIGKILL');
+  });
+
+  child.on('exit', common.mustCall((code, signal) => {
+    assert.ok(stderr.includes(kMessage), stderr);
+    assert.match(stderr, kStackFrame);
+    assert.strictEqual(code, null);
+    assert.strictEqual(signal, expectedSignal);
+  }));
+}
+
+// Without a handler, the signal terminates the process as usual.
+run('unhandled', 'SIGTERM');
+
+// With a handler, `--trace-sigterm` does not terminate the process, so it is
+// killed above once the trace has been printed.
+run('handled', 'SIGKILL');