Python 서비스가 이상해지기 시작할 때 가장 어려운 건 고치는 방법보다도, 어떤 증상을 기준으로 조사를 시작해야 하는지 고르는 일입니다.
짧게 말하면, 익숙한 라이브러리나 설정부터 건드리지 말고 가장 눈에 띄는 증상부터 잡아야 합니다. 그다음 그 증상과 가장 잘 맞는 분기 글로 들어가는 편이 훨씬 빠릅니다.
이 글은 이 블로그의 Python 트러블슈팅 허브로 쓰면 됩니다.
가정보다 보이는 증상부터 잡으세요
Python 장애는 초반에 비슷해 보여도 실제 원인은 꽤 다릅니다.
팀이 처음 보게 되는 증상은 보통 아래 중 하나입니다.
- 메모리가 계속 늘어난다
- 로그가 비거나 불완전하다
- task가 끝나지 않는다
- CPU는 뜨거운데 처리량은 떨어진다
- worker 수를 늘렸더니 오버헤드가 커졌다
- DB나 외부 네트워크 경계에서 요청이 오래 머문다
이 증상들은 한 가족이 아닙니다. 메모리 유지 문제인데 로그부터 만지거나, backlog 문제인데 worker 수부터 올리면 오히려 상황이 더 꼬일 수 있습니다.
빠르게 나누는 Python 분기 지도
가장 빠른 첫 분기는 이렇게 잡으면 됩니다.
- 메모리 증가, retained object, cache 확장: 메모리 글부터
- 로그 누락, handler 혼선, 관측성 부족: 로그 글부터
- asyncio 작업 정체, 조기 취소, event loop 멈춤: asyncio 글부터
- worker 중복, CPU 압박, 프로세스 수 변화: runtime / worker 글부터
- Celery backlog, Gunicorn 재시작, DB pool 고갈: 운영형 pressure 글부터
첫 단계에서 완벽한 진단은 필요하지 않습니다. 가장 신호가 강한 첫 분기만 고르면 됩니다.
메모리 문제처럼 보일 때
아래 증상이 보이면 Python Memory Usage High부터 보세요.
- 특정 프로세스 또는 모든 worker 메모리가 계속 커진다
- 트래픽이 줄어도 메모리가 잘 내려오지 않는다
- 큰 payload나 cache가 의심된다
- worker 수를 바꾼 뒤 메모리가 확 뛰었다
worker 프로세스를 늘린 뒤 메모리 사용량이 특히 커졌다면 Python Worker Memory Duplication로 이어가면 좋습니다.
로그 또는 관측성 문제처럼 보일 때
아래 증상이면 Python Logging Not Showing부터 보세요.
- 운영 환경에서 로그가 비어 있다
basicConfig()가 먹지 않는 것처럼 보인다- 환경마다 log level이 다르게 동작한다
- handler, propagation, formatting이 일관되지 않다
이 분기는 중요한데, 관측성이 약하면 다른 모든 조사 단계가 막히기 쉽기 때문입니다.
asyncio 조정 문제처럼 보일 때
비동기 coordination 문제가 의심되면 아래 글들부터 들어가면 됩니다.
핵심은 task가 영원히 기다리는지, 너무 일찍 취소되는지, 아니면 동기 작업이 event loop를 막아 스케줄링 자체가 깨지는지 구분하는 것입니다.
worker나 queue pressure처럼 보일 때
운영형 backlog 또는 처리량 압박으로 보이면 아래 글이 더 잘 맞습니다.
- Python CPU Usage High
- Python Celery Tasks Stuck
- Python Celery Worker Concurrency Low
- Python ThreadPoolExecutor Queue Growing
이 글들은 시스템이 accepted work를 completed work로 잘 바꾸지 못하는 상황에서 특히 유용합니다.
프로세스 또는 배포 형태 문제처럼 보일 때
배포 후에 증상이 달라졌거나 process model이 바뀐 뒤부터 이상하다면 아래 분기가 좋습니다.
애플리케이션 로직이 크게 바뀌지 않았는데 worker 수, preload 전략, 배포 형태만 바뀌고 증상이 나타났다면 이쪽이 더 가깝습니다.
downstream 자원 고갈처럼 보일 때
아래 증상이면 Python Database Connections Not Closed부터 보세요.
- DB 근처에서 요청이 쌓인다
- crash보다 pool exhaustion이 먼저 보인다
- 메모리나 CPU보다 connection starvation이 더 먼저 드러난다
Python 서비스는 실제 원인이 connection pool인데도 처음엔 단순한 slowdown처럼 보이는 경우가 많습니다.
실전 조사 순서
증상이 애매할 때는 아래 순서가 안전합니다.
- 지금 관측 정보가 믿을 만한지 먼저 확인합니다
- 시스템이 멈춘 건지, 느린 건지, 계속 불어나는 건지 구분합니다
- 메모리 압박과 처리량 압박을 나눕니다
- asyncio coordination 문제와 process-level capacity 문제를 나눕니다
- 가장 강한 증상과 맞는 좁은 글로 이동합니다
이 순서가 관련 없는 해결책을 여러 개 읽는 것보다 훨씬 빠른 경우가 많습니다.
FAQ
Q. 이 글은 Python 설정 가이드인가요?
아니요. 증상 기준으로 다음 분기를 정하는 허브 글입니다.
Q. 로그 누락과 메모리 증가가 같이 보이면 어디부터 볼까요?
메모리 진단을 신뢰하기 어려울 정도로 관측성이 약하면 로그부터 보세요. 그렇지 않다면 먼저 나타난 증상부터 가면 됩니다.
Q. Celery, asyncio, API timeout이 한꺼번에 보이면요?
가장 먼저 backlog나 stall이 보인 지점부터 잡으세요. 여러 증상은 종종 하나의 초기 병목에서 시작됩니다.
Q. queue 모양도 모르는데 worker 수부터 조정해도 될까요?
보통은 아닙니다. process 수를 바꾸면 메모리 오버헤드만 늘고 실제 원인을 가릴 수 있습니다.
Read Next
- 메모리 증가가 가장 뚜렷하면 Python Memory Usage High를 보세요.
- 관측성이 막히는 느낌이면 Python Logging Not Showing를 보세요.
- asyncio coordination이 깨진 것 같다면 Python asyncio Tasks Not Finishing를 보세요.
- backlog나 worker pressure가 더 선명하면 Python Celery Tasks Stuck를 보세요.
Related Posts
- Python Memory Usage High
- Python Logging Not Showing
- Python asyncio Tasks Not Finishing
- Python asyncio Event Loop Blocked
- Python Worker Memory Duplication
- Python CPU Usage High
- Python Celery Tasks Stuck
- Python Database Connections Not Closed
심사 대기 중에는 광고 대신 관련 가이드를 먼저 보여줍니다.
먼저 읽어볼 가이드
검색 유입이 많은 핵심 글부터 이어서 보세요.
- 미들웨어 트러블슈팅 가이드: Redis vs RabbitMQ vs Kafka 개발자를 위한 미들웨어 트러블슈팅 허브 글입니다. Redis, RabbitMQ, Kafka 중 어떤 증상부터 먼저 봐야 하는지와 어떤 문제 패턴이 각 시스템에 가까운지 정리합니다.
- Kubernetes CrashLoopBackOff: 먼저 볼 것들 startup failure, probe, config, resource limit 관점에서 CrashLoopBackOff를 어떻게 나눠서 봐야 하는지 정리한 가이드입니다.
- Kafka consumer lag가 계속 늘 때: 트러블슈팅 가이드 Kafka consumer lag가 계속 늘어날 때 무엇부터 봐야 하는지 정리합니다. poll 주기, 처리 속도, rebalance, consumer 설정까지 실전 기준으로 다룹니다.
- Kafka Rebalancing Too Often 가이드 Kafka consumer group에서 rebalance가 너무 자주 일어날 때 membership flapping, poll timing, protocol, assignment churn을 어떤 순서로 봐야 하는지 설명하는 실전 가이드입니다.
- Docker container가 계속 재시작될 때: 먼저 확인할 것들 exit code, command failure, environment mistake, health check 관점에서 Docker restart loop를 푸는 실전 가이드입니다.
심사 대기 중에는 광고 대신 관련 가이드를 먼저 보여줍니다.