Mar 24, 2026

마지막 업데이트 Mar 30, 2026

Python Celery task가 멈춰 있을 때 트러블슈팅 가이드

Celery task가 queue에 남아 있거나 끝나지 않는다면, 원인은 broker 흐름, worker 가용성, acknowledgement 동작, retry, 혹은 task 내부 dependency 지연일 수 있습니다.

그래서 “task가 멈췄다”는 말만으로는 아직 진단이 아닙니다. 어떤 task는 아예 pickup되지 않고, 어떤 task는 pickup된 뒤 reserved 상태로 오래 남거나, retry/requeue를 반복하면서 겉으로만 다른 문제처럼 보이기도 합니다.

이 글은 실전 순서에 집중합니다.

queued task와 executing-but-stuck task를 어떻게 나눌지
worker, broker 흐름, task 실행 안에서 무엇을 먼저 볼지
ack와 retry가 장애 모습을 어떻게 왜곡할 수 있는지

짧게 말하면 작업이 queue에서 기다리는지, 가져간 뒤 끝나지 않는지 먼저 구분하고, 그다음 worker 상태, broker 전달, dependency latency, retry 동작 순서로 보는 편이 가장 빠릅니다.

더 넓은 Python 분기부터 다시 보고 싶다면 Python 트러블슈팅 가이드로 가세요.

먼저 queue 상태부터 보기

가장 먼저 물어볼 질문은 task가 queue에서 기다리는지, worker가 가져간 뒤 끝나지 않는지입니다.

이 분기는 Celery 설정을 무작정 바꾸는 것보다 훨씬 빠르게 범위를 줄여줍니다.

아래 같은 장애를 나눠주기 때문입니다.

worker가 죽었거나 consuming을 안 함
task가 reserved됐지만 실행 중 막힘
retry가 같은 failing work를 계속 돌려보냄

이 첫 분기 없이 보면 broker backlog를 worker 속도 문제로 오해하거나, worker 실행 문제를 broker 문제로 오해하기 쉽습니다.

queued와 executing의 차이가 중요한 이유

운영에서는 이 둘의 의미가 완전히 다릅니다.

queued task는 worker availability, routing, broker, prefetch 문제 가능성이 큼
executing task가 안 끝나는 것은 dependency latency, deadlock, resource starvation, retry confusion 가능성이 큼

두 문제가 함께 보일 수는 있지만, 대개는 어느 쪽이 더 먼저 봐야 할 branch인지가 존재합니다.

자주 나오는 원인

1. worker가 소비하지 않는다

queue가 커지는 이유가 worker unavailable, misconfiguration, disconnect, 잘못된 queue binding일 수 있습니다.

자주 보이는 단서는 아래와 같습니다.

queue length는 늘는데 active execution은 낮음
worker가 내려갔거나, 끊겼거나, 예상외로 idle함
최근 routing이나 queue binding이 바뀜

이 경우 task code보다 먼저 delivery와 consumption을 봐야 합니다.

2. 실행 중 task가 끝나지 않는다

dependency, lock, 장수 작업 경로 하나가 task 완료를 계속 늦출 수 있습니다.

예를 들면:

느린 DB나 외부 API를 기다림
CPU-heavy 작업이 생각보다 오래 걸림
내부 lock이나 shared resource를 기다림
error path가 completion으로 이어지지 않음

이 경우 queue 증상은 뒤따라오는 결과이고, 실제 문제는 worker가 작업을 너무 오래 붙잡는 데 있습니다.

3. ack / retry가 그림을 흐린다

retry나 late ack는 하나의 failing task를 여러 다른 문제처럼 보이게 만들 수 있습니다.

예를 들면:

한 task가 실패 후 계속 requeue되어 queue가 안 줄어듦
late ack 때문에 실제로는 실패/재시도인데 stuck처럼 보임
poison task 하나가 반복되면서 worker capacity를 계속 먹음

그래서 retry-heavy 장애는 queue growth와 worker exhaustion이 동시에 보이는 경우가 많습니다.

실전 점검 순서

Celery task가 멈춰 보일 때는 아래 순서가 가장 도움이 됩니다.

queued task와 executing task 구분
worker availability, routing, broker flow 확인
task 내부 long-running dependency 확인
ack와 retry 설정 검토
delivery 문제인지, execution 문제인지, retry churn인지 판단

이 순서가 중요한 이유는 두 가지 흔한 실수를 막기 때문입니다.

work가 실제로 소비되는지도 모르면서 Celery 설정부터 만지는 실수
실제 문제는 task runtime인데 broker 탓부터 하는 실수

worker 프로세스 구조도 함께 수상하면 Python worker 메모리 중복이 커질 때와 같이 보세요.

아주 작은 예시가 보여주는 운영 질문

celery -A proj worker --loglevel=info --concurrency=4

worker가 떠 있어도 broker 전달, ack 동작, prefetch 설정이 어긋나면 task가 reserved 상태로 오래 머무를 수 있습니다.

이 명령 자체보다 중요한 것은 시스템이 일을 못 받고 있는지, 받고 나서 못 끝내는지 구분하는 것입니다.

stuck task마다 물어볼 질문

각 task 경로마다 아래를 물어보면 도움이 됩니다.

worker가 task를 언제 처음 받는가
task가 어떤 외부 dependency를 기다리는가
task는 언제 acknowledged되는가
중간에 실패하면 어떤 일이 생기는가

이 프레이밍이 좋은 이유는 Celery 장애가 단순한 queue 문제보다 lifecycle과 ownership 문제인 경우가 많기 때문입니다.

FAQ

Q. queue가 커지면 항상 worker가 죽은 건가요?

아닙니다. task가 너무 오래 돌거나, retry가 많거나, worker가 느린 dependency에 붙잡혀 있어도 queue는 커질 수 있습니다.

Q. 운영에서 무엇부터 보는 게 가장 빠른가요?

task가 pickup되지 않는지, pickup된 뒤 끝나지 않는지 구분하는 것이 가장 빠릅니다. 이 분기 하나가 다음 branch를 거의 결정합니다.

Q. 하나의 나쁜 task가 전체 queue를 망칠 수 있나요?

네. retry가 붙은 poison task나 hold time이 긴 task 하나가 worker capacity를 계속 먹으면서 전체 queue 그림을 왜곡할 수 있습니다.

먼저 읽어볼 가이드

검색 유입이 많은 핵심 글부터 이어서 보세요.