faulthandler — Python-Traceback ausgeben

Hinzugefügt in Version 3.3.

Dieses Modul enthält Funktionen, um Python-Tracebacks explizit auszugeben, bei einem Fehler, nach einem Timeout oder bei einem Benutzersignal. Rufen Sie faulthandler.enable() auf, um Fehlerbehandler für die Signale SIGSEGV, SIGFPE, SIGABRT, SIGBUS und SIGILL zu installieren. Sie können sie auch beim Start aktivieren, indem Sie die Umgebungsvariable PYTHONFAULTHANDLER setzen oder die Kommandozeilenoption -X faulthandler verwenden.

Der Fehlerbehandler ist kompatibel mit systemweiten Fehlerbehandlern wie Apport oder dem Windows-Fehlerbehandler. Das Modul verwendet einen alternativen Stack für Signalbehandler, wenn die Funktion sigaltstack() verfügbar ist. Dies ermöglicht die Ausgabe des Tracebacks auch bei einem Stack-Überlauf.

Der Fehlerbehandler wird in katastrophalen Fällen aufgerufen und kann daher nur signal-sichere Funktionen verwenden (z. B. kann er keinen Speicher auf dem Heap allozieren). Aufgrund dieser Einschränkung ist die Traceback-Ausgabe im Vergleich zu normalen Python-Tracebacks minimal.

  • Nur ASCII wird unterstützt. Der Fehlerbehandler backslashreplace wird bei der Kodierung verwendet.

  • Jede Zeichenkette ist auf 500 Zeichen begrenzt.

  • Nur der Dateiname, der Funktionsname und die Zeilennummer werden angezeigt. (kein Quellcode)

  • Es ist auf 100 Frames und 100 Threads beschränkt.

  • Die Reihenfolge ist umgekehrt: Der zuletzt aufgerufene Aufruf wird zuerst angezeigt.

Standardmäßig wird der Python-Traceback nach sys.stderr geschrieben. Um Tracebacks zu sehen, müssen Anwendungen im Terminal ausgeführt werden. Alternativ kann eine Logdatei an faulthandler.enable() übergeben werden.

Das Modul ist in C implementiert, sodass Tracebacks bei einem Absturz oder wenn Python blockiert ist, ausgegeben werden können.

Der Python Development Mode ruft faulthandler.enable() beim Start von Python auf.

Siehe auch

Modul pdb

Interaktiver Quellcode-Debugger für Python-Programme.

Modul traceback

Standard-Schnittstelle zum Extrahieren, Formatieren und Ausgeben von Stack-Tracebacks von Python-Programmen.

Traceback ausgeben

faulthandler.dump_traceback(file=sys.stderr, all_threads=True)

Gibt die Tracebacks aller Threads in file aus. Wenn all_threads False ist, wird nur der aktuelle Thread ausgegeben.

Siehe auch

traceback.print_tb(), die zum Ausgeben eines Traceback-Objekts verwendet werden kann.

Geändert in Version 3.5: Unterstützung für die Übergabe eines Dateideskriptors an diese Funktion hinzugefügt.

C-Stack ausgeben

Hinzugefügt in Version 3.14.

faulthandler.dump_c_stack(file=sys.stderr)

Gibt den C-Stack-Trace des aktuellen Threads in file aus.

Wenn die Python-Build-Unterstützung dafür fehlt oder das Betriebssystem keinen Stack-Trace bereitstellt, wird anstelle eines ausgegebenen C-Stacks eine Fehlermeldung ausgegeben.

C-Stack-Kompatibilität

Wenn das System das C-Level-backtrace(3) oder dladdr1(3) nicht unterstützt, funktionieren C-Stack-Dumps nicht. Stattdessen wird eine Fehlermeldung ausgegeben.

Zusätzlich unterstützen einige Compiler die CPython-Implementierung von C-Stack-Dumps nicht. Infolgedessen kann eine andere Fehlermeldung anstelle des Stacks ausgegeben werden, selbst wenn das Betriebssystem das Ausgeben von Stacks unterstützt.

Hinweis

Das Ausgeben von C-Stacks kann beliebig langsam sein, abhängig vom DWARF-Level der Binaries im Aufrufstapel.

Zustand des Fehlerbehandlers

faulthandler.enable(file=sys.stderr, all_threads=True, c_stack=True)

Aktiviert den Fehlerbehandler: Installiert Behandler für die Signale SIGSEGV, SIGFPE, SIGABRT, SIGBUS und SIGILL, um den Python-Traceback auszugeben. Wenn all_threads True ist, werden für jeden laufenden Thread Tracebacks erzeugt. Andernfalls wird nur der aktuelle Thread ausgegeben.

Das file muss geöffnet bleiben, bis der Fehlerbehandler deaktiviert wird: siehe Problem mit Dateideskriptoren.

Wenn c_stack True ist, wird der C-Stack-Trace nach dem Python-Traceback ausgegeben, es sei denn, das System unterstützt dies nicht. Siehe dump_c_stack() für weitere Informationen zur Kompatibilität.

Geändert in Version 3.5: Unterstützung für die Übergabe eines Dateideskriptors an diese Funktion hinzugefügt.

Geändert in Version 3.6: Unter Windows wird auch ein Behandler für Windows-Ausnahmen installiert.

Geändert in Version 3.10: Der Dump erwähnt nun, ob eine Garbage-Collector-Sammlung läuft, wenn all_threads wahr ist.

Geändert in Version 3.14: Nur der aktuelle Thread wird ausgegeben, wenn die GIL deaktiviert ist, um das Risiko von Datenrennen zu vermeiden.

Geändert in Version 3.14: Der Dump zeigt nun den C-Stack-Trace an, wenn c_stack wahr ist.

faulthandler.disable()

Deaktiviert den Fehlerbehandler: Deinstalliert die von enable() installierten Signalbehandler.

faulthandler.is_enabled()

Überprüft, ob der Fehlerbehandler aktiviert ist.

Tracebacks nach einem Timeout ausgeben

faulthandler.dump_traceback_later(timeout, repeat=False, file=sys.stderr, exit=False)

Gibt die Tracebacks aller Threads nach einem Timeout von timeout Sekunden aus, oder alle timeout Sekunden, wenn repeat True ist. Wenn exit True ist, wird nach der Ausgabe der Tracebacks _exit() mit Status=1 aufgerufen. (Hinweis: _exit() beendet den Prozess sofort, was bedeutet, dass keine Bereinigungsarbeiten wie das Leeren von Dateipuffern durchgeführt werden.) Wenn die Funktion zweimal aufgerufen wird, ersetzt der neue Aufruf die vorherigen Parameter und setzt den Timeout zurück. Der Timer hat eine Untersekunden-Auflösung.

Das file muss geöffnet bleiben, bis der Traceback ausgegeben wird oder cancel_dump_traceback_later() aufgerufen wird: siehe Problem mit Dateideskriptoren.

Diese Funktion wird mithilfe eines Watchdog-Threads implementiert.

Geändert in Version 3.5: Unterstützung für die Übergabe eines Dateideskriptors an diese Funktion hinzugefügt.

Geändert in Version 3.7: Diese Funktion ist jetzt immer verfügbar.

faulthandler.cancel_dump_traceback_later()

Bricht den letzten Aufruf von dump_traceback_later() ab.

Traceback bei Benutzersignal ausgeben

faulthandler.register(signum, file=sys.stderr, all_threads=True, chain=False)

Registriert ein Benutzersignal: Installiert einen Behandler für das signum-Signal, um den Traceback aller Threads, oder nur des aktuellen Threads (wenn all_threads False ist), in file auszugeben. Ruft den vorherigen Behandler auf, wenn chain True ist.

Das file muss geöffnet bleiben, bis das Signal durch unregister() deregistriert wird: siehe Problem mit Dateideskriptoren.

Nicht auf Windows verfügbar.

Geändert in Version 3.5: Unterstützung für die Übergabe eines Dateideskriptors an diese Funktion hinzugefügt.

faulthandler.unregister(signum)

Deregistriert ein Benutzersignal: Deinstalliert den Behandler für das signum-Signal, der von register() installiert wurde. Gibt True zurück, wenn das Signal registriert war, andernfalls False.

Nicht auf Windows verfügbar.

Problem mit Dateideskriptoren

enable(), dump_traceback_later() und register() behalten den Dateideskriptor ihres file-Arguments bei. Wenn die Datei geschlossen und ihr Dateideskriptor von einer neuen Datei wiederverwendet wird, oder wenn os.dup2() verwendet wird, um den Dateideskriptor zu ersetzen, wird der Traceback in eine andere Datei geschrieben. Rufen Sie diese Funktionen jedes Mal erneut auf, wenn die Datei ersetzt wird.

Beispiel

Beispiel für einen Segmentierungsfehler unter Linux mit und ohne Aktivierung des Fehlerbehandlers

$ python -c "import ctypes; ctypes.string_at(0)"
Segmentation fault

$ python -q -X faulthandler
>>> import ctypes
>>> ctypes.string_at(0)
Fatal Python error: Segmentation fault

Current thread 0x00007fb899f39700 (most recent call first):
  File "/opt/python/Lib/ctypes/__init__.py", line 486 in string_at
  File "<stdin>", line 1 in <module>

Current thread's C stack trace (most recent call first):
  Binary file "/opt/python/python", at _Py_DumpStack+0x42 [0x5b27f7d7147e]
  Binary file "/opt/python/python", at +0x32dcbd [0x5b27f7d85cbd]
  Binary file "/opt/python/python", at +0x32df8a [0x5b27f7d85f8a]
  Binary file "/usr/lib/libc.so.6", at +0x3def0 [0x77b73226bef0]
  Binary file "/usr/lib/libc.so.6", at +0x17ef9c [0x77b7323acf9c]
  Binary file "/opt/python/build/lib.linux-x86_64-3.14/_ctypes.cpython-314d-x86_64-linux-gnu.so", at +0xcdf6 [0x77b7315dddf6]
  Binary file "/usr/lib/libffi.so.8", at +0x7976 [0x77b73158f976]
  Binary file "/usr/lib/libffi.so.8", at +0x413c [0x77b73158c13c]
  Binary file "/usr/lib/libffi.so.8", at ffi_call+0x12e [0x77b73158ef0e]
  Binary file "/opt/python/build/lib.linux-x86_64-3.14/_ctypes.cpython-314d-x86_64-linux-gnu.so", at +0x15a33 [0x77b7315e6a33]
  Binary file "/opt/python/build/lib.linux-x86_64-3.14/_ctypes.cpython-314d-x86_64-linux-gnu.so", at +0x164fa [0x77b7315e74fa]
  Binary file "/opt/python/build/lib.linux-x86_64-3.14/_ctypes.cpython-314d-x86_64-linux-gnu.so", at +0xc624 [0x77b7315dd624]
  Binary file "/opt/python/python", at _PyObject_MakeTpCall+0xce [0x5b27f7b73883]
  Binary file "/opt/python/python", at +0x11bab6 [0x5b27f7b73ab6]
  Binary file "/opt/python/python", at PyObject_Vectorcall+0x23 [0x5b27f7b73b04]
  Binary file "/opt/python/python", at _PyEval_EvalFrameDefault+0x490c [0x5b27f7cbb302]
  Binary file "/opt/python/python", at +0x2818e6 [0x5b27f7cd98e6]
  Binary file "/opt/python/python", at +0x281aab [0x5b27f7cd9aab]
  Binary file "/opt/python/python", at PyEval_EvalCode+0xc5 [0x5b27f7cd9ba3]
  Binary file "/opt/python/python", at +0x255957 [0x5b27f7cad957]
  Binary file "/opt/python/python", at +0x255ab4 [0x5b27f7cadab4]
  Binary file "/opt/python/python", at _PyEval_EvalFrameDefault+0x6c3e [0x5b27f7cbd634]
  Binary file "/opt/python/python", at +0x2818e6 [0x5b27f7cd98e6]
  Binary file "/opt/python/python", at +0x281aab [0x5b27f7cd9aab]
  Binary file "/opt/python/python", at +0x11b6e1 [0x5b27f7b736e1]
  Binary file "/opt/python/python", at +0x11d348 [0x5b27f7b75348]
  Binary file "/opt/python/python", at +0x11d626 [0x5b27f7b75626]
  Binary file "/opt/python/python", at PyObject_Call+0x20 [0x5b27f7b7565e]
  Binary file "/opt/python/python", at +0x32a67a [0x5b27f7d8267a]
  Binary file "/opt/python/python", at +0x32a7f8 [0x5b27f7d827f8]
  Binary file "/opt/python/python", at +0x32ac1b [0x5b27f7d82c1b]
  Binary file "/opt/python/python", at Py_RunMain+0x31 [0x5b27f7d82ebe]
  <truncated rest of calls>
Segmentation fault