faulthandler
— Dumpa Python-spårningen¶
Tillagd i version 3.3.
Denna modul innehåller funktioner för att dumpa Python-spårningar explicit, på ett fel, efter en timeout eller på en användarsignal. Anropa faulthandler.enable()
för att installera felhanterare för signalerna SIGSEGV
, SIGFPE
, SIGABRT
, SIGBUS
och SIGILL
. Du kan också aktivera dem vid start genom att ställa in miljövariabeln PYTHONFAULTHANDLER
eller genom att använda kommandoradsalternativet -X
faulthandler
.
Felhanteraren är kompatibel med systemfelhanterare som Apport eller Windows felhanterare. Modulen använder en alternativ stack för signalhanterare om funktionen sigaltstack()
är tillgänglig. Detta gör att den kan dumpa traceback även vid stacköverflöd.
Felhanteraren anropas i katastroffall och kan därför bara använda signalsäkra funktioner (den kan t.ex. inte allokera minne i heapen). På grund av denna begränsning är spårningsdumpningen minimal jämfört med normala Python-spårningar:
Endast ASCII stöds. Felhanteraren
backslashreplace
används vid kodning.Varje sträng är begränsad till 500 tecken.
Endast filnamnet, funktionsnamnet och radnumret visas. (ingen källkod)
Den är begränsad till 100 ramar och 100 trådar.
Ordningen är omvänd: det senaste anropet visas först.
Som standard skrivs Python-spårningen till sys.stderr
. För att se spårningar måste program köras i terminalen. En loggfil kan alternativt skickas till faulthandler.enable()
.
Modulen är implementerad i C, så att spårningar kan dumpas vid en krasch eller när Python är blockerat.
I Python Development Mode anropas faulthandler.enable()
vid Python-start.
Se även
Dumpning av spårningen¶
- faulthandler.dump_traceback(file=sys.stderr, all_threads=True)¶
Dumpar spårningarna av alla trådar till fil. Om all_threads är
False
, dumpas endast den aktuella tråden.Se även
traceback.print_tb()
, som kan användas för att skriva ut ett traceback-objekt.Ändrad i version 3.5: Lagt till stöd för att skicka filbeskrivare till denna funktion.
Dumpa C-stacken¶
Tillagd i version 3.14.
- faulthandler.dump_c_stack(file=sys.stderr)¶
Dumpa C-stackspårningen för den aktuella tråden till fil.
Om Python-versionen inte stöder detta eller om operativsystemet inte tillhandahåller en stackspårning, skrivs ett fel ut i stället för en dumpad C-stack.
Kompatibilitet med C-stack¶
Om systemet inte stöder C-nivå backtrace(3) eller dladdr1(3) fungerar inte C-stackdumpar. Ett felmeddelande kommer att skrivas ut istället för stacken.
Dessutom stöder vissa kompilatorer inte CPythons implementering av C-stackdumpar. Detta kan leda till att ett annat fel skrivs ut i stället för stacken, även om operativsystemet stöder dumpning av stackar.
Anteckning
Dumpning av C-stackar kan vara godtyckligt långsam, beroende på DWARF-nivån för binärprogrammen i anropsstacken.
Felhanterarens status¶
- faulthandler.enable(file=sys.stderr, all_threads=True, c_stack=True)¶
Aktivera felhanteraren: installera hanterare för signalerna
SIGSEGV
,SIGFPE
,SIGABRT
,SIGBUS
ochSIGILL
för att dumpa Python-spårningen. Om all_threads ärTrue
, producera spårningar för varje tråd som körs. Annars dumpas endast den aktuella tråden.Filen måste hållas öppen tills felhanteraren inaktiveras: se problem med filbeskrivare.
Om c_stack är
True
, skrivs C-stackspåret ut efter Python-spårningen, såvida inte systemet inte stöder det. Sedump_c_stack()
för mer information om kompatibilitet.Ändrad i version 3.5: Lagt till stöd för att skicka filbeskrivare till denna funktion.
Ändrad i version 3.6: I Windows installeras även en hanterare för Windows-undantag.
Ändrad i version 3.10: Dumpen nämner nu om en skräpsamlare körs om all_threads är true.
Ändrad i version 3.14: Endast den aktuella tråden dumpas om GIL är inaktiverad för att förhindra risken för datarace.
Ändrad i version 3.14: Dumpen visar nu C-stackspårningen om c_stack är sant.
- faulthandler.disable()¶
Inaktivera felhanteraren: avinstallera de signalhanterare som installerats av
enable()
.
- faulthandler.is_enabled()¶
Kontrollera om felhanteraren är aktiverad.
Dumpning av spårningar efter en timeout¶
- faulthandler.dump_traceback_later(timeout, repeat=False, file=sys.stderr, exit=False)¶
Dumpar spårningarna av alla trådar efter en tidsgräns på timeout sekunder, eller varje timeout sekund om repeat är
True
. Om exit ärTrue
, anropa_exit()
med status=1 efter att ha dumpat spårningarna. (Observera att_exit()
avslutar processen omedelbart, vilket innebär att den inte gör någon upprensning som att tömma filbuffertar) Om funktionen anropas två gånger ersätter det nya anropet tidigare parametrar och återställer timeouten. Timern har en upplösning på subsekunder.Filen måste hållas öppen tills spårningen dumpas eller
cancel_dump_traceback_later()
anropas: se problem med filbeskrivare.Denna funktion implementeras med hjälp av en watchdog-tråd.
Ändrad i version 3.5: Lagt till stöd för att skicka filbeskrivare till denna funktion.
Ändrad i version 3.7: Denna funktion är nu alltid tillgänglig.
- faulthandler.cancel_dump_traceback_later()¶
Avbryt det senaste anropet till
dump_traceback_later()
.
Dumpning av spårningen av en användarsignal¶
- faulthandler.register(signum, file=sys.stderr, all_threads=True, chain=False)¶
Registrera en användarsignal: installera en hanterare för signum-signalen för att dumpa spårningen av alla trådar, eller av den aktuella tråden om all_threads är
False
, i file. Anropa den föregående hanteraren om chain ärTrue
.Filen måste hållas öppen tills signalen avregistreras med
unregister()
: se problem med filbeskrivare.Ej tillgängligt på Windows.
Ändrad i version 3.5: Lagt till stöd för att skicka filbeskrivare till denna funktion.
- faulthandler.unregister(signum)¶
Avregistrera en användarsignal: avinstallera hanteraren av signum-signalen som installerats av
register()
. ReturnerarTrue
om signalen var registrerad,False
annars.Ej tillgängligt på Windows.
Problem med filbeskrivare¶
enable()
, dump_traceback_later()
och register()
behåller filbeskrivaren för sitt file-argument. Om filen stängs och dess filbeskrivare återanvänds av en ny fil, eller om os.dup2()
används för att ersätta filbeskrivaren, kommer spårningen att skrivas till en annan fil. Anropa dessa funktioner igen varje gång filen ersätts.
Exempel¶
Exempel på ett segmenteringsfel på Linux med och utan aktivering av felhanteraren:
$ 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