# `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에서 변경: 이 함수에 파일 기술자를 전달하는 지원이 추가되었습니다.

## 결함 처리기 상태

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

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

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

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

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

  버전 3.10에서 변경: The dump now mentions if a garbage collector collection is running if all_threads 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 "/home/python/cpython/Lib/ctypes/__init__.py", line 486 in string_at
      File "<stdin>", line 1 in <module>
    Segmentation fault