benfred/py-spy

어떤 프로젝트인가요?

핵심 기능

• 01코드를 수정하거나 프로세스를 재시작하지 않고 PID로 실행 중인 Python 프로세스에 연결합니다.
• 02flame graph를 SVG, speedscope 프로파일 또는 raw 데이터 형식으로 출력합니다.
• 03시간을 가장 많이 쓰는 함수를 실시간으로 보여주는 `top` 뷰를 제공합니다.
• 04선택적으로 로컬 변수를 포함해 모든 스레드의 호출 스택을 덤프합니다.
• 05GIL을 보유한 스레드만 대상으로 필터링하고 네이티브 확장을 프로파일링할 수 있습니다.
• 06multiprocessing이나 gunicorn 워커 같은 자식 프로세스를 추적합니다.

활용 사례

• 서비스를 재배포하지 않고 프로덕션 Python 서비스에서 느린 함수를 찾습니다.
• 현재 스레드 스택을 덤프해 응답이 멈춘 프로세스를 진단합니다.
• py-spy record로 스크립트를 실행해 프로파일링합니다.
• Python 프레임과 함께 Cython 또는 C 확장의 CPU 핫스팟을 분석합니다.

빠른 시작

1. 1

   PyPI에서 미리 빌드된 바이너리 설치

   pip install py-spy
2. 2

   실행 중인 프로세스를 프로파일링하고 플레임 그래프 작성

   py-spy record -o profile.svg --pid 12345
3. 3

   실행 중인 프로세스의 top 스타일 실시간 요약 보기

   py-spy top --pid 12345

사용 전 알아둘 점

• !Linux에서 다른 프로세스를 프로파일링하려면 일반적으로 root 권한이 필요합니다.
• !OSX에서는 항상 root 권한이 필요하며, System Integrity Protection으로 인해 기본 제공되는 /usr/bin/python의 프로파일링이 차단됩니다.
• !네이티브 확장 프로파일링(--native)은 일부 플랫폼 및 아키텍처 조합에서만 사용할 수 있습니다.

토픽

자주 묻는 질문

py-spy은(는) 무엇인가요?

코드를 수정하거나 프로세스를 재시작하지 않고 실행 중인 프로세스에 연결하는 Python 프로그램용 샘플링 프로파일러입니다. py-spy를 사용하면 실행 중인 Python 프로그램이 어디에서 시간을 쓰는지 확인할 수 있습니다. 대상 프로세스 외부에서 샘플링하므로 코드를 수정하거나 import를 추가하거나 프로그램을 재시작할 필요가 없습니다. Rust로 작성되어 프로파일링 대상과 별도의 프로세스로 실행되며, 오버헤드가 낮아 프로덕션 서비스에도 사용할 수 있습니다.

py-spy은(는) 무료로 사용할 수 있나요? 라이선스는 무엇인가요?

py-spy은(는) MIT 라이선스의 오픈소스입니다. 상업용 제품에 사용하기 전에 라이선스 조건을 확인하세요.

py-spy은(는) 아직 유지보수되고 있나요?

활발히 유지보수 중. py-spy의 마지막 커밋은 2026년 11월 6일입니다.

py-spy은(는) 어디에 사용할 수 있나요?

서비스를 재배포하지 않고 프로덕션 Python 서비스에서 느린 함수를 찾습니다. 현재 스레드 스택을 덤프해 응답이 멈춘 프로세스를 진단합니다. py-spy record로 스크립트를 실행해 프로파일링합니다. Python 프레임과 함께 Cython 또는 C 확장의 CPU 핫스팟을 분석합니다.

py-spy는 어떻게 설치하나요?

PyPI에서 미리 빌드된 바이너리 설치: pip install py-spy 실행 중인 프로세스를 프로파일링하고 플레임 그래프 작성: py-spy record -o profile.svg --pid 12345 실행 중인 프로세스의 top 스타일 실시간 요약 보기: py-spy top --pid 12345

py-spy은(는) 어디서 받을 수 있나요?

소스 코드와 설치 방법은 GitHub에 있습니다: https://github.com/benfred/py-spy