진행 기간: 2026.05 2026.07 > 기여 전체 개요는 Playground 문서 파싱 파이프라인 — 기여 개요 참고. 본 글은 그중 메모리·프로세스·이미지 크기 안정화만 모은 기록이다. 문서 파싱 서비스를 운영하면서 겪은 리소스 문제 다섯 건을 정리한다. 다룬 문제는 다음과 같다. - 워커 강제 종료 - 대용량 엑셀 메모리 - 컨테이너 좀비 프로세스...
진행 기간: 2026.05 ~ 2026.07
기여 전체 개요는 Playground 문서 파싱 파이프라인 — 기여 개요 참고. 본 글은 그중 메모리·프로세스·이미지 크기 안정화만 모은 기록이다.
문서 파싱 서비스를 운영하면서 겪은 리소스 문제 다섯 건을 정리한다. 다룬 문제는 다음과 같다.
계층은 다 다른데 공통점이 하나 있었다. 평소엔 아무 문제 없이 돌아가다가, 특정 조건(대용량 입력, 반복 실행, 오래 켜둔 서버)이 쌓여야만 터진다는 점이다. 그래서 다섯 건 모두 "왜 지금까지 안 보였나"를 같이 적어둔다.
문서 하나를 변환하는 워커 프로세스가 비정상적으로 오래 걸리는 경우가 있었다. 입력 파일이 깨졌거나 OCR 라이브러리가 특정 페이지에서 멈추는 경우다.
기존에는 워커 프로세스 안에서 signal.alarm으로 자기 자신에게 시간 초과를 걸어뒀다.
시간이 지나면 시그널 핸들러가 sys.exit(1)을 불러 스스로 종료하는 방식이다.
문제는 이 방식이 가끔 안 먹었다는 것이다.
signal.alarm이 보낸 SIGALRM은 프로세스의 메인 스레드가 파이썬 바이트코드 실행 루프로 돌아와야 처리된다.
그런데 워커가 docling·OCR 같은 C 확장 라이브러리 안에서 오래 머무는 동안에는 제어권이 파이썬 인터프리터로 돌아오지 않는다.
시그널은 큐에 쌓여 있지만 핸들러가 실행될 기회를 못 잡는다.
그 결과 정말 멈춰야 할 워커가 회수되지 않고 CPU 를 계속 점유하는 상황이 생겼다.
바꾼 방식은 워커 자신이 스스로를 죽이는 대신, 부모 프로세스 안의 별도 감시 스레드가 밖에서 지켜보다 강제로 죽이는 구조다.
SIGKILL은 프로세스가 무엇을 하고 있든 커널이 강제로 회수하는 시그널이라, 워커가 C 확장 안에 갇혀 있어도 상관없이 통한다.
SIGALRM처럼 대상 프로세스의 인터프리터 루프에 의존하지 않는다는 게 핵심 차이다.
감시 스레드가 각 워커의 시작 시각을 딕셔너리에 기록해두고, 주기적으로 순회하며 임계값(기본 20분)을 넘긴 워커를 찾아 죽인다. 여기서 두 가지를 더 손봐야 했다.
unknown) 으로 한 번 더 집계했다.
시간 초과로 죽인 직후에는 그 사실을 잠깐 기억해뒀다가, 뒤따라오는 재집계를 한 번 걸러내는 방식으로 고쳤다.결과로 종료 사유별 지표(시간 초과·원인 불명 등)가 갈라져 나오고, 멈춘 워커가 확실히 회수돼 CPU 과점유를 방어할 수 있게 됐다.
이 감시 스레드는 죽은 워커가 남긴 metrics .db 파일을 치우는 역할도 겸하는데, 그 쪽은 문서 파싱 서비스 관측성 체계 구축 — 초기화 순서 함정과 지표 단일화에서 다룬다.
엑셀 파일을 markdown 으로 바꿀 때 문제가 됐던 건 셀 수가 아주 많은 파일이었다. 워커가 파일을 읽으면서 전체 시트를 메모리에 통째로 올리는 구조라, 셀 수에 비례해서 메모리가 늘어났다. 실제로 1,000만 셀짜리 파일 4개가 거의 동시에 들어왔을 때 컨테이너 메모리 27GiB 제한을 그대로 다 채운 사례가 있었다.
평소엔 이 경로가 문제였던 적이 없다. 보통 들어오는 xlsx 는 시트가 커봐야 몇천 행이라, 통째로 읽어도 메모리가 눈에 띄게 늘지 않았다. 큰 시트가 낀 파일이 몰릴 때만 드러나는 문제였다.
해결 방향은 큰 시트가 있는 파일만 골라서 행 묶음 단위로 읽는 것이다.
read_only=True 모드로 열어 시트 메타데이터에서 행 수를 확인하는데, 이 메타데이터가 비어 있어 행 수를 못 읽는 경우도 있다.
이때는 "작은 시트"로 낙관하지 않고 큰 시트로 간주해 스트리밍으로 보낸다 — 판단이 안 서면 안전한 쪽(메모리를 덜 쓰는 쪽)으로 기운다는 뜻이다.결과로 같은 입력에서 메모리 사용량이 평탄하게 유지됐다(실측 RSS 92MB 수준). 작은 xlsx·pptx·docx 는 전후 출력이 바이트 단위로 동일했고, 스트리밍 경로에 대한 단위 테스트 15건을 새로 추가했다.
doc·ppt 계열 파일을 markdown 으로 바꾸는 경로는 LibreOffice 를 호출한다.
그런데 LibreOffice 가 작업을 끝내고 종료돼도 그 하위 프로세스(soffice.bin)가 완전히 회수되지 않고 좀비 상태로 남는 경우가 있었다.
운영 인스턴스 하나를 기준으로 컨테이너를 띄운 지 약 1주일 만에 좀비가 420개까지 쌓인 걸 실측으로 확인했다.
이 문제가 평소엔 안 보이는 이유는 좀비 프로세스 자체가 CPU 나 메모리를 거의 안 쓰기 때문이다. 다만 PID 는 유한한 자원이라, 좀비가 계속 쌓이면 언젠가 새 프로세스를 만들 PID 자리가 고갈될 위험이 있다.
원인은 컨테이너 안에서 애플리케이션이 PID 1로 뜬다는 점이었다.
리눅스 커널은 좀비가 된 자식 프로세스를 부모가 wait() 계열 호출로 거둬가길 기다리는데, 부모 프로세스가 죽거나 미리 그 자식을 잊어버리면 커널은 그 좀비를 PID 1(그 네임스페이스의 init)에게 재입양시킨다.
그런데 PID 1은 원래 각종 기본 시그널 처리를 하지 않는 특별한 프로세스라, 우리 애플리케이션이 직접 PID 1이 되면 이 재입양된 좀비를 거둬가는 책임까지 떠안았지만 그 책임을 이행하는 코드가 없었다.
해결은 컨테이너 시작 프로세스를 tini(좀비를 회수하는 역할만 하는 아주 작은 init)로 감싸는 것이다.
자세한 배경과 동작 원리는 Docker에서 좀비 프로세스가 쌓이는 이유 — PID 1 문제와 tini에 정리해뒀다.
이 서비스에 적용하면서 신경 쓴 부분은 두 가지다.
ENTRYPOINT를 tini 로 고정해서, 특정 실행 방식에 의존하지 않고 항상 좀비 회수가 보장되게 했다.SIGTERM을 tini 가 애플리케이션에 그대로 전달하도록 설정했다.
tini 를 새로 끼워 넣으면서 기존의 정상 종료 흐름(진행 중인 요청을 마저 처리하고 종료)이 깨지면 안 됐기 때문이다.결과로 좀비 누적으로 인한 PID 고갈 위험이 사라졌다.
운영 중인 self-hosted 러너 서버에서, PR 이 취소되면(새 커밋이 push 되어 이전 실행이 자동 취소되는 경우 등) 특정 단계의 프로세스가 정리되지 않고 계속 살아 있는 걸 발견했다. 취소 신호를 못 받은 프로세스는 다음 작업을 계속 기다리며 재시도를 반복했고, 그중 두 개는 각각 18일·7일 동안 CPU 를 40%씩 물고 있었다.
원인은 셸 파이프라인 구조였다.
명령 | while read ...; do ... done 형태로 짜면, while 루프는 파이프 오른쪽에서 서브셸로 실행된다.
작업이 취소돼 셸에 종료 신호가 전달돼도, 그 신호가 파이프로 연결된 하위 서브셸까지 확실히 전파된다는 보장이 없다.
게다가 루프 안에서 부르는 API 호출 자체가 타임아웃 없이 걸려 있으면, 취소 신호와 무관하게 그 호출이 끝날 때까지 프로세스가 남는다.
1차 대응은 파이프-서브셸 구조를 프로세스 치환(< <(명령))으로 바꾸는 것이었다.
이렇게 하면 while 루프가 서브셸이 아니라 지금 실행 중인 셸 그 자체에서 도니까, 종료 신호가 파이프를 거치지 않고 직접 전달된다.
그런데 이 방식에도 허점이 있었다.
프로세스 치환 안의 명령이 타임아웃으로 잘리면, 뒤의 while 루프는 그게 "지울 게 없어서 빈 목록"인지 "중간에 잘려서 빈 목록"인지 구분할 수 없었다.
최종적으로는 목록 조회를 임시 파일에 먼저 저장하고, 그 조회가 성공했는지 종료 코드로 확인한 뒤에만 삭제 루프를 도는 방식으로 정리했다.
모든 API 호출에는 개별 타임아웃을 걸어 취소 신호를 못 받아도 스스로 끝나게 만들었다.
결과로 방치돼 있던 문제 프로세스 6개를 정리했고, 러너의 CPU 사용률이 20%대에서 0.5%대로 떨어졌다.
운영 이미지의 압축 크기가 9.89GB(디스크에 풀면 약 30GB)까지 불어나 있었다. 원인을 뜯어보니 CUDA 관련 라이브러리가 이미지 안에 중복으로 여러 벌 들어가 있었고, 빌드에만 필요한 도구가 런타임 이미지에까지 그대로 남아 있었다.
CUDA 중복이 생긴 이유는 Python CUDA 버전 생태계에서 다룬 것처럼, 파이썬 라이브러리마다 CUDA 를 가져오는 방식이 다르기 때문이다. torch 는 자체 wheel 안에 CUDA 런타임을 통째로 번들링해서 시스템 CUDA 와 무관하게 동작하는데, 이 wheel 버전을 기본값(PyPI 최신 CUDA 태그)으로 두면 베이스 이미지의 CUDA(11.8) 와 다른 버전을 하나 더 들고 오게 된다. 여기에 시스템 CUDA 를 직접 참조하는 paddle 까지 더해지면, 결과적으로 서로 다른 두세 벌의 CUDA 관련 바이너리가 이미지 안에 겹쳐 쌓인다.
정리한 항목은 세 가지다.
결과로 압축 이미지 크기가 9.89GB 에서 6.82GB 로 31% 줄었고, 이미 구축해둔 회귀 검증 체계로 동작 회귀 0건을 확인했다.
다섯 건을 나란히 놓고 보니 전부 "정상적으로 도는 동안에는 절대 안 보이는" 종류의 문제였다. signal.alarm 은 워커가 안 멈추는 한 문제가 없었고, xlsx 메모리는 큰 시트가 안 몰리는 한 문제가 없었고, 좀비 프로세스는 컨테이너를 오래 안 띄워두면 안 보였고, 러너 프로세스는 취소가 자주 안 일어나면 안 보였고, CUDA 중복은 디스크 용량을 신경 쓰지 않는 한 안 보였다.
공통적으로 실측이 없었으면 이 중 어느 것도 고칠 근거를 못 만들었을 거라는 생각이 든다. "좀비가 쌓이는 것 같다"가 아니라 420개라는 숫자, "메모리를 많이 쓴다"가 아니라 27GiB 제한을 채웠다는 숫자, "러너가 좀 걸린다"가 아니라 CPU 40%를 18일 물고 있었다는 숫자가 있어야 그 방어 코드를 넣을 이유가 생긴다. 반대로 말하면 겉보기에 멀쩡하게 돌아가는 시스템일수록, 어디를 실측해야 다음 사고가 보이는지를 계속 물어야 한다는 뜻이기도 하다. 이런 숫자를 뽑아낼 수 있었던 것도 문서 파싱 서비스 관측성 체계 구축 — 초기화 순서 함정과 지표 단일화에서 먼저 관측 체계를 갖춰둔 덕분이었다.
이 중 메모리 회수 자체(gc.collect·malloc_trim)에 관한 더 자세한 진단 과정은 Python 서버 RSS 가 안 줄어들어 malloc_trim 을 박은 이야기에 따로 정리해뒀다.
그 글이 "회수 안 된 메모리를 어떻게 강제로 되돌리나"를 다룬다면, 이 글은 "애초에 회수해야 할 자원(워커·좀비·프로세스·이미지 용량)이 어디서 새는지"를 다뤘다는 점에서 서로 보완 관계다.