# `faulthandler` — 파이썬 트레이스백 덤프

Added in version 3.3.

이 모듈은 결함(fault) 시, 시간 초과 후 또는 사용자 시그널에 파이썬 트레이스백을 명시적으로 덤프하는 함수를 포함합니다. `SIGSEGV`, `SIGFPE`, `SIGABRT`, `SIGBUS` 및 `SIGILL` 시그널에 대한 결함 처리기를 설치하려면 `faulthandler.enable()`를 호출하십시오. `PYTHONFAULTHANDLER` 환경 변수를 설정하거나 `-X` `faulthandler` 명령 줄 옵션을 사용하여 시작할 때 활성화할 수도 있습니다.

결함 처리기는 Apport나 윈도우 결함 처리기(Windows fault handler)와 같은 시스템 결함 처리기와 호환됩니다. 이 모듈은 `sigaltstack()` 함수를 사용할 수 있으면 시그널 처리기에 대체 스택을 사용합니다. 이것은 스택 오버플로에서조차 트레이스백을 덤프할 수 있도록 합니다.

결함 처리기는 치명적일 때 호출되므로 시그널 안전한 함수만 사용할 수 있습니다 (예를 들어, 힙에 메모리를 할당할 수 없습니다). 이 제한 때문에 일반적인 파이썬 트레이스백에 비해 트레이스백 덤프는 최소화됩니다:

- ASCII만 지원됩니다. 인코딩 시 `backslashreplace` 에러 처리기가 사용됩니다.

- 각 문자열은 500자로 제한됩니다.

- 파일명, 함수 이름 및 줄 번호만 표시됩니다. (소스 코드 없음)

- 100프레임과 100스레드로 제한됩니다.

- 순서가 뒤집힙니다: 가장 최근의 호출이 먼저 표시됩니다.

기본적으로, 파이썬 트레이스백은 `sys.stderr`에 기록됩니다. 트레이스백을 보려면, 응용 프로그램이 터미널에서 실행되어야 합니다. 로그 파일을 `faulthandler.enable()`로 전달할 수도 있습니다.

모듈은 C로 구현되어 있으므로, 충돌 시나 파이썬이 교착 상태에 빠질 때 트레이스백을 덤프할 수 있습니다.

파이썬 개발 모드는 파이썬 시작 시 `faulthandler.enable()`을 호출합니다.

더 보기

Module `pdb`

  Interactive source code debugger for Python programs.

Module `traceback`

  Standard interface to extract, format and print stack traces of Python programs.

## 트레이스백 덤프하기

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

  모든 스레드의 트레이스백을 file로 덤프합니다. all_threads가 `False`면, 현재 스레드만 덤프합니다.

  더 보기

  `traceback.print_tb()`, which can be used to print a traceback object.

  버전 3.5에서 변경: 이 함수에 파일 기술자를 전달하는 지원이 추가되었습니다.

## Dumping the C stack

Added in version 3.14.

faulthandler.dump_c_stack(file=sys.stderr)

  Dump the C stack trace of the current thread into file.

  If the Python build does not support it or the operating system does not provide a stack trace, then this prints an error in place of a dumped C stack.

### C Stack Compatibility

If the system does not support the C-level backtrace(3) or dladdr1(3), then C stack dumps will not work. An error will be printed instead of the stack.

Additionally, some compilers do not support CPython’s implementation of C stack dumps. As a result, a different error may be printed instead of the stack, even if the operating system supports dumping stacks.

참고

Dumping C stacks can be arbitrarily slow, depending on the DWARF level of the binaries in the call stack.

## 결함 처리기 상태

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

  결함 처리기를 활성화합니다: `SIGSEGV`, `SIGFPE`, `SIGABRT`, `SIGBUS` 및 `SIGILL` 시그널에 대한 처리기를 설치하여 파이썬 트레이스백을 덤프합니다. all_threads가 `True`면 실행 중인 모든 스레드에 대한 트레이스백을 생성합니다. 그렇지 않으면, 현재 스레드만 덤프합니다.

  file은 결함 처리기가 비활성화될 때까지 열려 있어야 합니다: 파일 기술자 관련 문제를 참조하십시오.

  If c_stack is `True`, then the C stack trace is printed after the Python traceback, unless the system does not support it. See `dump_c_stack()` for more information on compatibility.

  버전 3.5에서 변경: 이 함수에 파일 기술자를 전달하는 지원이 추가되었습니다.

  버전 3.6에서 변경: 윈도우에서는, 윈도우 예외(Windows exception) 처리기도 설치됩니다.

  버전 3.10에서 변경: The dump now mentions if a garbage collector collection is running if all_threads is true.

  버전 3.14에서 변경: Only the current thread is dumped if the GIL is disabled to prevent the risk of data races.

  버전 3.14에서 변경: The dump now displays the C stack trace if c_stack is true.

faulthandler.disable()

  결함 처리기를 비활성화합니다: `enable()`로 설치된 시그널 처리기를 제거합니다.

faulthandler.is_enabled()

  결함 처리기가 활성화되었는지 검사합니다.

## 시간 초과 후에 트레이스백 덤프하기

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

  timeout 초의 시간제한 후, 또는 repeat가 `True`면 매 timeout 초마다, 모든 스레드의 트레이스백을 덤프합니다. exit가 `True`면, 트레이스백을 덤프한 후 status=1 로 `_exit()`를 호출합니다. (`_exit()`가 프로세스를 즉시 종료함에 유의하십시오. 파일 버퍼를 플러시 하는 것과 같은 정리 작업을 수행하지 않습니다.) 함수가 두 번 호출되면, 새 호출은 이전 매개 변수를 대체하고 시간제한을 다시 설정합니다. 타이머는 1초 미만의 해상도를 갖습니다.

  file은 트레이스백이 덤프 되거나 `cancel_dump_traceback_later()`가 호출될 때까지 열려 있어야 합니다: 파일 기술자 관련 문제를 참조하십시오.

  이 함수는 워치독(watchdog) 스레드를 사용하여 구현됩니다.

  버전 3.5에서 변경: 이 함수에 파일 기술자를 전달하는 지원이 추가되었습니다.

  버전 3.7에서 변경: 이 함수는 이제 항상 사용할 수 있습니다.

faulthandler.cancel_dump_traceback_later()

  마지막 `dump_traceback_later()` 호출을 취소합니다.

## 사용자 시그널에 트레이스백 덤프하기

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

  사용자 시그널을 등록합니다: signum 시그널에 대한 처리기를 설치해서, 모든 스레드, 또는 all_threads가 `False`면 현재 스레드의, 트레이스백을 file로 덤프합니다. chain이 `True`면 이전 처리기를 호출합니다.

  file은 시그널이 `unregister()`로 등록 해지 될 때까지 열려 있어야 합니다: 파일 기술자 관련 문제를 참조하십시오.

  윈도우에서는 사용할 수 없습니다.

  버전 3.5에서 변경: 이 함수에 파일 기술자를 전달하는 지원이 추가되었습니다.

faulthandler.unregister(signum)

  사용자 시그널을 등록 해지합니다: `register()`로 설치된 signum 시그널 처리기를 제거합니다. 시그널이 등록되었으면 `True`를 반환하고, 그렇지 않으면 `False`를 반환합니다.

  윈도우에서는 사용할 수 없습니다.

## 파일 기술자 관련 문제

`enable()`, `dump_traceback_later()` 및 `register()`는 file 인자의 파일 기술자를 유지합니다. 파일이 닫히고 파일 기술자가 새 파일에 의해 다시 사용되거나, `os.dup2()`가 파일 기술자를 바꾸는 데 사용되면, 트레이스백이 다른 파일에 기록됩니다. 파일을 바꿀 때마다 이 함수들을 다시 호출하십시오.

## 예제

리눅스에서 결함 처리기를 활성화하거나 그렇지 않았을 때의 세그멘테이션 결함 예제:

    $ 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