gh-149085: Add max_threads keyword to faulthandler.dump_traceback() by efroemling · Pull Request #149106 · python/cpython

efroemling · 2026-04-28T16:44:38Z

Adds a keyword-only max_threads argument to faulthandler.dump_traceback() and faulthandler.dump_traceback_later(), raising the per-call cap on the number of threads dumped (previously a hardcoded MAX_NTHREADS = 100 in Python/traceback.c). Default of 100 preserves existing behavior.

Motivation (covered in the issue): on server processes with many worker or gRPC threads, watchdog dumps silently lose the main thread because tstates are prepended to the interpreter's thread list and the cap chops the tail. This was the failure mode that prompted the issue.

Scope per @vstinner's confirmation in the issue: max_threads only; the frame/stack limits raised by @ZeroIntensity are left as-is for now.

The hardcoded 100 is moved to a new internal macro _Py_TRACEBACK_MAX_NTHREADS in pycore_traceback.h so the in-tree fatal-signal callers (faulthandler.c, pylifecycle.c) all share one source of truth.

Issue: faulthandler: make per-call thread dump cap configurable #149085

📚 Documentation preview 📚: https://cpython-previews--149106.org.readthedocs.build/

…ck() Add a keyword-only `max_threads` argument to `dump_traceback()` and `dump_traceback_later()`, defaulting to 100 to preserve existing behavior. Allows server processes with many worker threads to dump beyond the historical 100-thread cap (previously a hardcoded `MAX_NTHREADS = 100` in `Python/traceback.c`). The cap matters in practice: tstates are prepended to the PyInterpreterState linked list, so the dump walks newest-first. With more than 100 threads alive, the main thread (oldest, at the tail) is silently elided from watchdog dumps -- exactly the thread that's usually wanted. The hardcoded value is moved to a new internal macro `_Py_TRACEBACK_MAX_NTHREADS` in `pycore_traceback.h` so the in-tree fatal-signal callers all reference one source of truth.

read-the-docs-community · 2026-04-28T17:08:01Z

Documentation build overview

📚 cpython-previews | 🛠️ Build #32472695 | 📁 Comparing 1a6eead against main (8a8d737)

🔍 Preview build

6 files changed · ± 6 modified

± Modified

vstinner

I would prefer to also add max_threads parameter to enable().

- Drop _Py_TRACEBACK_MAX_NTHREADS macro; use 0 as sentinel for default 100 inside _Py_DumpTracebackThreads so internal callers don't have to pass the default explicitly. - Rename max_nthreads -> max_threads everywhere for naming consistency with the public Python kwarg. - Add max_threads kwarg to faulthandler.enable(); store in fatal_error.max_threads and pass through faulthandler_dump_traceback to the fatal-signal dump path on both POSIX and Windows. - Drop the three redundant explanatory comments vstinner flagged. - Doc: tighten the limitations bullet, drop implementation-detail mentions of the "..." truncation marker, switch versionchanged directives to "next", document the new enable() kwarg. - Tests: assertEqual exact count, check whole-line "\n...\n" marker, use script_helper.assert_python_ok, drop the default-value test, add test_enable_max_threads exercising the fatal-signal path. - NEWS: trim to two lines, mention all three functions.

efroemling · 2026-04-28T17:59:03Z

Thanks for the feedback.
I took a pass and tried to address everything (added max_threads to faulthandler.enable(), scaled back excessive comments, removed _Py_TRACEBACK_MAX_THREADS in favor of 0 for historical default, etc.).
Please holler if I missed anything or you notice anything else I can clean up or improve.

The fatal-signal handler only dumps the current thread when the GIL is disabled (pythongh-104812 / 3.14 versionchanged), so the truncation marker assertion in test_enable_max_threads fails on free-threading CI runs. Skip it there.

vstinner

Can you replace unsigned int max_threads with Py_ssize_t max_threads? Replace also unsigned int nthreads with Py_ssize_t nthreads in _Py_DumpTracebackThreads().

vstinner · 2026-04-29T11:19:52Z

        return;

-    faulthandler_dump_traceback(user->fd, user->all_threads, user->interp);
+    faulthandler_dump_traceback(user->fd, user->all_threads, user->interp, 0);


Please modify faulthandler.register() to add a max_threads parameter.

vstinner · 2026-04-29T11:31:21Z

I took a pass and tried to address everything (added max_threads to faulthandler.enable(), scaled back excessive comments, removed _Py_TRACEBACK_MAX_THREADS in favor of 0 for historical default, etc.).

Thanks for this big update!

ZeroIntensity

Please also add an entry to "What's New in Python 3.15".

@ZeroIntensity

- Add a 'faulthandler' entry to Doc/whatsnew/3.15.rst (per @ZeroIntensity). - Switch the max_threads parameters/fields and the nthreads loop counter in _Py_DumpTracebackThreads to Py_ssize_t (per @vstinner).

efroemling · 2026-04-29T14:48:31Z

Ok I added the whats-new entry and switched the max_size args to Py_ssize_t. 👍

vstinner · 2026-04-29T17:38:44Z

Can you also modify faulthandler.register() to add a max_threads parameter?

@vstinner

Per @vstinner's follow-up: also wire the kwarg through register() / faulthandler_user. Stored in the per-signal user_signal_t struct; the user-signal handler now passes user->max_threads to faulthandler_dump_traceback instead of 0. Doc, whatsnew, and NEWS entries updated to list all four functions.

Mirrors test_enable_max_threads but uses register(SIGUSR1, ...) + os.kill round-trip, matching the existing test_register_* pattern.

efroemling · 2026-04-29T18:19:06Z

Ok faulthandler.register() now has max_threads too. (and added an associated test). Holler if anything looks off there.

vstinner · 2026-04-29T19:49:06Z

+            ready.wait()
+            faulthandler.register(signal.SIGUSR1, all_threads=True,
+                                  max_threads=CAP)
+            os.kill(os.getpid(), signal.SIGUSR1)


To raise the signal, you can use:

Suggested change

os.kill(os.getpid(), signal.SIGUSR1)

signal.raise_signal(signal.SIGUSR1)

Can you use test_dump_traceback_max_threads() code to cleanup threads?

- Use signal.raise_signal() instead of os.kill(os.getpid(), ...). - Match test_dump_traceback_max_threads thread-cleanup pattern: keep refs, no daemon=True, set the stop event in a finally block, and join() the workers.

efroemling · 2026-04-29T20:53:32Z

Ok; switched to raise_signal() and now doing test_dump_traceback_max_threads() style cleanup

vstinner

LGTM.

vstinner · 2026-04-30T10:53:52Z

@ZeroIntensity: Do you want to double check the change?

It would be good to merge this change before next Tuesday to have it in Python 3.15 beta1.

ZeroIntensity

LGTM as well.

ZeroIntensity · 2026-04-30T13:28:47Z

Thanks for contributing :)

efroemling requested review from FFY00, ZeroIntensity and ericsnowcurrently as code owners April 28, 2026 16:44

bedevere-app Bot added the awaiting review label Apr 28, 2026

bedevere-app Bot mentioned this pull request Apr 28, 2026

faulthandler: make per-call thread dump cap configurable #149085

Closed

vstinner reviewed Apr 28, 2026

View reviewed changes

Skip test_enable_max_threads on free-threading builds

4689f4e

The fatal-signal handler only dumps the current thread when the GIL is disabled (pythongh-104812 / 3.14 versionchanged), so the truncation marker assertion in test_enable_max_threads fails on free-threading CI runs. Skip it there.

vstinner reviewed Apr 29, 2026

View reviewed changes

ZeroIntensity reviewed Apr 29, 2026

View reviewed changes

Address review iteration 2: whatsnew entry + Py_ssize_t

553c3a4

- Add a 'faulthandler' entry to Doc/whatsnew/3.15.rst (per @ZeroIntensity). - Switch the max_threads parameters/fields and the nthreads loop counter in _Py_DumpTracebackThreads to Py_ssize_t (per @vstinner).

efroemling requested a review from AA-Turner as a code owner April 29, 2026 14:43

efroemling added 2 commits April 29, 2026 11:11

Add test_register_max_threads

1a6eead

Mirrors test_enable_max_threads but uses register(SIGUSR1, ...) + os.kill round-trip, matching the existing test_register_* pattern.

vstinner reviewed Apr 29, 2026

View reviewed changes

Clean up test_register_max_threads per @vstinner

846ce34

- Use signal.raise_signal() instead of os.kill(os.getpid(), ...). - Match test_dump_traceback_max_threads thread-cleanup pattern: keep refs, no daemon=True, set the stop event in a finally block, and join() the workers.

vstinner mentioned this pull request Apr 30, 2026

Add PyUnstable_DumpTraceback() and PyUnstable_DumpTracebackThreads() capi-workgroup/decisions#101

Open

5 tasks

vstinner approved these changes Apr 30, 2026

View reviewed changes

bedevere-app Bot added awaiting merge and removed awaiting review labels Apr 30, 2026

ZeroIntensity approved these changes Apr 30, 2026

View reviewed changes

ZeroIntensity merged commit 7686abe into python:main Apr 30, 2026
57 checks passed

bedevere-app Bot removed the awaiting merge label Apr 30, 2026

	os.kill(os.getpid(), signal.SIGUSR1)
	signal.raise_signal(signal.SIGUSR1)

Uh oh!

Conversation

efroemling commented Apr 28, 2026 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

read-the-docs-community Bot commented Apr 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

vstinner left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

efroemling commented Apr 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vstinner left a comment

Choose a reason for hiding this comment

Uh oh!

vstinner Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

vstinner commented Apr 29, 2026

Uh oh!

ZeroIntensity left a comment

Choose a reason for hiding this comment

Uh oh!

efroemling commented Apr 29, 2026

Uh oh!

vstinner commented Apr 29, 2026

Uh oh!

efroemling commented Apr 29, 2026

Uh oh!

vstinner Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

efroemling commented Apr 29, 2026

Uh oh!

vstinner left a comment

Choose a reason for hiding this comment

Uh oh!

vstinner commented Apr 30, 2026

Uh oh!

ZeroIntensity left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ZeroIntensity commented Apr 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

efroemling commented Apr 28, 2026 •

edited by github-actions Bot

Loading

read-the-docs-community Bot commented Apr 28, 2026 •

edited

Loading

efroemling commented Apr 28, 2026 •

edited

Loading