faulthandler — Python 트레이스백 덤프

faulthandler — Python 트레이스백 덤프

이 모듈은 폴트 시, 타임아웃 후, 또는 사용자 신호 시에 Python 트레이스백을 명시적으로 덤프하는 함수를 포함합니다 (3.3에서 추가). faulthandler.enable()을 호출하면 SIGSEGV, SIGFPE, SIGABRT, SIGBUS, SIGILL 신호에 대한 폴트 핸들러를 설치합니다. PYTHONFAULTHANDLER 환경 변수나 -X faulthandler 명령줄 옵션으로 시작 시 활성화할 수도 있습니다.

출처: Python documentation

본문

폴트 핸들러는 Apport나 Windows 폴트 핸들러 같은 시스템 폴트 핸들러와 호환됩니다. sigaltstack() 함수가 사용 가능하면 신호 핸들러에 대해 대체 스택을 사용하므로 스택 오버플로 시에도 트레이스백을 덤프할 수 있습니다.

폴트 핸들러는 치명적 상황에서 호출되므로 신호 안전(signal-safe) 함수만 사용할 수 있습니다(예: 힙에 메모리를 할당할 수 없음). 이 제한 때문에 일반 Python 트레이스백에 비해 최소한의 트레이스백 덤프를 수행합니다:

  • ASCII만 지원됩니다. 인코딩 시 backslashreplace 오류 처리기가 사용됩니다.
  • 각 문자열은 500자로 제한됩니다.
  • 파일 이름, 함수 이름, 줄 번호만 표시됩니다(소스 코드 없음).
  • 100 프레임과 100 스레드로 제한됩니다.
  • 순서가 반대입니다: 가장 최근 호출이 먼저 표시됩니다.

기본적으로 Python 트레이스백은 sys.stderr에 기록됩니다. 트레이스백을 보려면 애플리케이션을 터미널에서 실행해야 합니다. 대신 로그 파일을 faulthandler.enable()에 전달할 수 있습니다. 모듈은 C로 구현되므로 크래시 시나 Python이 교착 상태일 때도 트레이스백을 덤프할 수 있습니다. Python 개발 모드는 Python 시작 시 faulthandler.enable()을 호출합니다.

트레이스백 덤프

  • faulthandler.dump_traceback(file=sys.stderr, all_threads=True) — 모든 스레드의 트레이스백을 file에 덤프합니다. all_threads가 False이면 현재 스레드만 덤프합니다.

C 스택 덤프

faulthandler.dump_c_stack(file=sys.stderr)는 현재 스레드의 C 스택 트레이스를 file에 덤프합니다 (3.14에서 추가). Python 빌드가 지원하지 않거나 운영 체제가 스택 트레이스를 제공하지 않으면 오류를 출력합니다. 시스템이 C 수준의 backtrace(3)나 dladdr1(3)을 지원하지 않으면 C 스택 덤프는 동작하지 않습니다. C 스택 덤프는 호출 스택에 있는 바이너리의 DWARF 수준에 따라 임의로 느릴 수 있습니다.

폴트 핸들러 상태

  • faulthandler.enable(file=sys.stderr, all_threads=True, c_stack=True) — 폴트 핸들러를 활성화합니다. all_threads가 True이면 실행 중인 모든 스레드의 트레이스백을 생성하고, 아니면 현재 스레드만 덤프합니다. c_stack이 True이면 시스템이 지원할 때 Python 트레이스백 뒤에 C 스택 트레이스를 출력합니다. Windows에서는 Windows 예외에 대한 핸들러도 설치됩니다 (3.6). 3.14부터 GIL이 비활성화되면 데이터 경합 위험을 막기 위해 현재 스레드만 덤프합니다.
  • faulthandler.disable() — 폴트 핸들러를 비활성화합니다. enable()이 설치한 신호 핸들러를 제거합니다.
  • faulthandler.is_enabled() — 폴트 핸들러가 활성화되었는지 확인합니다.

타임아웃 후 트레이스백 덤프

  • faulthandler.dump_traceback_later(timeout, repeat=False, file=sys.stderr, exit=False) — timeout 초 후, 또는 repeat이 True이면 매 timeout 초마다 모든 스레드의 트레이스백을 덤프합니다. exit이 True이면 덤프 후 _exit()을 status=1로 호출합니다. 이 함수는 워치독 스레드로 구현됩니다.
  • faulthandler.cancel_dump_traceback_later() — 마지막 dump_traceback_later() 호출을 취소합니다.

사용자 신호 시 트레이스백 덤프

  • faulthandler.register(signum, file=sys.stderr, all_threads=True, chain=False) — signum 신호에 대한 핸들러를 설치해 모든 스레드의 트레이스백을 덤프합니다. chain이 True이면 이전 핸들러를 호출합니다.

faulthandler는 예외가 아닌 네이티브 수준의 크래시(예: 잘못된 메모리 접근으로 인한 segfault)를 진단하는 데 특히 유용합니다. 예를 들어 세그멘테이션 폴트 시 Python과 C 스택 트레이스가 함께 출력되어 문제의 원인을 추적할 수 있습니다. 관련 모듈로는 대화형 디버거 pdb와 스택 트레이스를 추출·형식화·출력하는 표준 인터페이스 traceback이 있습니다.

더 알아보기 (Learn more)