From cc351cd6db825a57ccd447643592d758bc5a7902 Mon Sep 17 00:00:00 2001
From: Orgad Shaneh <orgad.shaneh@audiocodes.com>
Date: Sun, 2 Aug 2026 00:14:04 +0300
Subject: [PATCH] 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: https://github.com/nodejs/node/issues/56879
Signed-off-by: Orgad Shaneh <orgad.shaneh@audiocodes.com>
---
 doc/api/cli.md                      | 14 +++++
 doc/node-config-schema.json         |  4 ++
 doc/node.1                          |  9 ++++
 src/node.cc                         |  4 ++
 src/node_options.cc                 |  5 ++
 src/node_options.h                  |  1 +
 src/node_watchdog.cc                | 84 +++++++++++++++++++++++++++++
 src/node_watchdog.h                 | 28 ++++++++++
 test/parallel/test-trace-sigterm.js | 56 +++++++++++++++++++
 9 files changed, 205 insertions(+)
 create mode 100644 test/parallel/test-trace-sigterm.js

diff --git a/doc/api/cli.md b/doc/api/cli.md
index 9434e19d3b73..fe6422392251 100644
--- a/doc/api/cli.md
+++ b/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`
diff --git a/doc/node-config-schema.json b/doc/node-config-schema.json
index 116f0c286818..429505657938 100644
--- a/doc/node-config-schema.json
+++ b/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"
diff --git a/doc/node.1 b/doc/node.1
index 05b80da80a43..42fd2c80808d 100644
--- a/doc/node.1
+++ b/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
diff --git a/src/node.cc b/src/node.cc
index b368c5873434..0f5c4e699282 100644
--- a/src/node.cc
+++ b/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
diff --git a/src/node_options.cc b/src/node_options.cc
index 383522863bb8..0f13ab51f9ba 100644
--- a/src/node_options.cc
+++ b/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",
diff --git a/src/node_options.h b/src/node_options.h
index fc758f2444aa..a827ae5eabc5 100644
--- a/src/node_options.h
+++ b/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();
diff --git a/src/node_watchdog.cc b/src/node_watchdog.cc
index f9bfa0e0c86f..d8a48b365093 100644
--- a/src/node_watchdog.cc
+++ b/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");
diff --git a/src/node_watchdog.h b/src/node_watchdog.h
index 096e347d7b3f..c06cd794b8e7 100644
--- a/src/node_watchdog.h
+++ b/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; }
diff --git a/test/parallel/test-trace-sigterm.js b/test/parallel/test-trace-sigterm.js
new file mode 100644
index 000000000000..3fd4c625a371
--- /dev/null
+++ b/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');