Repository navigation
Associate thread-local data/context with a faulthandler traceback #98825
Description
Feature or enhancement
I’d like to be able to associate a thread-local string with the faulthandler module.
Pitch
The faulthandler module is invaluable for tracking down segfaults in native code, however it is really lacking the ability to add some kind of useful breadcumb to aide debugging. Imagine you are running a large-scale distributed job over tens of millions of images and a single one causes opencv to segfault reliably. This can be very difficult to track down.
It would be very useful to be able to add a string (limited by size) via the faulthandler module that is outputted along with the traceback. For example:
for image in millions_of_images():
faulthandler.context(f'{image.id=}')
segfaulty_function(image)
# Or maybe:
for image in millions_of_images():
with faulthandler.context(f'{image.id=}'):
segfaulty_function(image)
The traceback might be something like:
Fatal Python error: Segmentation fault Current thread 0x00007fb899f39700 (most recent call first): .... (traceback) Segmentation fault Context: image_id=foo
You could of course add logging to this function to print out the image ID before you run it through segfaulty_function, but if you're running this at high volume on a huge number of machines, this becomes a bit of an overhead, and it doesn't handle multiple threads running the function well.
Previous discussion
This is lifted from the following thread on Python-ideas: https://mail.python.org/archives/list/python-ideas@python.org/message/BG36W24KEEX4YJA7CZ3PGW4ISZGVXMH6/
Activity
iritkatriel commented on Oct 28, 2022
This won't happen without a discussion on python-ideas, and probably also a PEP.
orf commented on Oct 28, 2022
I linked a discussion on Python-ideas. Why would it need a PEP? It seems like a simple, small change in line with existing functionality.
iritkatriel commented on Oct 28, 2022
Ah sorry I missed the link. Good.
See PEP 678 - that was a similar kind of change for exceptions. Since it touches a builtin type, it required a PEP.
iritkatriel commented on Oct 28, 2022
The PR needs unit tests too.
orf commented on Oct 28, 2022
This is a slightly different change than 678 - I’m not touching a built-in type in a visible way. Segfaults can’t really be handled, so I’m just proposing adding a user-defined string to the output. This is very different from adding a __notes__ attribute to BaseException, which has a lot more considerations involved.
I’m basically suggesting a thread-local user-definable print statement to be run on a segfault. I’m happy to progress with a PEP if it’s confirmed to be needed (who makes this call?), but I’m generally surprised.
iritkatriel commented on Oct 28, 2022
The call would be made by the core dev who merges the PR, in consultation with the steering council. Don't worry about now - make sure you have unit tests and docs and everything in the PR. Does it have to be on the thread state? Maybe the fault handler module can have some thread local variable?
orf commented on Oct 28, 2022
Ok! Will do, I’ll continue to work on it in a week or so. I guess a thread local in the faulthandler module would work, I just wasn’t really sure how to do that to be honest. I can dig into it if it would be preferable?
iritkatriel commented on Oct 28, 2022
CC @barry-scott @ericvsmith
vstinner commented on Apr 30, 2026
Since Python 3.14, faulthandler now dumps the thread name which can be used as a short context. On Linux, a thread name is limited to 15 bytes.
Example:
Output on Linux with Python 3.14:
Notice the [context:123] in the output.