Skip to content

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

Open
orgads wants to merge 1 commit into
nodejs:mainfrom
orgads:trace-sigterm
Open

orgads wants to merge 1 commit into
nodejs:mainfrom
orgads:trace-sigterm

Conversation

@orgads

@orgads orgads commented Aug 2, 2026

Copy link
Copy Markdown
Contributor

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.

Fixes: #56879

@nodejs-github-bot

Copy link
Copy Markdown
Collaborator

Review requested:

  • @nodejs/config
  • @nodejs/startup

@nodejs-github-bot nodejs-github-bot added c++ Issues and PRs that require attention from people who are familiar with C++. lib / src Issues and PRs involving general changes in the lib/ or src/ directories. needs-ci PRs that need a full CI run. labels Aug 2, 2026
@orgads
orgads force-pushed the trace-sigterm branch 3 times, most recently from 9124e14 to cc351cd Compare August 2, 2026 06:29
@codecov

codecov Bot commented Aug 2, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 5.35714% with 53 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.63%. Comparing base (3983092) to head (44422b9).
⚠️ Report is 1 commits behind head on main.

Files with missing lines Patch % Lines
src/node_watchdog.cc 0.00% 50 Missing ⚠️
src/node.cc 0.00% 2 Missing and 1 partial ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main   #64948      +/-   ##
==========================================
- Coverage   92.96%   90.63%   -2.33%     
==========================================
  Files         428      797     +369     
  Lines      195232   278318   +83086     
  Branches    30184    53519   +23335     
==========================================
+ Hits       181492   252266   +70774     
- Misses      13413    16437    +3024     
- Partials      327     9615    +9288     
Files with missing lines Coverage Δ
src/node_options.cc 88.20% <100.00%> (ø)
src/node_options.h 95.72% <100.00%> (ø)
src/node_watchdog.h 44.44% <ø> (ø)
src/node.cc 79.55% <0.00%> (ø)
src/node_watchdog.cc 71.67% <0.00%> (ø)

... and 497 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@orgads
orgads force-pushed the trace-sigterm branch 2 times, most recently from dd4a298 to 9002423 Compare August 26, 2026 19:32
@orgads

orgads commented Aug 27, 2026

Copy link
Copy Markdown
Contributor Author

Rebased

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: nodejs#56879
Signed-off-by: Orgad Shaneh <orgad.shaneh@audiocodes.com>
@orgads

orgads commented Oct 26, 2026

Copy link
Copy Markdown
Contributor Author

Rebased

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

c++ Issues and PRs that require attention from people who are familiar with C++. lib / src Issues and PRs involving general changes in the lib/ or src/ directories. needs-ci PRs that need a full CI run.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Support printing backtrace also on SIGTERM

2 participants