faulthandler 2.0

[Victor Stinner]

When a user reports that your program crashes or hangs, sometimes you
can only help to try and collect more information and outline a scenario
to reproduce the situation. Even with a reliable user scenario, as a
developer you are often unable to reproduce the situation due to
environment differences, e.g., operating system and compiler. If you are
lucky, the user will be able to install debug tools, but most of time
you will have to wait until another person is able to obtain more
information from the same situation.

This mail is adapted from the article posted on the Python Insider to
announce the introduction of the faulthandler module into Python 3.3:

http://blog.python.org/2011/05/new-faulthandler-module-in-python-33.html



Fatal Errors
============

The faulthandler module should help this problem:

    http://pypi.python.org/pypi/faulthandler/

faulthandler provides the ability to dump the Python traceback on a
fatal error such as a segmentation fault, division by zero, abort, or
bus error. You can enable it inside your application using
faulthandler.enable(). Output example:

    Fatal Python error: Segmentation fault

    Current thread 0x00007f7babc6b700:
      File "Lib/test/crashers/gc_inspection.py", line 29 in g
      File "Lib/test/crashers/gc_inspection.py", line 32 in <module>
    Segmentation fault


Timeout
=======

faulthandler can also dump the traceback after a timeout using
faulthandler.dump_tracebacks_later(timeout). Call it again to restart
the timer or call faulthandler.cancel_dump_tracebacks_later() to stop
the timer. Output example:

    Timeout (0:01:00)!
    Current thread 0x00007f987d459700:
      File "Lib/test/crashers/infinite_loop_re.py", line 20 in <module>

Use the repeat=True option to dump the traceback each timeout seconds,
or exit=True to immediatly exit the program in an unsafe fashion, e.g.
don't flush files.


User Signal
===========

If you have access to the host on which the program is running, you can
use faulthandler.register(signal) to install a signal handler to dump
the traceback when signal is received. On UNIX, for example, you can use
the SIGUSR1 signal: kill -USR1 <pid> will dump the current traceback.
This feature is not available on Windows. Output example:

    Current thread 0x00007fdc3da74700:
      File "Lib/test/crashers/infinite_loop_re.py", line 19 in <module>


Another possibility is to explicitly call faulthandler.dump_traceback()
in your program.


Integrated in Python 3.3
========================

faulthandler is now part of Python 3.3 and has a nice documentation:

    http://docs.python.org/dev/library/faulthandler.html


Early Success
=============

The new faulthandler module has already helped with tracking down race
conditions in Python buildbots. I hope that it will also help you in
your programs.


Victor Stinner aka haypo