파이썬 스레드 덤프 자동 수집 방법 watchdog와 faulthandler 활용

🔍 스레드 덤프 자동 수집이 필요한 이유

파이썬으로 개발한 프로그램이 갑자기 응답하지 않거나 멈추는 상황을 겪어본 적이 있을 것입니다.
특히 멀티스레드 환경에서는 어떤 스레드가 어떤 작업을 하고 있었는지 추적하기가 쉽지 않습니다.
이럴 때 스레드 덤프(thread dump)는 문제 해결의 핵심 단서를 제공합니다.
스레드 덤프란, 특정 시점에 모든 스레드의 상태와 실행 중인 코드 위치를 기록한 정보로, 교착상태나 무한 루프 같은 오류를 추적하는 데 필수적입니다.

하지만 이런 정보를 수동으로 남기려면 보통 프로세스를 강제로 중단하거나 디버거를 붙여야 합니다.
이는 운영 환경에서는 불가능하거나 서비스 중단을 초래할 수 있어 위험합니다.
따라서 자동으로 스레드 덤프를 수집하는 기능이 필요합니다.
프로그램이 특정 이벤트(예: 일정 시간 응답 없음, CPU 점유율 폭주)에 도달했을 때 곧바로 기록을 남기면, 장애 상황에서 복구 시간을 줄이고 근본 원인을 신속하게 파악할 수 있습니다.

📌 수동 덤프와 자동 덤프의 차이

수동 덤프는 문제가 발생한 후 사람이 개입해 기록하는 방식으로, 이미 서비스가 멈춘 이후라 근본 원인을 놓치기 쉽습니다.
반면 자동 덤프는 문제가 발생하는 순간 시스템이 스스로 상태를 기록하므로 더 정확하고 빠르게 상황을 파악할 수 있습니다.
특히 실시간 서비스에서는 자동화된 스레드 덤프 수집이 사실상 필수라고 할 수 있습니다.

• 🛠️프로세스가 응답하지 않는 상황에서 원인 파악
• ⚙️멀티스레드 환경에서 교착상태 확인
• 🔍CPU 점유율 급등 원인 추적

🧩 faulthandler 기본 활용법

파이썬은 faulthandler라는 내장 모듈을 제공하여 스레드 상태를 쉽게 기록할 수 있습니다.
이 모듈은 프로그램이 크래시되거나 특정 시그널을 받았을 때 자동으로 스택 트레이스를 출력해 줍니다.
개발자는 별도의 복잡한 설정 없이 몇 줄의 코드만으로 스레드 덤프 기능을 활성화할 수 있습니다.

가장 기본적인 사용 방법은 프로그램 시작 시 faulthandler.enable()을 호출하는 것입니다.
이렇게 하면 치명적인 오류나 강제 종료 시 파이썬 인터프리터가 자동으로 현재 스레드 상태를 stderr에 출력합니다.
또한 특정 시그널(예: SIGUSR1)을 받았을 때 스레드 상태를 덤프하도록 설정할 수도 있습니다.

📌 기본 코드 예제

import faulthandler
import signal

# faulthandler 활성화
faulthandler.enable()

# SIGUSR1 시그널을 받으면 스레드 덤프 출력
faulthandler.register(signal.SIGUSR1)

위 코드를 실행한 뒤 kill -USR1 <pid> 명령어를 보내면, 해당 시점의 스레드 상태가 자동으로 출력됩니다.
이 기능은 특히 리눅스 환경에서 서비스가 응답하지 않을 때 매우 유용합니다.

📌 faulthandler의 한계

faulthandler는 강력하지만, 특정 조건에서만 동작합니다.
예를 들어 단순히 프로그램이 느려지는 상황이나 무한 루프에 빠진 경우에는 자동으로 덤프를 남기지 않습니다.
따라서 이런 경우에는 외부 트리거가 필요하며, 이때 watchdog 같은 도구를 함께 사용하면 더욱 효과적입니다.

👀 watchdog으로 이벤트 감시하기

faulthandler가 스레드 덤프를 남기는 기능을 제공한다면, watchdog은 특정 이벤트를 감지하는 역할을 합니다.
watchdog은 파이썬에서 많이 활용되는 파일 시스템 감시 라이브러리로, 파일이 수정되거나 새로 생성될 때 이벤트를 트리거할 수 있습니다.
이 기능을 활용하면 단순히 로그 파일 변화를 감시하는 것을 넘어서, 특정 상황에서 스레드 덤프를 자동으로 실행하도록 만들 수 있습니다.

예를 들어 “trigger.dump”라는 파일이 생성되면 watchdog이 이를 감지하고, 즉시 faulthandler를 호출하여 스레드 덤프를 남길 수 있습니다.
이는 외부에서 파일만 생성하면 곧바로 덤프를 얻을 수 있기 때문에, 서비스 중단 없이 진단 작업을 수행할 수 있는 장점이 있습니다.

📌 watchdog 기본 구조

from watchdog.observers import Observer
from watchdog.events import FileSystemEventHandler
import time

class Handler(FileSystemEventHandler):
    def on_created(self, event):
        if event.src_path.endswith("trigger.dump"):
            print("덤프 실행 트리거 감지!")

observer = Observer()
observer.schedule(Handler(), path=".", recursive=False)
observer.start()

try:
    while True:
        time.sleep(1)
except KeyboardInterrupt:
    observer.stop()

observer.join()

위 코드에서는 현재 디렉토리를 감시하고 있다가, trigger.dump라는 파일이 생성되면 이벤트가 발생합니다.
여기에 faulthandler 호출을 추가하면 곧바로 스레드 상태를 기록할 수 있습니다.

📌 watchdog의 활용 시나리오

watchdog은 단순히 파일 이벤트뿐 아니라 여러 상황에 적용할 수 있습니다.
운영 환경에서는 다음과 같은 방식으로 활용할 수 있습니다.

• 📂특정 제어 파일 생성 시 스레드 덤프 트리거
• 🔔로그 파일에 특정 키워드 발생 감지
• 🖥️운영자가 수동으로 덤프 실행 요청 가능

⚙️ watchdog과 faulthandler 연동하기

이제 핵심은 watchdog과 faulthandler를 함께 사용하는 것입니다.
watchdog이 특정 이벤트를 감지하면 즉시 faulthandler를 호출해 스레드 덤프를 남기는 방식이죠.
이 조합을 사용하면 운영자가 별도로 디버거를 붙이지 않아도 프로그램 내부 상태를 기록할 수 있습니다.

예를 들어 trigger.dump라는 파일이 생성되면 watchdog이 이를 감지하고, faulthandler가 모든 스레드의 현재 상태를 파일로 남기도록 설정할 수 있습니다.
이렇게 하면 서비스가 멈춰도 간단히 파일 하나 생성만으로 원인 파악을 위한 자료를 확보할 수 있습니다.

📌 연동 코드 예제

import faulthandler
from watchdog.observers import Observer
from watchdog.events import FileSystemEventHandler
import time, threading

# 덤프 출력 파일 설정
faulthandler.enable(open("thread_dump.log", "w"))

class DumpHandler(FileSystemEventHandler):
    def on_created(self, event):
        if event.src_path.endswith("trigger.dump"):
            print("스레드 덤프 실행!")
            faulthandler.dump_traceback()

observer = Observer()
observer.schedule(DumpHandler(), path=".", recursive=False)
observer.start()

try:
    while True:
        time.sleep(1)
except KeyboardInterrupt:
    observer.stop()
observer.join()

위 예제에서는 현재 디렉토리에 trigger.dump 파일이 생성되면 faulthandler가 즉시 thread_dump.log 파일에 스레드 상태를 남깁니다.
이 로그에는 실행 중인 모든 스레드의 호출 스택이 기록되어 문제 원인을 추적하는 데 활용할 수 있습니다.

📌 실무 적용 팁

이 방법은 특히 운영 환경에서 유용합니다.
프로세스가 응답하지 않을 때 관리자나 모니터링 시스템이 단순히 trigger.dump 파일을 생성하기만 하면 곧바로 덤프가 수집됩니다.
이는 서비스 중단 시간을 줄이고, 원인 파악 속도를 높여 장애 대응력을 강화할 수 있습니다.

💡 운영 환경에서의 적용 팁

watchdog과 faulthandler를 연동하면 강력한 디버깅 도구가 되지만, 운영 환경에서 바로 적용하려면 몇 가지 고려해야 할 점이 있습니다.
자동화된 스레드 덤프 수집은 문제 원인 분석에 큰 도움이 되지만, 로그 관리와 성능에 신경 쓰지 않으면 오히려 시스템에 부담이 될 수 있습니다.

📌 로그 관리 전략

스레드 덤프는 모든 스레드의 호출 스택을 기록하기 때문에 로그 크기가 빠르게 커질 수 있습니다.
따라서 로그 순환(rotation) 정책을 설정하여 오래된 덤프를 자동으로 삭제하거나 별도의 보관소로 이동시키는 것이 중요합니다.
또한 운영 환경에서는 로그를 단순히 텍스트 파일로 저장하기보다 중앙 로그 관리 시스템과 연계해 검색 가능하게 만드는 것이 효율적입니다.

📌 성능 고려사항

덤프 수집 자체는 큰 부하를 주지 않지만, 너무 잦은 수집은 I/O 성능에 영향을 줄 수 있습니다.
특히 CPU 점유율 급등이나 네트워크 지연이 발생했을 때마다 자동 덤프를 남기면 운영 환경이 불안정해질 수 있습니다.
따라서 필요한 시점에만 트리거가 발생하도록 설계하는 것이 바람직합니다.

📌 보안 및 접근 제어

덤프 로그에는 코드 실행 위치와 내부 함수 호출 정보가 담기므로 민감한 데이터로 분류될 수 있습니다.
따라서 권한이 없는 사용자가 덤프를 열람하지 못하도록 접근 제어를 강화해야 합니다.
운영 환경에서는 반드시 권한 분리를 적용해 개발자와 운영자의 접근 권한을 구분하는 것이 좋습니다.

❓ 자주 묻는 질문 (FAQ)