Python 3.14의 sys.remote_exec()를 활용해 Kubernetes나 Docker에서 실행 중인 Python 프로세스에 준비 없이 debugpy를 주입해 원격 디버깅을 가능하게 하는 도구 debugwand를 소개합니다.
URL: https://savannah.dev/posts/the-coolest-feature-in-314/
Title: Python 3.14에서 가장 멋진 기능
아마 이미 아시겠지만, 저는 컨테이너를 정말 좋아합니다. 컨테이너는 자유로움과 사용 편의성이라는 측면에서 진정으로 마법 같고 놀라운 기술이라고 생각해요. 하지만 컨테이너(또는 Kubernetes)를 사용하면 워크플로에 복잡성이 더해질 수 있습니다. 소프트웨어를 컨테이너에 넣는 순간, 로컬 개발 환경과 우리가 만들고 있는 소프트웨어 사이에 자연스럽게 약간의 장벽이 생기죠. 물론 Dev Container를 쓰고 있다면 이야기가 좀 더 메타해지긴 하지만… 딴 얘기였네요.
컨테이너나 Kubernetes를 사용할 때 마찰이 생기는 영역 중 하나가 바로 디버깅 워크플로입니다. Docker Compose나 Kubernetes로 실행 중인 그 FastAPI 앱 말이죠? 네, VS Code에서 launch.json을 설정하고 실행한다고 해서 디버거가 예전처럼 알아서 “마법처럼” 연결되진 않습니다. 클러스터에서 디버깅을 돌리기 위해 어떤 사이드카 서비스를 따로 세팅해본 적이 있을지도 모르고요. 또는 코드에 debugpy를 추가하고, 연결을 기다리도록 설정한 다음, 파드를 재시작하고, 포트 포워딩을 잡아두고, 연결할 때까지 앱이 여전히 원하는 상태이길 바라 본 적도 있을 겁니다. 아, 그리고 거기에 uvicorn --reload까지 얹으면… 아아아아아. 이런 것들을 설정하는 건 진짜 골치 아프고, 솔직히 말해서 지금 해야 하는 일의 본질과는 거리가 멉니다! 그냥 만들고 있는 앱을 디버깅하고 싶었을 뿐인데요!
그래서 저는 debugwand라는 도구를 만들었습니다. Kubernetes 클러스터나 Docker 컨테이너에서 실행 중인 Python 애플리케이션을 위한, 준비(사전 작업) 없이 쓰는 원격 디버거입니다. debugwand를 쓰면 사이드카 파드도 필요 없고, 애플리케이션 코드 변경도 필요 없고, 사실상 거의 설정이 필요 없습니다(좋아요, 아주 쬐끔은요… 설정이긴 합니다!).
컨테이너들은 내가 오는 걸 싫어하지
어떻게 가능하냐고요? 여기서 이 모든 것을 가능하게 해 주는 Python 3.14의 아마도 가장 멋진 단일 기능(좋아요, 좋아요… 좀 과장했어요 — 자식 중에 최애를 고르는 느낌이랄까!)을 소개해야 합니다: sys.remote_exec(). sys.remote_exec()를 사용하면, 재시작 없이 이미 실행 중인 다른 프로세스 내부에서 Python 스크립트를 실행할 수 있습니다. 스크립트는 대상 프로세스의 메모리, 모듈, 상태에 완전한 접근 권한을 가진 채 실행되며, 이는 필요할 때 즉석으로 디버그 서버를 띄우는 데 딱 필요한 조건입니다.
wand debug를 실행하면, CLI가 다음을 수행합니다:
대상을 찾습니다 - Kubernetes의 경우, 서비스에 해당하는 파드를 찾아냅니다(물론 Knative도 처리합니다. 왜냐하면 여러분이 Knative를 쓰고 있을 테니까요). Docker의 경우에는 컨테이너를 지정해 주기만 하면 됩니다.
프로세스를 고릅니다 - 파드/컨테이너에서 실행 중인 모든 Python 프로세스를 CPU 및 메모리 통계와 함께 찾아, (가능한 한) 올바른 프로세스를 선택합니다. uvicorn --reload를 실행 중인가요? 그것도 자동으로 감지합니다(원한다면 다른 프로세스를 디버깅하도록 선택을 언제든지 바꿀 수 있습니다).
debugpy를 주입합니다 - 여기서 sys.remote_exec()가 제 역할을 합니다. debugwand는 debugpy 서버를 시작하는 작은 스크립트를 작성한 뒤, 실행 중인 프로세스에 주입합니다. 재시작도 없고. 코드 변경도 없고. 앱은 아무 일도 없었던 것처럼 계속 요청을 처리합니다.
연결을 설정합니다 - Kubernetes에서는 포트 포워딩을 자동으로 처리합니다. Docker에서는 컨테이너 시작 시 포트를 노출시키기만 하면 됩니다.
에디터를 연결합니다 - VS Code(또는 nvim, 또는 여러분이 좋아하는 어떤 DAP 클라이언트든)를 localhost:5679(원한다면 다른 포트도 선택 가능)에 연결하면 디버깅이 됩니다. 브레이크포인트 설정, 변수 확인, 코드 단계 실행… 다 됩니다.
전체 플로우는 설정을 몇 분 정도만 해두면 바로 달릴 수 있어야 합니다! 꽤 멋지지 않나요?
짧은 참고: 이 도구는 실험적이며 로컬 개발을 목적으로 합니다.
SYS_PTRACE기능을 활성화하는 것은 보안상 고려해야 할 점이 있으니, 프로덕션에 가까운 곳에서는 사용하기 전에 꼭 생각해 보세요(그러지 마세요!).
이건 주로 호기심과 회사에서의 워크플로를 위해 만들었지만, 여러분도 편하게 한번 써보셔도 됩니다! Python 3.14를 사용 중이라면 uv tool install debugwand로 설치해 보세요(PyPI는 여기).
그 다음에는 아래가 필요합니다:
그 다음은 그냥:
# Kubernetes
wand debug -n my-namespace -s my-service
# Docker
wand debug --container my-container
이제 출발입니다! 디버거를 켜고 브레이크포인트를 찍기만 하면 됩니다!
debugwanddebugwand