SIGTERM 뒤 60초를 누가 얼마나 쓰는지 정했다 초안
지금 이 봇이 SIGTERM을 받으면 60초는 이렇게 쓰인다. 종료 시작부터 50초까지가 진행 중인 외부 호출(최대 25초)과 백그라운드 tick 정리의 몫이고, 마지막 10초는 PTB의 shutdown과 로그 정리의 몫이다.
전에는 이 60초를 누가 얼마나 쓰는지 정해 둔 적이 없었다. 커뮤니티용 텔레그램 봇을 python-telegram-bot(이하 PTB)으로 만들어 Docker 컨테이너에서 돌리는데, 배포가 잦아서 컨테이너가 하루에 여러 번 새로 만들어진다. 그 순간 진행 중이던 일이 조용히 사라지는 문제를 2026년 7월 말과 10월 말에 서로 다른 모양으로 겪었다.
7월 말, “번역 중”만 남기고 사라진 두 건
배포 순간에 진행 중이던 번역 두 건이 “번역 중” 자리표시자 메시지만 남기고 사라졌다. 결과도 오류 메시지도 오지 않았다. 로그를 보니 같은 프로세스에서 도는 두 번째 봇 애플리케이션은 종료 완료 로그(Application.stop() complete)조차 찍지 못했다.
docker stop이나 컨테이너 교체는 프로세스에 SIGTERM을 보내고, 정해진 유예 시간 안에 끝나지 않으면 SIGKILL로 죽인다. compose 파일의 stop_grace_period가 그 유예이고 60초로 두고 있었다. 그런데 봇이 번역하려고 subprocess로 부르는 외부 CLI 호출 하나가 최대 180초, 재시도까지 하면 360초를 매달릴 수 있었다. PTB는 SIGTERM을 받으면 진행 중인 핸들러가 끝나기를 기다리며 종료 절차를 밟는다. 핸들러가 180초짜리 호출을 붙잡고 있으면 종료는 60초 안에 끝나지 않고, 정리 코드도 못 돌린 채 컨테이너째 SIGKILL된다. 종료 완료 로그가 없었던 이유다.
죽은 뒤에 그 일을 다시 집어 줄 장치도 없었다. 번역할 원문을 봇이 스스로 올린 경우였는데, 봇이 자기 손으로 올린 메시지는 update로 돌아오지 않는다. 폴링도 drop_pending_updates=True로 시작하고 있었다. 재부팅한 봇은 그 일이 있었다는 사실 자체를 모른다.
종료가 시작되면 호출에 25초만 준다
먼저 “지금 내려가는 중인가”를 한 곳에서 판정하게 했다. SIGTERM 핸들러를 직접 걸지는 않았다. PTB가 이미 그 시그널에 자기 종료 절차를 걸어 두었고, 덮어쓰면 PTB의 종료가 망가진다. 대신 PTB의 상태 플래그를 본다. Application.running은 종료 절차에 들어가면 내려간다.
함정이 하나 있었다. 부팅 직후에는 running이 아직 False다. 그대로 종료로 읽으면 부팅 때 재개되는 작업이 시작하자마자 끊긴다. 한 번이라도 True를 본 뒤에만 False를 종료로 읽는다.
_seen_running = False
def is_stopping() -> bool:
global _seen_running
if _probe is None: # 테스트나 단독 실행
return False
running = bool(_probe()) # main 이 lambda: app.running 을 등록해 둔다
if running:
_seen_running = True
return False
return _seen_running # 부팅 직후의 False 를 종료로 읽지 않는다
외부 CLI를 띄울 때마다 감시 task 하나를 같이 붙인다. 종료가 시작되면 유예 25초를 기다렸다가 subprocess를 죽이고, 호출이 정상적으로 끝나면 감시 task는 취소된다.
async def _kill_on_shutdown(proc) -> None:
await shutdown.wait_for_stop() # 종료 시작을 기다리고, 유예 25초를 더 기다린다
try:
proc.kill()
except Exception:
pass
유예 안에 끝난 호출은 결과가 정상적으로 나간다. 못 끝낸 호출은 전용 예외로 구분한다. 고장이 아니라 아직 못 끝낸 일이라서, 사용자에게 오류 메시지를 띄우지 않고 재개 대상에서도 지우지 않는다.
끊긴 일을 다시 집으려면 어딘가에 적혀 있어야 한다. 번역은 착수하기 전에 작업 내용을 파일 원장에 적고, 끝나면 지운다. 못 끝내고 내려갔으면 다음 부팅이 원장을 읽어 마저 돌리고, 이미 나간 부분은 발송 기록을 보고 건너뛴다. 평소 실행과 재개는 같은 함수를 타게 했다. 재개 전용 코드를 따로 두면 평소에는 한 번도 실행되지 않다가 필요한 날 깨져 있기 쉽다.
10월 하순, 1시간 41분짜리 오디오 전사가 4분 만에 끊겼다
전사를 시작한 지 4분 만에 배포가 들어왔다. “전사 중…” 표시만 남았고 아무 알림도 없었다.
긴 음성 전사에는 번역과 다른 방식을 썼다. 작업을 시작할 때 “진행 중” 표시를 남긴다. 다음 부팅에 그 표시가 남아 있으면 배포로 끊긴 것이므로, 새 메시지로 알리고 처음부터 다시 전사한다. 기존 메시지를 고치지 않고 새 메시지를 보내는 건 알림이 울리게 하려는 것이다. 배포와 상관없는 실패라면 표시를 지워서 자동 재시작 대상에서 뺀다. 같은 작업이 두 번 넘게 끊기면 다시 돌리지 않고 안내만 한다.
며칠 뒤, 발송이 두 목적지 중 한 곳에만 나갔다
자동 발송 한 건의 다른 사본이 끝내 오지 않았다. 로그에는 asyncio의 경고가 남아 있었다.
Task was destroyed but it is pending!
자동 발송은 asyncio.create_task로 띄운 백그라운드 루프가 주기적으로 처리한다. 한 번 도는 것을 tick이라고 부른다. 이 task는 PTB가 모르는 task라서 PTB의 종료 순서 어디에서도 기다려 주지 않는다. 이벤트 루프가 닫힐 때 아직 끝나지 않은 task는 그대로 버려진다. tick이 await 중이었다면 그 지점에서 멈춘 채 사라지고 CancelledError도 전달되지 않아서, try/finally로 정리할 기회조차 없다. 위 경고가 그 흔적이다.
여기에 기록 순서가 겹쳤다. “이 건은 처리했음” 표시를 발송 전에 저장하고 있었다. 첫 목적지에 보낸 뒤 둘째 목적지로 보내기 전에 tick이 버려졌는데 표시는 이미 저장돼 있었으니, 다음 부팅의 tick은 그 건을 건너뛰었다.
작은 공용 모듈을 하나 만들어 막았다. 루프는 tick 사이에 asyncio.sleep 대신 nap으로 잔다. 종료 신호가 오면 잠에서 바로 깨고, True를 받은 루프는 새 tick을 열지 않고 빠져나온다. 돌던 tick은 끝까지 간다.
async def nap(seconds: float) -> bool:
"""seconds 동안 자거나 종료 신호에 깬다. 종료 중이면 True."""
ev = _event()
if ev.is_set():
return True
try:
await asyncio.wait_for(ev.wait(), timeout=seconds)
except asyncio.TimeoutError:
pass
return ev.is_set()
루프 쪽은 await asyncio.sleep(n) 한 줄이 if await nap(n): return으로 바뀐다. 종료 신호는 0.5초마다 위의 is_stopping()을 보는 감시 task가 켠다.
루프 task는 이 모듈에 등록한다. 요청 처리 뒤에 떼어 보내던 일회성 task들도 같은 모듈을 거쳐 띄운다. 그냥 create_task로 던진 task는 종료 때 아무도 기다리지 않고, 참조가 없으면 가비지 컬렉션될 수 있다는 것이 asyncio 문서의 경고이기도 하다.
등록된 task들이 끝나기를 기다리는 자리는 PTB의 post_stop 훅이다. post_stop은 Application.stop() 뒤, Application.shutdown() 앞에 불린다. 봇의 HTTP 클라이언트가 아직 열려 있는 시점이라 돌던 tick의 발송이 실제로 나간다. post_shutdown에서 기다렸다면 보낼 수단이 이미 닫혀 있다.
50초에서 앞 단계가 쓴 만큼 뺀다
기다리는 시간은 고정값으로 두지 않았다. 종료가 시작된 시각을 기록해 두고, “종료 시작 후 50초까지 남은 시간”만큼만 기다린다. 앞 단계에서 PTB가 핸들러를 기다리며 이미 시간을 썼을 수 있어서다. 진행 중이던 외부 호출이 25초 유예를 다 썼다면 남은 예산은 그만큼 줄어든다. 최소 3초는 보장하고, 기한 안에 못 끝낸 task는 취소한다.
그래도 60초 안에 못 끝나는 날은 있다. 그래서 “보냈음” 기록의 단위를 바꿨다. 건 단위로 발송 전에 찍던 것을, 목적지 단위로 보낸 뒤에 찍는다. 다음 tick은 원장을 보고 아직 안 나간 목적지만 잇는다. 여러 부분을 차례로 내보내는 발송은 이미 나간 부분을 빼고 남은 것만 보낸다. 끝내 못 이은 항목이 영원히 남지 않도록 미완료 기록에 만료 시간을 둔 것도 있다.