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 #32456372 | 📁 Comparing 4689f4e against main (8a8d737)

🔍 Preview build

6 files changed · ± 6 modified

± Modified

vstinner

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

vstinner · 2026-04-28T17:00:56Z

    if (all_threads == 1) {
-        (void)_Py_DumpTracebackThreads(fd, NULL, tstate);
+        /* Fatal-signal path has no caller-supplied cap; use the
+           historical default. */


Can you modify faulthandler.enable() to add a max_threads parameter and store the value in fatal_error? See _faulthandler_runtime_state structure in Include/internal/pycore_faulthandler.h.

vstinner · 2026-04-28T17:02:06Z

-#define MAX_NTHREADS 100
+/* The historical default thread-dump cap is declared as
+   _Py_TRACEBACK_MAX_NTHREADS in pycore_traceback.h so callers of
+   _Py_DumpTracebackThreads can reference it directly. */


I don't think that this comment is useful. I suggest removing it.

vstinner · 2026-04-28T17:02:50Z

+* It is limited to 100 frames per thread, and by default to 100 threads
+  total in newest-first order (configurable via *max_threads*).


Suggested change

* It is limited to 100 frames per thread, and by default to 100 threads

total in newest-first order (configurable via *max_threads*).

* It is limited to 100 frames per thread, and 100 threads

(configurable via *max_threads*).

vstinner · 2026-04-28T17:03:24Z

   Dump the tracebacks of all threads into *file*. If *all_threads* is
-   ``False``, dump only the current thread.
+   ``False``, dump only the current thread. *max_threads* caps the number
+   of threads dumped; a ``...`` marker is written if there are more.


a ... marker is written if there are more

That's an implementation detail, please don't document it (remove it from the doc). Same remark for all documentation of this PR.

vstinner · 2026-04-28T17:03:32Z

   .. versionchanged:: 3.5
      Added support for passing file descriptor to this function.

+   .. versionchanged:: 3.15


Suggested change

.. versionchanged:: 3.15

.. versionchanged:: next

vstinner · 2026-04-28T17:11:13Z

+Add a *max_threads* keyword argument to :func:`faulthandler.dump_traceback`
+and :func:`faulthandler.dump_traceback_later`, raising the per-call cap on
+the number of threads dumped (previously a hard-coded ``MAX_NTHREADS = 100``
+in :file:`Python/traceback.c`). Useful for server processes with many
+worker or gRPC threads, where dump order (newest-thread-first) means the
+historical 100-thread cap silently elided the main thread. The default of
+``100`` preserves existing behavior.


Suggested change

Add a *max_threads* keyword argument to :func:`faulthandler.dump_traceback`

and :func:`faulthandler.dump_traceback_later`, raising the per-call cap on

the number of threads dumped (previously a hard-coded ``MAX_NTHREADS = 100``

in :file:`Python/traceback.c`). Useful for server processes with many

worker or gRPC threads, where dump order (newest-thread-first) means the

historical 100-thread cap silently elided the main thread. The default of

``100`` preserves existing behavior.

Add a *max_threads* keyword argument to :func:`faulthandler.dump_traceback`

and :func:`faulthandler.dump_traceback_later`.

I don't think that it's needed to mention gRPC usecase here, having it described in the issue is enough. Also, it's not needed to mention that the default is 100 since it's not changed.

vstinner · 2026-04-28T17:12:20Z

 _Py_DumpTracebackThreads(int fd, PyInterpreterState *interp,
-                         PyThreadState *current_tstate)
+                         PyThreadState *current_tstate,
+                         unsigned int max_nthreads)


I suggest renaming the parameter to max_threads for consistency.

vstinner · 2026-04-28T17:13:46Z

+                output, _ = process.communicate()
+                process.wait()
+        # Truncation marker is written when the cap is hit.
+        self.assertIn(b"...\n", output)


Check the whole line:

Suggested change

self.assertIn(b"...\n", output)

self.assertIn(b"\n...\n", output)

vstinner · 2026-04-28T17:14:30Z

+                    t.join()
+        """).strip()
+        # spawn_python merges stderr into stdout by default.
+        with support.SuppressCrashReport():


This process is not supposed to fail. If it fails, I would prefer to use the default crash reporter (such as dumping a coredump file).

vstinner · 2026-04-28T17:16:13Z

+        with support.SuppressCrashReport():
+            process = script_helper.spawn_python('-c', code)
+            with process:
+                output, _ = process.communicate()
+                process.wait()


assert_python_ok() can be used instead (to make the code shorter):

Suggested change

with support.SuppressCrashReport():

process = script_helper.spawn_python('-c', code)

with process:

output, _ = process.communicate()

process.wait()

proc = script_helper.assert_python_ok('-c', code)

output = proc.err

- 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.

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

Open

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.

		* It is limited to 100 frames per thread, and by default to 100 threads
		total in newest-first order (configurable via max_threads).

	self.assertIn(b"...\n", output)
	self.assertIn(b"\n...\n", output)

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 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