Docker 환경에서 Node.js 프로젝트를 빌드하다가 프로세스가 갑자기 종료된 적이 있었다.

당시에는 Nest 기반 프로젝트를 빌드하는 과정에서 문제가 나타났고, 로그를 따라가다 보면 결국 눈에 들어오는 문구는 메모리와 관련된 것이었다.

(아래와 같은 오류.. 수도 없이 봤을 것이다…)

JavaScript heap out of memory

그리고 프로세스는 정상적으로 끝나지 않았고 Exit Code 134가 남았다.

처음에는 이 상황을 아주 단순하게 받아들였다.

Docker 안에서 실행 중이던 Node.js가 메모리 문제로 죽었으니 컨테이너에 메모리가 부족했던 것이라고 생각하면 되지 않을까 싶었다.

당시 서버에는 다른 컨테이너도 실행되고 있었고, Docker라는 환경 자체가 프로세스의 자원을 제한할 수 있다는 것도 알고 있었기 때문에 더 그렇게 생각했다.

그래서 처음 머릿속에 떠오른 해결 방법도 자연스러웠다.

Docker에 메모리를 더 주거나 서버 메모리를 확보하면 해결되지 않을까?

그런데 로그를 다시 보면서 조금 이상한 점이 생겼다.

에러 메시지가 단순히 운영체제에서 프로세스를 강제로 죽였다는 내용이 아니라 JavaScript heap 자체를 명확하게 이야기하고 있었기 때문이다.

Node.js 공식 문서에도 V8이 heap 한계에 접근하면 garbage collection에 더 많은 시간을 사용하게 되고, 끝내 메모리를 확보하지 못하면 JavaScript heap out of memory 형태의 치명적인 오류로 프로세스가 종료될 수 있는 사례가 나온다. 또한 --max-old-space-size는 V8 old memory 영역의 최대 크기를 조절하는 옵션으로 제공된다.

이 내용을 보고 나니 내가 처음부터 서로 다른 두 종류의 메모리 문제를 하나로 보고 있었던 것은 아닐까라는 생각이 들었다.

---

처음에는 “메모리 부족”이면 전부 같은 문제라고 생각했다

애플리케이션을 운영하면서 메모리가 부족하다는 표현을 자주 사용한다.

그래서 다음과 같은 상황도 모두 비슷하게 느껴진다.

메모리가 부족하다
→ 프로세스가 죽는다

하지만 Node.js를 Docker에서 실행하고 있다면 실제로는 적어도 두 개의 서로 다른 한계를 생각해야 했다.

하나는 Node.js/V8이 JavaScript 객체를 관리하는 heap의 한계이고, 다른 하나는 컨테이너 또는 호스트 운영체제가 사용할 수 있도록 허용한 실제 메모리의 한계다.

둘 다 최종적으로는 “프로세스가 죽었다”라는 결과를 만들 수 있기 때문에 로그를 자세히 보지 않으면 같은 문제처럼 느껴진다.

그런데 원인이 다르면 해결 방법도 달라진다.

Node.js의 JavaScript heap 한계에 도달한 것이라면 V8의 heap 설정이나 애플리케이션의 메모리 사용 패턴을 확인해야 한다.

반대로 컨테이너가 허용된 실제 메모리 한계를 넘어서 운영체제의 OOM 처리 대상이 된 것이라면 Docker의 memory limit과 컨테이너의 실제 사용량을 확인해야 한다.

Docker 공식 문서에서도 컨테이너가 사용 가능한 메모리보다 많이 사용해 OOM 상황이 발생하면 기본적으로 커널이 컨테이너 내부 프로세스를 종료할 수 있다고 설명한다. Docker는 컨테이너에 --memory를 이용한 hard limit도 설정할 수 있다.

이 차이를 알고 나니 “메모리 때문에 죽었다”라는 설명만으로는 원인을 거의 설명하지 못한다는 생각이 들었다.

정말 알아야 하는 것은 누가 어떤 한계를 넘겼다고 판단해서 프로세스를 종료했는가였다.

그리고 Docker 컨테이너 일부가 좀비로 남는 경우도.. 간혹 있었다.

---

내가 본 JavaScript heap out of memory는 무엇을 말하고 있었을까

Node.js는 JavaScript 객체를 저장하고 관리하기 위해 V8 heap을 사용한다.

애플리케이션이 객체를 계속 만들면 heap 사용량이 증가하고, V8은 더 이상 사용하지 않는 객체를 정리하기 위해 garbage collection을 수행한다.

여기까지는 일반적인 동작이다.

문제가 되는 것은 garbage collection을 반복해도 필요한 공간을 확보하지 못하고 heap이 허용된 한계에 가까워질 때다.

Node.js 공식 진단 문서에서도 메모리 부족 상황에서는 memory usage가 증가하다 프로세스가 crash하고, garbage collection 활동이 증가하면서 CPU 사용량과 응답시간에도 영향을 줄 수 있다고 설명한다.

Node 공식 예제를 보면 heap limit에 도달했을 때 다음과 유사한 로그가 나타난다.

FATAL ERROR:
Reached heap limit
Allocation failed
JavaScript heap out of memory

그리고 그 전에 여러 번의 GC 기록이 남을 수도 있다.

이 부분을 보고 나서 내가 당시 봤던 오류를 조금 다르게 생각할 수 있었다.

Docker가 먼저:

너는 컨테이너 메모리를 너무 많이 썼으니 강제로 종료한다.

라고 판단한 상황과,

Node.js/V8이:

JavaScript heap에서 더 이상 필요한 메모리를 확보하지 못한다.

고 판단하면서 자체적으로 치명적인 오류를 발생시키는 상황은 관찰되는 원인이 다를 수 있다.

그래서 JavaScript heap out of memory가 로그에 명확하게 보인다면 적어도 V8 heap 상태를 확인할 이유가 생긴다.

Docker 자체만 바라보고 끝내면 안 되는 이유였다.

---

반대로 Docker OOM Kill이라면 무엇을 봐야 할까

그렇다고 로그에 메모리라는 말이 나왔다는 이유만으로 Docker 쪽을 무시해서도 안 된다.

Node.js heap을 크게 늘려놓았는데 컨테이너 자체의 memory limit보다 더 많은 실제 메모리를 필요로 한다면 결국 다른 한계에 부딪힐 수 있기 때문이다.

Docker에서는 컨테이너의 상태 정보 안에 OOMKilled 여부와 ExitCode가 따로 존재한다. Docker Engine의 공식 Container Inspect 응답에도 State.OOMKilled와 State.ExitCode가 별도의 값으로 정의되어 있다.

그래서 지금 같은 문제가 다시 발생한다면 로그만 보고 추측하기보다 바로 상태를 확인하게 되었다.

예를 들면:

docker inspect \
  --format '{{.State.ExitCode}} {{.State.OOMKilled}}' \
  container_name

여기에서 중요한 것은 Exit Code 하나만 보는 것이 아니다.

Docker가 실제로 이 컨테이너를 OOM Kill로 기록하고 있는지를 같이 보는 것이다.

Docker 공식 문서에서는 상태 코드 137을 SIGKILL(9)로 종료된 컨테이너를 찾을 때 사용할 수 있다고 명시하고 있고, OOM 상황에서는 커널이 컨테이너 프로세스를 종료할 수 있다고 설명한다.

이 내용을 보고 나니 내가 겪었던 Exit 134에 대해서도 “메모리라는 단어가 있었으니 Docker OOM Kill이었다”라고 단정하면 안 된다는 생각이 들었다.

당시 함께 나타난 Node.js의 JavaScript heap out of memory 로그가 오히려 더 중요한 단서였다.

Exit Code는 결과를 좁혀가는 하나의 정보이고, 실제 종료 원인을 판단하려면 애플리케이션 로그와 Docker 상태를 함께 봐야 했다.

---

처음 해결책으로 생각한 것은 --max-old-space-size였다

Node.js heap 문제를 검색하다 보면 상당히 빠르게 만나게 되는 옵션이 있다.

node --max-old-space-size=4096 app.js

Node.js 공식 문서에서 --max-old-space-size는 V8 old memory 영역의 최대 크기를 MiB 단위로 설정한다. heap 사용량이 이 한계에 접근하면 V8은 사용하지 않는 메모리를 확보하기 위해 garbage collection에 더 많은 시간을 사용한다.

그래서 JavaScript heap out of memory를 보면 이 값을 높이는 것이 아주 자연스러운 해결 방법처럼 보인다.

나도 처음에는 그렇게 봤다.

현재 JavaScript heap이 부족하다.

그렇다면 heap을 더 크게 허용하면 된다.

논리 자체는 틀리지 않는다.

실제로 정상적인 작업이 현재 V8 heap 한계보다 많은 메모리를 필요로 하는 경우라면 heap limit을 늘리는 것이 필요한 조치일 수 있다.

그런데 여기서 또 하나의 질문이 생겼다.

왜 이 빌드가 그렇게 많은 JavaScript heap을 필요로 하고 있는가?

이 질문 없이 숫자만 늘리면 PostgreSQL에서 max_connections를 계속 올리던 문제와 비슷해질 수 있다는 생각이 들었다.

1GB가 부족하면 2GB.

2GB가 부족하면 4GB.

4GB가 부족하면 8GB.

이런 식으로 계속 늘렸는데 실제 원인이 메모리 누수나 비정상적으로 큰 빌드 작업에 있다면 한계선을 뒤로 미루는 것에 불과할 수 있다.

그래서 --max-old-space-size를 사용하더라도 이 값이 해결인지, 단순한 증상 완화인지 구분할 필요가 있었다.

---

특히 “서버 RAM이 32GB니까 Node에 16GB 줘도 되겠지”라고 생각하면 부족했다

처음에는 물리적인 서버 메모리만 보면 여유가 충분해 보일 수 있다.

예를 들어 서버에 RAM이 많이 남아 있다면 Node.js heap limit 역시 크게 줘도 괜찮을 것 같다.

그런데 Docker 안에서 실행한다면 다시 한 단계가 추가된다.

물리 서버 RAM
      ↓
Docker가 컨테이너에 허용한 메모리
      ↓
Node.js 프로세스 전체 메모리
      ↓
그 안의 V8 JavaScript Heap

이 숫자들은 전부 같은 것이 아니다.

Node.js의 --max-old-space-size는 Node 프로세스 전체 메모리 상한을 설정하는 옵션이 아니라 V8 old space의 최대 크기를 조정하는 것이다. Node.js 공식 문서도 이 옵션을 V8 old memory section의 최대 크기로 정의한다.

Node 프로세스에는 heap 이외에도 다른 메모리가 필요할 수 있다.

여기에 컨테이너 자체에는 Node 프로세스 외의 자원도 존재할 수 있다.

그런데 container memory limit을 4GB로 설정해 놓고 Node의 old-space 한계 역시 거의 4GB 가까이 사용하도록 만든다면 다른 메모리가 사용할 여유를 생각하지 못한 설정이 될 수 있다.

Node.js 문서에서도 2GiB 메모리 환경을 예로 들면서 old-space를 1536MiB 정도로 설정해 다른 용도를 위한 메모리를 남기는 예를 제시한다.

이 예시를 보고 나니 숫자를 정할 때 “얼마까지 줄 수 있는가”보다 “다른 메모리가 사용할 공간을 얼마나 남겨야 하는가”도 같이 생각해야 한다는 점이 더 명확해졌다.

---

빌드 중에만 죽는다면 또 다르게 봐야 했다

내가 겪었던 문제에서 특히 신경 쓰였던 부분은 애플리케이션을 단순 실행할 때와 빌드할 때 메모리 사용 패턴이 다를 수 있다는 점이었다.

Nest나 Node 기반 프로젝트를 빌드하면 TypeScript 변환, 모듈 분석, 번들링이나 기타 빌드 과정이 한꺼번에 진행될 수 있다.

평소 API 서버는 잘 실행되고 있는데:

npm run build

또는 Nest 빌드 과정에서만 JavaScript heap out of memory가 나타난다면,

애플리케이션 운영 자체가 메모리를 계속 누수하고 있다.

라는 결론과는 구분해서 생각해야 한다.

문제가 발생하는 시점이 단서가 될 수 있기 때문이다.

항상 일정 시간 운영한 뒤 죽는다면 장기적으로 메모리 사용량이 증가하는 문제를 의심해볼 수 있다.

반대로 특정 빌드 명령을 실행하는 순간에만 메모리가 급격히 증가한다면 빌드 작업이 순간적으로 필요로 하는 heap 크기나 빌드 구조를 먼저 확인할 수 있다.

Node.js 공식 메모리 진단 문서에서도 메모리 문제를 분석할 때 heap profiler, heap snapshot, GC trace 등을 이용해 객체의 크기와 allocation pattern을 확인하는 방법을 안내하고 있다.

이걸 보고 나서 “메모리 부족”이라는 한 문장보다 언제부터, 어떤 작업을 할 때, 어떤 형태로 증가했는가가 더 중요한 정보라고 생각하게 됐다.

---

그래서 지금이라면 먼저 메모리가 증가하는 모습을 보려고 할 것 같다

오류가 이미 발생한 뒤의 로그만 가지고 보면 그 순간의 결과만 알 수 있다.

나는 지금 다시 같은 문제를 만난다면 프로세스가 죽기 전에 메모리가 어떻게 변하는지부터 보고 싶다.

Docker에서는 docker stats를 이용해 실행 중인 컨테이너의 CPU와 memory usage, memory limit 등의 runtime metrics를 볼 수 있다.

예를 들어:

docker stats

를 켜놓고 빌드를 실행한다.

그리고 생각한다.

빌드를 시작하기 전에는 어느 정도였는가.

빌드가 시작되면 서서히 증가하는가.

특정 시점에 급격하게 증가하는가.

컨테이너 한계에 거의 도달하는가.

아니면 Docker가 허용한 메모리에는 여유가 있는데 Node.js가 먼저 heap out of memory로 종료되는가.

두 번째 상황이라면 상당히 중요한 단서가 된다.

Docker Memory Limit
4GB

실제 컨테이너 사용량
2GB 부근

그런데

Node.js
JavaScript heap out of memory

와 같은 패턴이 실제로 관찰된다면 컨테이너 전체 memory limit이 첫 번째 의심 대상이 아닐 수 있다.

반대로:

Docker Memory Limit
2GB

Memory Usage
2GB에 매우 근접

그 직후 종료

되고 OOMKilled도 true로 기록된다면 Docker/커널 쪽 메모리 한계를 먼저 볼 근거가 강해진다.

위 숫자는 설명을 위한 예시지만, 이런 방식으로 실제 측정값을 남겨야 두 상황을 구분할 수 있다는 점이 중요하다.

---

--max-old-space-size를 올린 뒤 잘 됐다고 해서 원인이 완전히 해결됐다고 보기도 어려웠다

가령 old-space 값을 높였더니 빌드가 성공했다고 생각해보자.

그러면 다음과 같이 결론을 내리기 쉽다.

원인: Node heap이 작았음
해결: max-old-space-size 증가
끝

하지만 나는 지금이라면 한 번 더 질문할 것 같다.

왜 기존 heap으로는 빌드가 불가능했을까?

프로젝트 규모가 실제로 커져서 정상적인 빌드에 더 많은 메모리가 필요한 것이라면 큰 문제가 아닐 수 있다.

그렇지만 이전에는 같은 설정으로 빌드됐는데 어느 시점부터 갑자기 실패하기 시작했다면 그 사이 무엇이 변했는지를 확인할 이유가 생긴다.

Dependency가 크게 늘었는지.

빌드 대상에 불필요한 파일이 들어갔는지.

코드 생성이나 변환 작업이 늘어났는지.

특정 버전 변경 이후 메모리 사용 패턴이 달라졌는지.

CI나 Docker 빌드 환경의 memory limit이 달라졌는지.

이런 질문이 필요하다.

--max-old-space-size로 성공했다는 것은 더 많은 heap을 주면 현재 작업을 끝낼 수 있다는 사실은 보여준다.

하지만 메모리를 많이 사용하게 된 이유까지 설명해주는 것은 아니다.

이 차이를 구분하지 않으면 몇 달 뒤 프로젝트가 더 커졌을 때 같은 문제를 다시 만날 수 있다.

---

메모리 누수와 단순히 큰 작업도 구분해야 했다

heap out of memory라는 말을 들으면 메모리 누수가 바로 떠오를 수 있다.

하지만 heap이 부족했다고 해서 항상 leak이라고 말할 수는 없다.

예를 들어 한 번의 작업에서 실제로 3GB의 객체가 동시에 필요하고 heap 한계가 2GB라면 메모리가 정상적으로 해제되고 있어도 해당 작업은 끝낼 수 없다.

반대로 처리한 작업이 끝났는데도 사용했던 객체가 계속 참조되어 garbage collection 대상이 되지 않고 시간이 갈수록 heap이 증가한다면 leak을 의심할 수 있다.

두 상황 모두 마지막에는:

JavaScript heap out of memory

로 끝날 수 있다.

그래서 Node.js 공식 메모리 진단 문서에서도 단순히 heap 크기를 조절하는 방법뿐 아니라 heap snapshot, profiler, GC trace 등을 이용해 어떤 객체가 공간을 차지하고 있고 무엇이 garbage collection을 막는지 분석하도록 안내한다.

이 차이가 중요한 이유는 해결 방법이 완전히 다르기 때문이다.

정상적인 대형 빌드라면 더 큰 heap을 제공하는 것이 합리적일 수 있다.

메모리 누수라면 heap을 늘리는 것은 프로세스가 죽는 시간을 늦출 뿐이다.

---

그렇다고 운영 서버에서 무턱대고 Heap Snapshot을 찍는 것도 조심해야 했다

메모리 문제가 있으니 Heap Snapshot을 찍으면 되지 않을까 생각할 수 있다.

하지만 이 작업 자체도 메모리를 사용한다.

Node.js 공식 문서는 heap snapshot을 생성할 때 main thread의 다른 작업이 멈출 수 있고, snapshot 생성 과정에서 현재 heap 크기의 약 두 배 수준 메모리가 필요할 수 있어 애플리케이션이 crash할 위험도 있다고 경고한다.

이 내용을 보면 운영 서버에서 메모리가 거의 바닥난 순간에:

지금 바로 heap snapshot부터 찍어보자.

라고 하는 것도 위험할 수 있다는 것을 알 수 있다.

이미 메모리 여유가 거의 없는 상태라면 진단 작업이 마지막 남은 메모리를 사용하는 상황도 생각해야 한다.

그래서 실제 운영 환경에서는 재현 가능한 테스트 환경을 만들거나, 장애 영향이 없는 인스턴스에서 진단하는 방법까지 같이 고려해야 한다.

이런 부분은 단순히 heapdump 사용법만 알고 있을 때는 잘 보이지 않았다.

---

내가 지금 다시 이 오류를 만나면 보는 순서가 완전히 달라질 것 같다

예전에는 로그에서 heap out of memory를 보고 바로 메모리를 늘리는 방향으로 생각했다.

지금은 먼저 로그 자체를 자세히 볼 것 같다.

Node.js가 JavaScript heap out of memory를 출력했는지 확인한다.

그다음 Docker 상태를 본다.

docker inspect \
  --format '{{.State.ExitCode}} {{.State.OOMKilled}}' \
  container_name

그리고 실행 중 재현이 가능하다면:

docker stats

로 컨테이너의 실제 메모리 증가를 본다.

Node.js heap limit도 별도로 확인할 수 있다. Node.js 공식 메모리 문서는 v8.getHeapStatistics()의 heap_size_limit을 이용해 현재 heap limit을 확인하는 방법을 제공한다.

예를 들면:

const v8 = require('node:v8');

const { heap_size_limit } = v8.getHeapStatistics();

console.log(
  heap_size_limit / 1024 / 1024,
  'MB'
);

이렇게 보면 최소한 세 개의 숫자를 서로 비교할 수 있다.

Node.js V8 Heap Limit

Docker Memory Limit

실제 Container Memory Usage

예전에는 이 셋을 거의 같은 “메모리 크기”로 생각했다.

지금은 각각 다른 계층의 한계라고 본다.

---

이 세 숫자를 같이 보면 해결 방향도 달라진다

예를 들어 실제 측정 결과가 다음과 같다고 생각해보자.

Node.js heap limit 근처까지 계속 올라가는데 Docker 컨테이너의 memory limit에는 충분한 여유가 있다.

그리고 로그에는 명확하게 JavaScript heap out of memory가 있다.

그렇다면 V8 heap 설정과 Node 애플리케이션의 heap 사용을 먼저 볼 근거가 생긴다.

반대로 Node heap limit보다 앞서 컨테이너가 Docker memory limit에 도달하고 OOMKilled=true로 종료된다면 컨테이너 자원 제한을 먼저 확인해야 한다.

그리고 heap과 Docker limit 모두 여유가 있는데 프로세스가 계속 비정상 종료된다면 메모리 문제라고 고집하지 말고 다른 원인으로 범위를 넓혀야 한다.

이것이 내가 Exit Code 하나에 너무 큰 의미를 부여하지 않게 된 이유다.

Exit Code는 조사 시작점이지 항상 원인 자체는 아니었다.

---

특히 Docker에서는 빌드 단계와 실행 단계를 구분해서 보고 싶다

Node 프로젝트를 Docker로 배포하면 빌드와 런타임을 같은 컨테이너 과정에서 처리할 수도 있고 multi-stage build처럼 분리할 수도 있다.

내가 다시 구조를 만든다면 빌드 중에만 큰 메모리가 필요한지, 실제 서비스 실행 중에도 계속 큰 메모리가 필요한지를 구분하고 싶다.

예를 들어 빌드 시점에만 메모리 요구량이 크다면:

Build Stage
→ 큰 메모리 필요

Runtime Stage
→ 상대적으로 작은 메모리

일 수 있다.

이 상황에서 런타임 컨테이너의 Node heap까지 무조건 크게 설정할 이유는 없을 수 있다.

반대로 서비스가 실행된 뒤 요청을 받을수록 메모리가 계속 증가한다면 빌드 문제가 아니라 런타임 메모리 사용 패턴을 분석해야 한다.

같은 heap out of memory라도 언제 발생했는지에 따라 조사할 코드와 설정이 달라진다.

이 부분을 기록해두는 것이 중요하다고 느꼈다.

---

당시에는 해결하는 것이 우선이었지만 지금이라면 실패 당시의 수치를 남길 것 같다

이런 문제를 실제로 만나면 블로그 글을 쓰기 위해 차분하게 데이터를 모으고 있을 여유가 없는 경우가 많다.

나 역시 당시에는 우선 빌드가 정상적으로 되도록 만드는 것이 중요했다.

그래서 지금 이 글에서:

당시 컨테이너 메모리가 정확히 몇 GB였고 Node heap이 정확히 몇 MB에서 실패했다.

같은 값을 만들어 적고 싶지는 않다.

그 숫자를 별도로 기록해두지 않았다면 모른다고 하는 것이 맞다.

다만 그 경험 때문에 다음에 같은 문제가 생기면 반드시 기록하고 싶은 항목은 분명해졌다.

Node 버전.

빌드 명령.

Docker memory limit.

오류 직전 container memory usage.

Node heap limit.

docker inspect의 ExitCode와 OOMKilled.

JavaScript heap out of memory 로그 직전 GC 내용.

--max-old-space-size 변경 전후 결과.

이 값들이 있다면 다음에는 단순히:

메모리를 올리니까 해결됐다.

가 아니라,

어느 한계에 먼저 도달했고, 어떤 설정을 바꾸자 그 한계가 어떻게 변했는지

를 설명할 수 있다.

나는 지금은 이 차이가 훨씬 중요하다고 생각한다.

---

결국 내가 잘못 묻고 있었던 질문은 “메모리를 얼마나 더 줘야 하지?”였다

처음 오류를 만났을 때 내가 가장 궁금했던 것은 이것이었다.

몇 GB를 더 주면 빌드가 될까?

지금은 이 질문부터 시작하지 않을 것 같다.

먼저 이렇게 묻는다.

지금 부족하다고 말하는 메모리는 정확히 어느 메모리인가?

V8의 JavaScript heap인가.

Docker가 컨테이너에 허용한 memory limit인가.

호스트 전체의 실제 RAM인가.

또는 메모리가 아니라 다른 이유로 프로세스가 비정상 종료된 것인가.

이 구분을 먼저 해야 해결 방법도 결정할 수 있다.

V8 heap 문제라면 --max-old-space-size를 검토하면서 왜 heap 사용량이 그렇게 큰지 본다.

Docker OOM Kill이라면 container memory limit과 실제 사용량을 확인한다.

장기적으로 memory usage가 계속 증가한다면 heap profiling이나 snapshot을 통해 무엇이 남아 있는지 분석한다.

빌드 시점에만 발생한다면 빌드 과정과 런타임을 분리해서 본다.

결국 모두 “메모리 문제”이지만 같은 문제는 아니다.

---

마무리

Docker에서 Node.js 프로세스가 갑자기 종료되고 로그에 메모리 관련 오류가 나타나면 처음에는 모든 원인이 한곳에 있는 것처럼 느껴진다.

나도 Exit Code 134와 JavaScript heap out of memory를 보면서 가장 먼저 Docker에 메모리를 더 주는 방향을 생각했다.

하지만 다시 구조를 살펴보면서 Node.js의 V8 heap과 Docker의 container memory limit은 서로 다른 계층이라는 것을 구분해서 보기 시작했다.

Node.js는 V8 old-space의 최대 크기를 --max-old-space-size로 조절할 수 있고, heap limit에 접근하면 GC 활동이 증가하며 결국 메모리를 확보하지 못하면 JavaScript heap out of memory로 종료될 수 있다.

Docker에서는 별도로 컨테이너의 memory limit을 설정할 수 있고, OOM 상황에서 커널이 프로세스를 종료할 수 있으며, Container Inspect 상태에는 OOMKilled와 ExitCode가 별도로 기록된다.

이 둘을 구분하고 나니 Exit Code를 보는 방식도 달라졌다.

예전에는:

Exit Code
+
메모리 오류

→ Docker 메모리 부족

처럼 바로 연결하려고 했다.

지금은:

애플리케이션 로그 확인

↓

Node/V8 Heap 오류인가?

↓

Docker OOMKilled인가?

↓

실제 Container Memory는 어디까지 올라갔는가?

↓

Node Heap Limit은 얼마인가?

↓

문제가 Build에서만 발생하는가,
Runtime에서도 발생하는가?

순서로 생각한다.

그리고 이 과정을 거친 뒤에야 메모리를 늘리는 것이 정말 해결책인지 판단한다.

결국 이 문제를 겪으면서 가장 크게 바뀐 생각은 메모리가 부족하다는 메시지를 해결책으로 연결하기 전에, 누가 어떤 메모리의 한계를 이야기하고 있는지부터 확인해야 한다는 것이었다.

그 한계를 구분할 수 있어야 --max-old-space-size를 올릴지, Docker memory limit을 수정할지, 애플리케이션의 메모리 사용 자체를 분석할지 결정할 수 있다.

단순히 숫자를 크게 만드는 것보다 먼저 해야 할 일은 프로세스가 어디에서 한계에 부딪혔는지를 설명할 수 있는 상태를 만드는 것이었다.

FastAPI 서비스를 운영하면서 PostgreSQL의 too many clients already 오류를 처음 봤을 때는 해결 방향이 꽤 명확해 보였다.

오류 메시지를 그대로 읽으면 PostgreSQL이 받아들일 수 있는 Connection 수를 모두 사용했다는 뜻으로 이해할 수 있었고, 그렇다면 허용 가능한 Connection 수를 늘리면 되는 것처럼 보였다.

당시에는 PostgreSQL의 max_connections를 상당히 크게 잡는 방법을 찾아보면서 3,000 정도까지 올리는 방안도 생각해봤다.

서버 메모리가 충분하고 PostgreSQL에서 연결을 더 많이 허용하면 적어도 too many clients already 때문에 새로운 요청이 실패하는 문제는 사라지지 않을까 하는 생각이었다.

처음에는 꽤 합리적인 해결 방법처럼 느껴졌다.

그런데 값을 실제로 크게 올리는 쪽으로 생각하다 보니 오히려 한 가지 질문이 생겼다.

지금 PostgreSQL이 연결을 적게 허용하고 있는 것이 정말 문제라면, 내 애플리케이션은 왜 그렇게 많은 Connection을 필요로 하고 있는 걸까?

이 질문에 답하지 못하고 있었다.

그때 FastAPI에서는 이미 asyncpg Connection Pool을 사용하고 있었고, 내가 사용하던 설정은 대략 다음과 같은 형태였다.

pool = await asyncpg.create_pool(
    dsn=DATABASE_URL,
    min_size=1,
    max_size=50
)

애플리케이션이 Connection을 무제한으로 생성하지 않도록 최대 크기까지 정해놓은 상태였다.

그렇다면 단순히 PostgreSQL의 상한만 올리기 전에 내가 생각하고 있는 Connection 구조와 실제 PostgreSQL 상태가 같은지부터 확인하는 것이 순서가 아닐까라는 생각이 들었다.

이 지점부터 max_connections를 바라보는 방식이 조금 달라졌다.

---

처음에는 “최대 몇 개까지 받을 수 있느냐”만 보고 있었다

PostgreSQL의 현재 설정값은 간단하게 확인할 수 있다.

SHOW max_connections;

PostgreSQL 공식 문서에서 max_connections는 서버가 동시에 허용할 수 있는 최대 Connection 수를 결정하는 설정이다. 그런데 문서를 조금 더 읽어보면 PostgreSQL은 이 값을 기준으로 일부 자원의 크기를 결정하고, 값을 높이면 shared memory를 포함한 관련 자원 할당도 증가할 수 있다고 설명하고 있다.

처음에는 앞부분만 보고 있었다.

Connection이 부족하다
→ max_connections가 작다
→ 값을 높인다

그런데 뒤의 이야기를 같이 생각하면 조금 달라진다.

max_connections는 단순히 출입문 앞에 붙어 있는 숫자표가 아니다.

값을 크게 만든다는 것은 PostgreSQL이 더 많은 동시 Connection을 받아들일 수 있는 구조로 운영하겠다는 결정에 가깝다.

그렇다면 100이 부족해서 300으로 늘리고, 300이 부족하면 1,000으로 늘리고, 또 부족하면 3,000으로 늘리는 방식이 정말 올바른 해결인지 먼저 확인해야 했다.

왜냐하면 애플리케이션 구조에서 Connection이 비정상적으로 계속 증가하고 있다면 상한을 올리는 것은 그 증가를 멈추는 것이 아니라 문제가 다시 나타나는 지점을 뒤로 옮기는 것일 수도 있기 때문이다.

예를 들어 물이 계속 새고 있는데 양동이 크기만 계속 키우는 것과 비슷하다.

양동이가 커졌기 때문에 넘치는 시점은 늦어진다.

하지만 물이 새는 원인은 그대로다.

나는 max_connections를 크게 올리는 문제도 이런 상황일 수 있다고 생각하기 시작했다.

---

그래서 총 Connection 수를 먼저 보기 시작했다

그다음 생각은 자연스럽게 이어졌다.

PostgreSQL이 최대 몇 개를 허용하는지는 알았다.

그렇다면 지금 실제로 몇 개가 연결되어 있는지를 봐야 했다.

PostgreSQL에서는 pg_stat_activity를 통해 서버 프로세스별 현재 활동을 확인할 수 있다. 현재 공식 문서에서도 이 View는 서버 프로세스마다 한 행을 제공하고 현재 상태와 Query 등의 정보를 보여준다고 설명한다.

가장 단순하게는 현재 Connection 수부터 확인할 수 있다.

SELECT COUNT(*)
FROM pg_stat_activity;

그런데 여기서 숫자 하나만 확인하고 끝내면 다시 처음과 비슷한 문제가 생긴다.

예를 들어 결과가 90이라고 하자.

max_connections가 100이라면:

거의 다 썼네. 역시 100이 부족했구나.

라고 생각하기 쉽다.

하지만 90개의 Connection이 왜 존재하고 있는지는 아직 모른다.

90개가 모두 실제 사용자 요청을 처리하고 있을 수도 있다.

Connection Pool이 다음 요청을 위해 유지하고 있는 연결이 많이 포함되어 있을 수도 있다.

오랫동안 끝나지 않는 Query 때문에 Connection이 반환되지 않고 있을 수도 있고, Transaction이 정상적으로 종료되지 않은 상태가 있을 수도 있다.

다른 애플리케이션이 같은 PostgreSQL에 연결하고 있을 수도 있다.

즉 COUNT(*) = 90은 현상을 보여주기는 하지만 원인을 설명하지는 못한다.

이 부분 때문에 다음에는 Connection의 상태를 같이 보게 됐다.

---

active와 idle을 보고 나서야 숫자의 의미가 조금 달라졌다

다음처럼 상태별로 나누면 현재 Connection이 어떤 상태인지 조금 더 구체적으로 볼 수 있다.

SELECT
    state,
    COUNT(*)
FROM pg_stat_activity
GROUP BY state;

pg_stat_activity의 state에는 active, idle, idle in transaction 등 현재 backend의 상태가 표시된다. PostgreSQL 공식 문서에서도 active는 Query를 실행하고 있는 상태, idle은 새로운 client command를 기다리는 상태, idle in transaction은 Transaction 안에 있지만 현재 Query를 실행하지 않는 상태로 구분한다.

처음 이 값을 보면 idle이 많다는 사실 자체가 문제처럼 보일 수 있다.

사용하지 않는 Connection이 왜 이렇게 많이 남아 있느냐는 생각이 들기 때문이다.

하지만 내가 asyncpg Connection Pool을 사용하고 있다는 사실을 다시 떠올리면 그렇게 단순하게 볼 수 없었다.

Connection Pool은 사용이 끝난 Connection을 매번 PostgreSQL에서 완전히 끊어버리는 대신 다음 요청에서 재사용할 수 있도록 유지한다.

따라서 Pool 안에서 당장 사용하지 않는 Connection이 idle로 존재하는 것은 자연스러운 상황일 수도 있다.

여기에서 질문을 다시 바꿔야 했다.

idle Connection이 있는가?

가 아니라,

현재 보이는 idle Connection의 개수가 내가 설정한 Pool 구조로 설명 가능한가?

가 더 중요한 질문이었다.

예를 들어 Pool이 하나이고 최대값이 50이라고 생각했는데 동일한 애플리케이션에서 만들어진 것으로 보이는 Connection이 그보다 훨씬 많다면 그때부터 이야기가 달라진다.

Pool 자체가 여러 번 만들어지고 있는지, FastAPI worker마다 별도의 Pool이 생성되는지, 동일한 컨테이너가 여러 개 실행 중인지 확인할 이유가 생긴다.

이렇게 보니 pg_stat_activity의 숫자는 단순히 많고 적음을 판단하기 위한 값이 아니라 내가 알고 있는 애플리케이션 구조가 실제 DB에서도 그렇게 보이는지를 검증하는 자료가 됐다.

---

idle in transaction은 같은 idle이라고 보기 어려웠다

상태를 보다 보면 idle in transaction이라는 값도 만날 수 있다.

처음에는 이름에 idle이 들어 있으니 일반적인 idle Connection과 비슷하게 생각하기 쉽다.

하지만 의미를 보면 다르다.

Transaction이 시작된 상태인데 현재 Query는 실행하지 않고 client의 다음 명령을 기다리고 있다는 의미다. PostgreSQL 문서에서도 idle in transaction을 Transaction 안에 있으면서 현재 Query를 실행하지 않는 상태로 구분한다.

왜 이 차이가 중요할까 생각해봤다.

일반적인 idle Connection은 Connection Pool에서 다음 사용을 기다리고 있을 수 있다.

반면 Transaction이 열린 채로 오래 남아 있다면 단순히 Connection 하나를 유지하고 있다는 것에서 끝나지 않을 수 있다.

Transaction이 언제 시작됐고 얼마나 오래 유지되고 있는지를 확인할 필요가 생긴다.

그래서 상태만 보는 것보다 조금 더 정보를 붙여서 확인하는 편이 의미가 있었다.

SELECT
    pid,
    usename,
    application_name,
    client_addr,
    state,
    backend_start,
    xact_start,
    query_start,
    state_change,
    query
FROM pg_stat_activity
ORDER BY backend_start;

이 쿼리를 보면 질문이 더 구체적으로 바뀐다.

이 Connection은 언제 만들어졌는가.

Transaction은 언제 시작됐는가.

마지막 Query는 언제 시작됐는가.

어떤 애플리케이션에서 연결했는가.

어느 client 주소에서 들어왔는가.

현재 어떤 Query와 연결되어 있는가.

단순히 90개 연결되어 있다에서 끝났을 때보다 조사할 수 있는 방향이 훨씬 많아진다.

---

그러고 나니 “연결이 많다”와 “연결 누수다”도 구분해야 했다

Connection 숫자가 계속 많아 보이면 곧바로 누수를 의심하기 쉽다.

나도 처음에는 연결 수가 예상보다 많으면:

Connection이 반환되지 않고 있는 것 아닐까?

라는 생각부터 했다.

충분히 확인할 가치가 있는 가설이다.

하지만 그것 역시 바로 결론을 내릴 수 있는 문제는 아니었다.

Connection Pool을 사용하면 일정한 수의 Connection을 의도적으로 유지할 수 있다.

FastAPI worker가 여러 개라면 프로세스마다 별도의 Pool이 만들어질 수 있다.

같은 PostgreSQL을 여러 서비스가 사용한다면 다른 서비스 Connection도 pg_stat_activity에 같이 보인다.

따라서 단순히:

Connection 수가 많음
=
Connection leak

라고 연결할 수 없다.

누수라고 판단하려면 적어도 내가 예상하는 정상적인 Connection 수와 실제 Connection 수 사이에 설명할 수 없는 차이가 있는지를 봐야 했다.

이 지점에서 이전 글에서 생각했던 Pool의 크기 문제와 다시 연결됐다.

코드에는:

max_size=50

이라고 적혀 있어도 프로세스가 여러 개라면 PostgreSQL 서버 전체에서 보게 되는 Connection 수는 50보다 클 수 있다.

결국 PostgreSQL 문제라고 생각했던 것이 실제로는 배포 구조까지 포함해서 봐야 하는 문제가 된다.

---

여기서 application_name 같은 값도 왜 필요한지 이해하게 됐다

정상적으로 동작할 때는 DB Connection이 어느 프로그램에서 왔는지를 자세히 구분할 필요가 없어 보인다.

연결만 잘 되고 Query만 정상적으로 실행되면 충분하기 때문이다.

그런데 여러 서비스가 같은 PostgreSQL을 사용하기 시작하면 상황이 달라진다.

예를 들어 검색 API와 추천 API, 관리용 프로그램, 배치 프로그램이 모두 같은 DB를 이용한다고 생각해보자.

Connection이 많아졌을 때:

누가 많이 사용하고 있는가?

를 알아야 한다.

그런데 모든 Connection이 비슷하게 보이면 조사하기가 어렵다.

pg_stat_activity에는 application_name, usename, client_addr 같은 정보가 있기 때문에 서비스별 Connection을 구분할 수 있도록 애플리케이션을 구성해두면 장애 상황에서 도움이 된다. 해당 컬럼들은 현재 pg_stat_activity 공식 정의에도 포함되어 있다.

평소에는 이런 메타데이터가 기능 구현과 직접 관계없는 정보처럼 보였다.

하지만 문제가 생긴 뒤에는 오히려 이런 값이 원인을 좁히는 데 중요하다는 것을 알게 됐다.

운영 로그와 모니터링 정보는 문제가 없을 때보다 문제가 생겼을 때 가치가 드러나는 경우가 많았다.

---

그런데 Connection 상태만 보고 끝내도 부족했다

여기까지 확인하면 PostgreSQL Connection 문제를 꽤 많이 이해한 것처럼 느껴진다.

하지만 한 가지가 다시 걸렸다.

예를 들어 Pool에 Connection이 50개 있고 대부분 active라고 하자.

그렇다면 Connection이 부족한 것이고 max_connections를 늘려야 할까?

꼭 그렇지는 않다.

왜 50개의 Connection이 모두 오랫동안 active인지 봐야 하기 때문이다.

Query 하나가 매우 빠르게 끝난다면 Connection은 곧 Pool로 돌아간다.

반대로 Query가 오래 걸리면 Connection 하나가 오랫동안 점유된다.

이 상황에서 요청이 계속 들어오면 Pool은 자연스럽게 가득 찰 수 있다.

즉 겉으로 보이는 현상은:

Connection 부족

이지만 실제 시작점은:

느린 Query

일 수도 있다.

이 사실을 이해하고 나니 max_connections를 높이는 것보다 SQL 실행시간을 줄이는 것이 더 직접적인 해결인 상황도 있을 수 있다는 생각이 들었다.

Connection을 두 배로 늘리는 것은 느린 Query를 두 배 더 많이 동시에 실행하게 만드는 결과로 이어질 수도 있기 때문이다.

---

그래서 Query 실행 통계까지 연결해서 봐야 했다

현재 실행 중인 Query는 pg_stat_activity로 확인할 수 있다.

하지만 어떤 SQL이 반복적으로 많이 실행되고 있고 평균적으로 얼마나 오래 걸리는지를 보려면 더 장기적인 통계도 필요하다.

PostgreSQL에서는 pg_stat_statements 모듈을 이용해 서버에서 실행되는 SQL의 planning 및 execution 통계를 추적할 수 있다. 공식 문서에서도 이 모듈을 서버에서 실행한 SQL 문의 계획 및 실행 통계를 추적하는 기능으로 설명하고 있다.

이 부분에서 Connection 문제와 Query 성능 문제가 연결된다.

처음에는 둘을 별개의 문제처럼 봤다.

Connection 문제
→ Pool / max_connections

Query 문제
→ SQL 튜닝

그런데 실제로는 느린 Query가 Connection을 오래 점유하고, 그 때문에 Pool 대기가 생기고, 결국 새로운 Connection을 더 만들려고 하면서 PostgreSQL 전체 Connection 수까지 증가하는 흐름도 생각할 수 있다.

느린 Query
    ↓
Connection 오래 점유
    ↓
Pool 사용량 증가
    ↓
새 요청이 Connection 대기
    ↓
Pool이 추가 Connection 사용
    ↓
전체 DB Connection 증가

그렇다면 마지막에 나타난 too many clients already만 보고 문제의 시작점을 판단하면 잘못된 곳을 수정할 수도 있다.

이런 이유로 이제는 DB 장애 메시지를 볼 때 가장 마지막에 터진 오류가 항상 최초 원인이라고 생각하지 않게 됐다.

---

한때 3,000까지 생각했던 숫자를 다시 보게 된 이유도 여기에 있다

max_connections=3000이라는 숫자를 처음 생각했을 때는 단순했다.

연결 상한이 매우 크면 Connection 부족 때문에 장애가 발생할 가능성도 작아질 것이라고 생각했다.

그런데 지금처럼 전체 흐름을 다시 보면 질문이 달라진다.

정말 3,000개의 Connection이 필요한 서비스인가.

동시에 3,000개의 Connection이 필요할 정도의 요청이 들어오는가.

그 Connection들이 실제로 동시에 Query를 실행한다면 현재 PostgreSQL 서버가 그 부하를 어떻게 처리할 것인가.

아니면 대부분의 Connection은 실제 작업 없이 유지되고 있는가.

왜 Application Pool에서 그렇게 많은 Connection을 허용해야 하는가.

이 질문에 답하지 않고 3,000이라는 숫자만 설정하는 것은 너무 큰 결정을 근거 없이 하는 셈이라는 생각이 들었다.

PostgreSQL 공식 문서 역시 max_connections를 높이면 이 값에 직접 비례해 일부 서버 자원 할당이 늘어날 수 있다고 밝히고 있다.

그래서 지금 다시 같은 문제를 만난다면 3,000이면 충분할까?부터 묻지 않을 것 같다.

오히려:

현재 서비스가 정상적으로 동작할 때 필요한 Connection은 몇 개인가?

부터 묻고 싶다.

이 값이 있어야 현재 Connection 수가 정상적인 성장인지 비정상적인 증가인지 판단할 기준도 생긴다.

---

지금이라면 장애가 발생하기 전 평상시 값을 먼저 기록할 것 같다

이 문제를 지나고 나서 한 가지 아쉬운 점도 있었다.

장애가 발생했을 때의 상태만 보면 그 숫자가 평소보다 얼마나 이상한 것인지 판단하기 어렵다는 것이다.

예를 들어 장애 순간 Connection이 80개라고 하자.

평소에도 70~80개를 사용하는 서비스라면 80이라는 숫자가 특별하지 않을 수 있다.

반대로 평소 5개를 사용하던 서비스가 갑자기 80개가 됐다면 매우 중요한 변화다.

결국 장애 분석에는 정상 상태의 기준값이 필요하다.

그래서 지금 다시 운영한다면 일정 간격으로 다음 정도는 기록해두고 싶다.

현재 총 Connection 수.

상태별 Connection 수.

서비스별 Connection 수.

오래 실행되는 Query 수.

Transaction이 오래 열린 세션.

이 데이터를 시간에 따라 보면 한 순간의 스냅샷보다 훨씬 많은 것을 알 수 있다.

예를 들어:

평소 10~15
↓
어느 배포 이후 30
↓
며칠 뒤 50
↓
장애 직전 90

같은 패턴이 보인다면 단순히 장애 순간의 숫자만 보는 것보다 원인을 추적하기 쉬워진다.

위 숫자는 설명을 위한 예시이지만, 이런 변화 자체를 기록하는 구조가 필요하다는 점이 중요하다.

---

결국 Connection 수는 하나의 결과값이었다

처음에는 too many clients already라는 오류 때문에 Connection 숫자 자체에만 집중했다.

몇 개까지 받을 수 있느냐.

몇 개가 연결되어 있느냐.

Pool이 몇 개인가.

그런데 계속 생각해보니 Connection 수는 여러 동작의 결과로 만들어지는 값이었다.

사용자가 얼마나 들어오는지에 따라 달라진다.

Query가 얼마나 빨리 끝나는지에 따라 달라진다.

Pool의 크기에 따라 달라진다.

FastAPI worker 수에도 영향을 받을 수 있다.

컨테이너 개수에 따라서도 달라질 수 있다.

동일 DB를 사용하는 다른 서비스가 있으면 또 달라진다.

Transaction을 잘못 관리하면 Connection이 오래 점유될 수도 있다.

그래서 Connection 문제를 단순히 PostgreSQL의 숫자 하나로 해결하려고 하면 원인을 설명하기 어려워진다.

이제는 전체 흐름을 다음처럼 보는 편이 훨씬 자연스럽다.

사용자 요청
    ↓
FastAPI
    ↓
DB Connection 필요
    ↓
asyncpg Pool
    ↓
PostgreSQL Connection
    ↓
SQL 실행
    ↓
Connection 반환

이 흐름 중 어느 부분에서 작업이 오래 머무르는지를 찾아야 한다.

---

지금 다시 too many clients already를 본다면

지금 같은 오류를 다시 만난다면 예전과 순서가 많이 다를 것 같다.

가장 먼저 max_connections를 높이지는 않을 것이다.

우선 현재 상한을 확인한다.

SHOW max_connections;

그다음 실제 Connection 수와 상태를 본다.

SELECT
    state,
    COUNT(*)
FROM pg_stat_activity
GROUP BY state;

그런데 여기에서도 결론을 내리지 않는다.

예상보다 많다면 어떤 서비스에서 만든 Connection인지 본다.

SELECT
    usename,
    application_name,
    client_addr,
    state,
    COUNT(*)
FROM pg_stat_activity
GROUP BY
    usename,
    application_name,
    client_addr,
    state
ORDER BY COUNT(*) DESC;

오래 유지되는 Connection이 있다면 생성 시점과 Transaction, Query 시작 시각을 같이 본다.

그 후 애플리케이션으로 돌아가 Pool 설정과 create_pool() 위치를 확인한다.

worker와 container 수도 다시 본다.

그리고 Query가 Connection을 오래 잡고 있는 상황이라면 SQL 실행시간과 통계를 확인한다.

이 과정을 거치고도 실제 서비스 규모 때문에 정상적인 Connection이 부족하다는 결론이 나오면 그때 max_connections 조정을 검토할 수 있다.

이 순서가 예전과 가장 크게 달라진 점이다.

---

마무리

처음 too many clients already 오류를 봤을 때 내 질문은 단순했다.

max_connections를 얼마까지 높이면 될까?

지금은 그 질문부터 하지 않는다.

먼저 묻는다.

왜 지금 이렇게 많은 Connection이 필요한가?

이 질문에 답하기 위해서는 PostgreSQL 설정만 봐서는 부족하다.

pg_stat_activity에서 실제 Connection 상태를 보고, Pool이 어떻게 만들어지고 있는지 확인하고, 느린 Query가 Connection을 오래 점유하고 있지는 않은지까지 연결해서 봐야 한다.

max_connections는 분명 필요한 PostgreSQL 설정이다.

서비스 규모가 커지면 실제로 값을 조정해야 하는 상황도 있을 수 있다.

하지만 상한을 크게 만드는 것과 Connection을 올바르게 관리하는 것은 서로 다른 문제다.

내가 이 문제를 겪으면서 가장 크게 바뀐 부분은 바로 이것이었다.

Connection 한계에 도달했다는 사실을 해결해야 할 원인으로 보지 않고, 그 앞에서 어떤 일이 일어났는지를 알려주는 결과로 보기 시작한 것.

그러고 나니 too many clients already라는 메시지를 보는 방식도 달라졌다.

예전에는:

Connection이 부족하다.
→ 더 많이 허용하자.

였다면,

지금은:

Connection이 부족하다.
→ 왜 이렇게 많이 사용하고 있지?
→ 정상적인 사용량인가?
→ 어떤 상태의 Connection이 많은가?
→ 어느 서비스에서 만들었는가?
→ Query가 오래 잡고 있는 것은 아닌가?
→ Pool과 배포 구조로 설명 가능한가?

로 질문이 이어진다.

그리고 그 질문에 답한 다음에야 max_connections를 늘리는 것이 정말 필요한 조치인지 판단할 수 있다고 생각한다.

결국 PostgreSQL 설정값 하나를 바꾸는 것보다 현재 시스템에서 Connection이 만들어지고 사용되고 반환되는 흐름을 설명할 수 있는 상태를 만드는 것이 먼저였다.

FastAPI를 처음 사용하다 보면 def와 async def 중 무엇을 써야 하는지 한 번쯤 고민하게 된다.

나 역시 FastAPI 기반 검색·추천 API를 만들면서 대부분의 요청 처리 코드를 비동기로 구성했다. PostgreSQL에는 asyncpg를 사용했고, 데이터베이스 연결도 Connection Pool을 만들어 사용하는 구조였다.

그래서 처음에는 상당히 단순하게 생각했다.

@app.get("/search")
async def search():
    ...

일반적인 def가 아니라 async def를 사용했고, 데이터베이스 라이브러리 역시 비동기를 지원한다면 동시 요청을 처리할 때 자연스럽게 더 좋은 성능을 낼 것이라고 생각하기 쉽다.

그런데 코드를 계속 보다 보니 한 가지가 걸렸다.

함수 앞에 async를 붙이는 것 자체가 어떻게 코드를 빠르게 만드는 것일까?

생각해보면 조금 이상하다.

CPU가 수행해야 하는 계산량이 똑같고, PostgreSQL에서 같은 SQL을 실행하며, 외부 API에서도 같은 데이터를 받아와야 한다면 def를 async def로 바꿨다는 이유만으로 실제 작업량이 줄어드는 것은 아니다.

이 질문에서부터 비동기 코드를 다시 보게 됐다.

그리고 내가 이해한 핵심은 async가 하나의 요청을 무조건 더 빨리 끝내는 기술이라기보다, 어떤 작업이 기다리고 있는 동안 다른 요청을 처리할 수 있도록 만드는 방식이라는 것이었다.

FastAPI 공식 문서 역시 네트워크, 데이터베이스, 파일 시스템 등 결과를 기다려야 하는 작업과 async/await의 관계를 설명하고 있으며, 일반 def로 선언된 path operation은 서버를 막지 않도록 외부 thread pool에서 실행한다.

이 차이를 이해하고 나니 async def가 def보다 빠르다라는 질문 자체가 조금 부족하게 느껴졌다.

정말 먼저 봐야 할 것은 함수 안에서 무엇을 하고 있는가였다.

---

처음에는 await를 “비동기 함수를 호출하는 문법” 정도로 생각하기 쉬웠다

예를 들어 내가 사용한 asyncpg를 생각해보면 다음과 같은 코드가 나온다.

async with pool.acquire() as conn:
    rows = await conn.fetch(
        "SELECT * FROM books LIMIT 10"
    )

처음 이런 코드를 작성할 때는:

asyncpg가 비동기 라이브러리니까 await를 붙인다.

정도로 이해해도 기능을 만드는 데는 문제가 없다.

하지만 왜 await가 필요한지를 생각해보면 이 코드의 의미가 조금 달라진다.

conn.fetch()를 호출한다고 Python이 혼자서 SQL 결과를 계산하는 것은 아니다.

실제 Query는 PostgreSQL에서 처리된다.

애플리케이션은 PostgreSQL에 요청을 보내고 결과가 돌아오기를 기다려야 한다.

단순화하면 다음과 같다.

FastAPI
   ↓
SQL 요청 전송
   ↓
PostgreSQL에서 Query 처리
   ↓
결과가 올 때까지 대기
   ↓
결과 수신

여기에서 중요한 시간이 바로 대기시간이다.

FastAPI 프로세스가 PostgreSQL 결과를 기다리는 동안 CPU가 해당 요청을 위해 계속 계산하고 있어야 하는 것은 아니다.

그렇다면 그 시간에 다른 요청을 처리할 수 있다면 서버 입장에서는 훨씬 효율적이다.

await를 이해할 때 내가 중요하게 보게 된 부분이 이것이다.

Python asyncio의 event loop는 task가 멈추거나 제어권을 돌려주면 다른 작업을 실행할 수 있는 구조를 가지고 있다. 반대로 한 작업이 제어권을 오래 잡고 있으면 다른 작업들도 실행 기회를 얻지 못할 수 있다.

즉 await가 중요한 이유는 단순히:

비동기 함수를 호출하기 위한 문법

이 아니라,

지금 이 작업은 결과를 기다려야 한다.

그동안 다른 일을 처리할 수 있도록
event loop에 실행권을 돌려준다.

라는 의미를 가질 수 있기 때문이다.

이렇게 생각하고 나니 async의 장점이 조금 더 명확해졌다.

---

한 요청을 1초에서 0.5초로 만드는 것과는 다른 문제였다

예를 들어 PostgreSQL Query가 결과를 반환하는 데 1초가 걸린다고 가정해보자.

async를 사용한다고 PostgreSQL Query 자체가 갑자기 0.5초 만에 끝나는 것은 아니다.

DB가 1초 동안 해야 하는 작업은 여전히 존재한다.

대신 차이가 날 수 있는 부분은 여러 요청이 동시에 들어왔을 때다.

설명을 위해 요청 A와 B가 거의 동시에 들어왔다고 하자.

요청 A가 PostgreSQL 결과를 기다리는 동안 아무것도 할 수 없다면:

요청 A
[ DB 대기........ ]
                  ↓
                완료

요청 B
                  [ DB 대기........ ]
                                    ↓
                                  완료

처럼 처리될 수 있다.

반면 A가 DB 응답을 기다리는 시점에 실행권을 넘길 수 있다면:

요청 A
DB 요청 → 대기 ─────────→ 응답

요청 B
          DB 요청 → 대기 ─────→ 응답

처럼 대기 시간을 겹쳐 사용할 여지가 생긴다.

이걸 보고 나서야 왜 FastAPI 같은 웹 API에서 비동기가 특히 자주 등장하는지 이해하기 쉬웠다.

웹 API에는 생각보다 기다리는 작업이 굉장히 많기 때문이다.

예를 들어 내 검색·추천 서비스만 생각해도 한 요청 안에 다음과 같은 작업이 들어갈 수 있다.

PostgreSQL 조회

Elasticsearch 검색

Embedding API 요청

LLM API 요청

로그 저장

이 중 상당수는 Python CPU가 직접 결과를 만들어내기보다 다른 시스템에 요청한 뒤 응답을 기다리는 성격을 가지고 있다.

따라서 비동기의 장점은:

하나의 Query를 마법처럼 빠르게 만든다.

보다는:

하나의 요청이 외부 시스템을 기다리는 동안 다른 요청이 처리될 기회를 만든다.

로 이해하는 것이 더 정확했다.

---

그렇다면 async def로 전부 바꾸면 되는 것 아닐까?

여기까지 이해하면 또 다른 생각이 든다.

대기시간을 효율적으로 사용할 수 있다면 모든 API를 async def로 바꾸면 되는 것처럼 보인다.

나도 처음에는 이 방향이 훨씬 자연스럽다고 생각했다.

하지만 async def 안에 무엇이 들어 있는지를 다시 생각하면 문제가 생긴다.

예를 들어 다음 코드를 보자.

import time

@app.get("/test")
async def test():
    time.sleep(5)
    return {"status": "ok"}

함수 선언만 보면 분명히 비동기다.

async def test():

그런데 내부에서 사용하는 time.sleep(5)는 비동기 대기가 아니다.

현재 실행 흐름을 그대로 5초 동안 멈춘다.

이 구조에서는:

async def
    ↓
blocking operation
    ↓
event loop가 다른 일을 처리할 기회를 얻지 못함

이라는 문제가 생길 수 있다.

Python 공식 asyncio 문서에서도 blocking I/O나 CPU-bound 작업을 event loop에서 그대로 실행하면 event loop를 막을 수 있으며, 필요할 경우 executor에서 실행하는 방법을 설명한다.

이 부분에서 한 가지 중요한 결론이 나왔다.

async def라고 적혀 있다고 그 안의 모든 코드가 비동기로 실행되는 것은 아니다.

---

처음에는 함수 선언만 봤지만 이제는 내부 라이브러리부터 본다

예전에는 코드를 보면 먼저 이것을 봤다.

async def

지금은 그보다 안쪽을 먼저 본다.

예를 들어:

async def get_book():
    result = some_library.get_data()
    return result

라고 되어 있다고 하자.

여기에서 중요한 질문은:

get_book()이 async def인가?

보다:

some_library.get_data()가 호출되는 동안 실행권을 돌려줄 수 있는가?

이다.

외부 API를 호출하는 라이브러리라고 해도 동기 방식으로 통신한다면 네트워크 응답이 올 때까지 현재 실행 흐름을 붙잡고 있을 수 있다.

반대로 비동기 HTTP client를 사용하고:

result = await client.get(...)

처럼 실제 I/O 대기 구간에서 await할 수 있다면 그 시간에 다른 task가 실행될 수 있다.

FastAPI 공식 문서도 사용하는 서드파티 라이브러리가 await를 지원한다면 async def와 함께 사용하고, await를 지원하지 않는 blocking 라이브러리를 사용할 경우 일반 def path operation을 사용할 수 있다고 설명한다. 일반 def path operation은 FastAPI가 외부 thread pool에서 실행한다.

이걸 이해한 뒤에는 async가 더 빠른가보다 내가 사용하는 라이브러리가 비동기 실행을 실제로 지원하는가가 훨씬 중요한 질문이 됐다.

---

FastAPI에서 일반 def가 무조건 나쁜 것도 아니었다

처음에는 FastAPI 프로젝트 안에서 다음 코드를 보면:

def get_data():
    ...

이걸 전부:

async def get_data():
    ...

로 바꿔야 성능이 좋아질 것 같은 느낌이 있었다.

하지만 FastAPI의 동작을 보면 그렇게 단순하지 않다.

FastAPI는 일반 def로 선언된 path operation을 event loop에서 직접 실행해 전체 서버를 막는 대신 외부 thread pool에서 실행한다.

즉 다음과 같은 구조를 생각할 수 있다.

async def endpoint

→ event loop에서 실행
→ await 가능한 I/O와 잘 맞음

반대로:

def endpoint

→ FastAPI가 thread pool에서 실행
→ blocking code가 event loop를 직접 잡지 않도록 처리

이 차이를 모르고 모든 함수를 async def로 변경하면 오히려 blocking 코드를 event loop 안으로 직접 가져오는 상황도 만들 수 있다.

그래서 지금은 def를 보면:

비동기가 아니니까 느리다.

라고 판단하지 않는다.

먼저 그 함수가 어떤 작업을 하고 있는지 본다.

---

내가 가장 조심하게 된 것은 “겉만 async인 코드”다

개인적으로 더 위험하다고 느낀 코드는 이런 형태다.

@app.get("/recommend")
async def recommend():
    data = blocking_function()

    result = await async_function(data)

    return result

코드에 async, await가 모두 있으니 전체적으로 비동기 처리가 잘 되어 있는 것처럼 보인다.

하지만 실제 흐름을 보면:

요청 시작
   ↓
blocking_function()
   ↓
여기서 event loop가 오래 잡힐 수 있음
   ↓
그 뒤에야 await

가 된다.

즉 아래쪽에 await가 존재한다고 앞에서 발생한 blocking이 없어지는 것은 아니다.

이 부분 때문에 이제는 비동기 코드를 볼 때 함수 전체보다 각 작업이 어디에서 기다리고 어디에서 CPU를 사용하는지를 나눠서 본다.

---

await가 많다고 좋은 코드도 아니다

반대 방향의 오해도 생길 수 있다.

비동기 코드가 좋다고 하니 코드 곳곳에 await가 많으면 효율적인 코드라고 생각하기 쉽다.

하지만 await의 개수 자체는 성능 지표가 아니다.

예를 들어:

result1 = await api_a()
result2 = await api_b()
result3 = await api_c()

라고 되어 있다고 하자.

세 요청이 서로의 결과에 의존한다면 이 순서가 맞다.

하지만 서로 완전히 독립적인 요청이라면 지금 구조는:

A 완료 기다림
↓
B 시작
↓
B 완료 기다림
↓
C 시작

처럼 동작한다.

비동기 함수를 사용하고 있기는 하지만 서로 독립적인 대기를 순차적으로 수행하고 있는 셈이다.

이 경우에는 실제 요구사항에 따라 독립 작업을 concurrent하게 실행할 수 있는지 검토할 수도 있다.

중요한 것은:

await를 썼는가?

가 아니라:

어떤 작업은 반드시 순서대로 기다려야 하고, 어떤 작업은 동시에 기다릴 수 있는가?

이다.

비동기 프로그램을 설계할 때 이 구분이 더 중요하다고 느끼게 됐다.

---

내 검색 서비스에서도 순서가 필요한 작업과 그렇지 않은 작업이 있었다

예를 들어 자연어 검색을 생각해보면 다음 과정은 순서가 필요하다.

사용자 검색어
      ↓
Embedding 생성
      ↓
그 Embedding으로 KNN 검색

Elasticsearch KNN 검색을 하려면 Query Vector가 먼저 있어야 한다.

따라서:

Embedding 완료 전
KNN 실행

은 불가능하다.

이 경우에는 기다리는 것이 정상이다.

반면 검색 결과가 이미 준비된 뒤 서로 독립적인 부가 데이터를 여러 곳에서 조회해야 한다면 이야기가 달라질 수 있다.

이 차이를 생각하면서 비동기 설계를:

무조건 동시에 실행한다

가 아니라:

의존성이 있는 작업은 순차

독립적인 I/O는 필요하면 동시 처리

로 보게 됐다.

이런 관점이 없으면 비동기로 작성했는데도 전체 작업은 여전히 대부분 순차적으로 실행될 수 있다.

---

Database Connection Pool도 async와 별개의 제한을 가지고 있었다

asyncpg를 사용하면 많은 요청을 비동기로 처리할 수 있다.

그렇다고 PostgreSQL Connection이 무한히 생기는 것은 아니다.

내가 사용하던 구조에서는 Connection Pool에 최대 크기를 두고 있었다.

예를 들면:

pool = await asyncpg.create_pool(
    dsn=DATABASE_URL,
    min_size=1,
    max_size=50
)

여기에서 생각해야 하는 부분이 있다.

FastAPI가 동시에 500개의 요청을 받아 처리할 수 있다고 해도 모든 요청이 동시에 PostgreSQL Connection을 확보할 수 있다는 뜻은 아니다.

Pool에서 사용할 수 있는 Connection이 모두 사용 중이라면 나머지 요청은 Connection이 반환되기를 기다려야 한다.

동시 API 요청 다수
        ↓
DB 작업 필요
        ↓
Connection Pool
        ↓
사용 가능한 Connection이 있으면 실행

없으면
        ↓
Connection 반환 대기

처음에는 이런 대기를 보면 Pool을 더 크게 만들면 해결될 것처럼 느껴질 수 있다.

하지만 앞에서 PostgreSQL 연결 문제를 다루면서 생각했던 것처럼 Pool 역시 크게 할수록 무조건 좋은 설정은 아니다.

FastAPI가 비동기로 많은 요청을 받을 수 있다는 것과 PostgreSQL이 동시에 많은 Query를 안정적으로 처리할 수 있다는 것은 서로 다른 문제이기 때문이다.

즉 애플리케이션의 concurrency와 데이터베이스의 처리 용량을 동일하게 보면 안 된다.

---

비동기는 “대기를 없애는 것”이 아니라 “대기를 활용하는 것”이었다

이 문장이 내가 async를 이해하면서 가장 중요하게 느낀 부분이다.

예를 들어 DB가 1초 걸리는 작업을 비동기로 만든다고 1초라는 DB 처리시간 자체가 사라지는 것은 아니다.

외부 LLM API가 결과를 보내는 데 3초가 걸린다면 await를 붙였다고 3초가 0초가 되는 것도 아니다.

그 대신:

DB를 기다리는 1초

LLM을 기다리는 3초

같은 시간 동안 Python 서버가 다른 요청을 처리할 수 있는 여지를 만드는 것이다.

그래서 async를 성능 최적화라고 표현할 때도 조금 조심해야 한다고 생각한다.

한 요청의 latency를 줄이는 관점과 서버 전체의 concurrency를 높이는 관점은 다르기 때문이다.

---

CPU 작업에서는 이야기가 다시 달라진다

여기까지는 대부분 I/O 대기에 관한 이야기였다.

그런데 API 안에서 CPU를 오래 사용하는 작업을 실행한다면 비동기의 장점이 그대로 적용되지 않을 수 있다.

예를 들어 설명을 위해 다음과 같은 작업이 있다고 하자.

def heavy_calculation():
    result = 0

    for i in range(100_000_000):
        result += i * i

    return result

이 작업은 외부 서버의 응답을 기다리고 있는 것이 아니다.

CPU가 계속 계산해야 한다.

이를 단순히:

async def heavy_calculation():
    ...

로 바꾼다고 계산량이 줄지 않는다.

더 큰 문제는 이 계산을 event loop에서 오래 실행하면 그 시간 동안 다른 coroutine이 실행될 기회를 잃을 수 있다는 점이다.

Python 공식 문서 역시 CPU-bound 작업은 event loop를 block할 수 있으며, 이런 작업에는 일반적으로 process pool 같은 별도 실행 방식을 고려하도록 설명한다.

그래서 이제는 작업을 크게 두 종류로 나누려고 한다.

기다리는 시간이 긴 작업

DB
외부 API
네트워크
일부 파일 I/O

이런 작업에서는 async가 잘 맞을 가능성이 높다.

CPU가 계속 계산해야 하는 작업

대규모 데이터 계산
이미지 처리
무거운 변환
복잡한 CPU 연산

이런 작업은 단순히 async def로 감싼다고 해결되지 않는다.

---

async def인데 서버가 같이 느려진다면 이렇게 생각할 수 있다

만약 비동기로 작성한 API 한 개가 오래 실행될 때 다른 요청들까지 함께 느려진다면 나는 지금 다음 순서로 볼 것 같다.

처음부터:

FastAPI가 느리다.

라고 생각하지 않는다.

먼저 함수 안쪽을 본다.

async def
   ↓
어떤 라이브러리를 호출하는가?

그 다음:

실제로 await 가능한 I/O인가?

아니면 blocking 함수인가?

를 본다.

그것도 아니라면:

CPU를 오래 잡고 있는 계산은 없는가?

를 확인한다.

DB 문제라면:

asyncpg Pool에서 Connection을 기다리고 있는가?

도 본다.

외부 API라면:

상대 서버 자체가 느린 것인가?

도 분리한다.

이렇게 보면 같은 “API가 느리다”라는 현상 안에서도 원인이 완전히 다를 수 있다.

---

응답시간 하나만 기록하는 것도 부족하다

앞의 LLM 스트리밍 글에서 응답시간을 여러 구간으로 나눠야 한다고 정리했다.

FastAPI 비동기 처리도 마찬가지다.

예를 들어 검색 요청 하나가 4초 걸렸다고 하자.

전체 응답시간 = 4초

이 정보만 가지고는 async 문제인지 알 수 없다.

실제로는:

Embedding      0.5초
Elasticsearch  0.2초
PostgreSQL     0.1초
LLM            3.0초
기타           0.2초

일 수도 있다.

이 경우 FastAPI의 async def를 수정하는 것보다 LLM 호출이 전체 latency의 대부분을 차지한다는 사실을 먼저 보는 것이 맞다.

반대로 특정 Python 처리 단계에서 3초를 CPU로 사용한다면 이야기가 달라진다.

그래서 성능을 개선하려면:

비동기냐 동기냐

를 먼저 보는 것보다:

실제 시간은 어디에서 소비되고 있는가?

를 확인해야 한다.

---

동시 요청 테스트를 해야 async의 차이를 볼 수 있는 이유

비동기 코드를 테스트하면서 요청을 한 번만 보내는 것도 부족할 수 있다.

예를 들어:

요청 1개

동기 코드 = 1.0초
비동기 코드 = 1.0초

라는 결과가 나왔다고 하자.

그러면:

async를 사용해도 아무 차이가 없네.

라고 결론 내리기 쉽다.

하지만 비동기의 장점이 대기시간 동안 다른 작업을 처리하는 것이라면 요청 하나만 있을 때는 그 장점이 나타날 상황 자체가 적다.

따라서 실제로 확인하고 싶은 것은 동시 요청이 늘어날 때다.

예를 들어:

1 concurrent request

10 concurrent requests

50 concurrent requests

100 concurrent requests

처럼 요청 수를 늘려본다.

그리고 단순 평균 response time뿐 아니라:

전체 처리량

p50

p95

오류 수

DB Connection 사용량

같은 값도 볼 수 있다.

그래야 비동기 구조가 실제 동시 요청 상황에서 어떤 차이를 만드는지 확인할 수 있다.

---

그런데 동시 요청 테스트도 잘못하면 다른 것을 측정하게 된다

여기서 또 한 단계 생각해야 한다.

예를 들어 DB를 사용하는 API에 500개의 요청을 동시에 보냈다고 하자.

결과가 느려졌다.

그렇다고 바로:

FastAPI async 성능이 부족하다.

고 판단할 수 없다.

DB Pool이 최대 20개라면 대부분의 요청이 Connection을 기다린 결과일 수 있다.

또 PostgreSQL Query 자체가 병목일 수도 있다.

외부 LLM API에 rate limit이 걸렸을 수도 있다.

결국 부하 테스트에서 얻는 숫자 하나도 어디에서 기다리는지와 함께 보지 않으면 의미가 부족하다.

이 부분 때문에 성능 테스트는 숫자를 만드는 작업이라기보다 병목 위치를 설명할 수 있게 만드는 작업에 가깝다고 생각한다.

---

지금 다시 FastAPI API를 작성한다면 판단 기준은 단순하다

이제는 def와 async def를 선택할 때:

무엇이 더 빠르지?

부터 묻지 않을 것 같다.

대신 다음부터 본다.

첫째, 사용하는 라이브러리가 비동기 API를 제공하는가?

예를 들어 asyncpg처럼 await 가능한 DB 작업을 사용한다면 async def 흐름이 자연스럽다.

둘째, 함수 내부에 오래 걸리는 blocking 코드가 있는가?

있다면 async def 안에 그대로 넣는 것이 적절한지 다시 본다.

셋째, CPU-bound 작업인가?

CPU 계산이 주된 작업이라면 asyncio만으로 해결하려고 하지 않는다.

넷째, 동시에 실행할 수 있는 독립적인 I/O가 있는가?

순차적으로 기다릴 필요가 없는 작업이라면 concurrency 구조를 검토한다.

다섯째, 실제 병목은 어디인가?

FastAPI가 아니라 DB Pool, PostgreSQL, Elasticsearch, 외부 API일 수도 있다.

---

결국 async는 문법보다 실행 흐름의 문제였다

처음 FastAPI에서 async def를 사용했을 때는 이것을 일종의 성능 옵션처럼 생각했다.

def
보다
async def가 빠르다.

정도로 단순화해서 이해하기 쉬웠다.

그런데 실제 검색·추천 API처럼 PostgreSQL, Elasticsearch, Embedding, LLM API가 한 요청 안에서 이어지는 구조를 보다 보니 이 구분만으로는 설명되지 않는 부분이 너무 많았다.

중요한 것은 결국:

어디에서 CPU를 사용하는가?

어디에서 외부 결과를 기다리는가?

기다리는 동안 실행권을 돌려줄 수 있는가?

다른 요청과 동시에 진행할 수 있는 작업인가?

어떤 자원에서 동시 실행 수가 제한되는가?

였다.

그래서 지금은 async def를 다음처럼 이해하는 편이 가장 편하다.

코드를 자동으로 빠르게 만들어주는 문법이 아니라, 기다림이 많은 프로그램에서 그 대기시간을 다른 작업에 활용할 수 있도록 만드는 실행 방식이다.

그리고 이 관점으로 보면 왜 async def를 사용했는데도 API가 빨라지지 않을 수 있는지도 설명된다.

DB Query 자체가 느리면 Query를 개선해야 한다.

Connection Pool이 가득 찼다면 Pool과 DB 용량을 봐야 한다.

외부 API가 느리다면 그 시간을 별도로 측정해야 한다.

동기 blocking 라이브러리가 event loop를 붙잡고 있다면 호출 구조를 바꿔야 한다.

CPU 계산이 오래 걸린다면 async가 아니라 실행 환경 자체를 다시 생각해야 한다.

결국 async는 해결책 하나가 아니라 병목이 어디에 있는지를 이해하고 나서 선택해야 하는 도구였다.

이 사실을 이해하고 나니 FastAPI 성능 문제를 볼 때도 이제는 함수 선언부의 async부터 보지 않는다.

먼저 그 함수 안에서 무엇을 기다리고 있고, 그 기다림 동안 서버가 다른 일을 할 수 있는 구조인지부터 확인한다.

그 질문에 답할 수 있어야 async def를 사용한 이유도 설명할 수 있고, 실제로 성능 문제가 발생했을 때 어디부터 확인해야 할지도 정할 수 있기 때문이다.

Docker로 FastAPI 서비스를 운영하면서 처음에는 컨테이너 상태를 꽤 단순하게 생각했다.

컨테이너가 실행되고 있고 FastAPI 프로세스도 죽지 않았다면 서비스는 정상이라고 생각했다. 실제로 docker ps를 실행했을 때 컨테이너가 Up 상태로 보이고, 로그에서도 Uvicorn이나 애플리케이션 프로세스가 정상적으로 실행되고 있다면 적어도 서버가 살아 있다는 뜻이라고 받아들이기 쉬웠다.

그런데 Health Check를 적용하고 나면 조금 이상한 상황을 만날 수 있다.

컨테이너는 분명히 실행 중이다.

FastAPI 프로세스도 살아 있다.

그런데 Docker에서는 상태가 이렇게 보인다.

Up ... (unhealthy)

처음 이 상태를 보면 자연스럽게 이런 생각이 든다.

프로세스가 살아 있는데 왜 Docker는 이 컨테이너가 건강하지 않다고 판단하는 걸까?

나도 처음에는 running과 healthy가 거의 같은 의미라고 생각했다.

그런데 Docker의 Health Check가 무엇을 확인하는지를 다시 보면서 두 상태가 애초에 다른 질문에 대한 답이라는 것을 이해하게 됐다.

Docker에서 컨테이너가 실행 중이라는 것은 기본적으로 컨테이너의 메인 프로세스가 종료되지 않았다는 것에 가깝다.

반면 Health Check는 그 프로세스가 살아 있다는 사실에서 한 단계 더 나아가 우리가 미리 정의한 검사 명령을 실제로 통과하고 있는지를 본다. Docker 공식 문서에서도 Health Check는 프로세스가 살아 있어도 웹 서버가 무한 루프 등에 빠져 새로운 연결을 처리하지 못하는 상황을 감지할 수 있는 별도의 상태 검사라고 설명한다. Health Check가 설정되면 컨테이너는 일반 실행 상태와 별도로 starting, healthy, unhealthy 상태를 갖는다.

이 차이를 이해하고 나니 unhealthy라는 상태를 보는 방식도 달라졌다.

Docker가 컨테이너 프로세스가 죽었다고 말하는 것이 아니라, 내가 정의한 “정상 조건”을 현재 컨테이너가 만족하지 못하고 있다고 말하는 것이었다.

---

처음에는 Health Check를 단순히 /health 한 번 호출하는 기능으로 생각했다

FastAPI 서비스를 운영한다면 Health Check는 보통 복잡하게 시작하지 않는다.

예를 들어 애플리케이션에 이런 endpoint를 만든다.

from fastapi import FastAPI

app = FastAPI()


@app.get("/health")
async def health():
    return {
        "status": "ok"
    }

그리고 Docker에서는 일정 시간마다 이 주소를 호출한다.

Compose라면 대략 다음과 같은 형태다.

services:
  api:
    build: .
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 20s

처음 보면 구조가 아주 단순하다.

Docker
   ↓
/health 호출
   ↓
200 OK
   ↓
healthy

그래서 Health Check가 실패하면 자연스럽게 FastAPI 서버 자체가 죽었다고 생각하기 쉽다.

그런데 실제로는 /health 요청 하나가 성공하기까지 여러 조건이 숨어 있다.

우선 컨테이너 안에 curl 명령이 실제로 존재해야 한다.

FastAPI가 8000 포트에서 정말 열려 있어야 한다.

Health Check가 실행되는 위치에서 localhost:8000으로 접근할 수 있어야 한다.

/health라는 경로가 실제로 존재해야 한다.

그 endpoint가 인증이나 Query Parameter를 요구하지 않아야 한다.

응답이 timeout 안에 돌아와야 한다.

그리고 curl -f를 사용했다면 HTTP 오류 응답도 Health Check 실패로 처리될 수 있다. curl 공식 문서에서 -f/--fail은 HTTP 400 이상 응답을 오류로 처리하고 non-zero exit code를 반환하도록 설명되어 있다.

결국 화면에서는 단순히:

unhealthy

라고 한 단어만 보이지만 그 한 단어 뒤에는 여러 종류의 실패가 숨어 있을 수 있었다.

---

Health Check에서 422가 나왔을 때 처음에는 더 혼란스러웠다

실제로 서비스를 구성하는 과정에서 Health Check 요청이 422로 떨어지는 상황을 본 적이 있었다.

이게 처음에는 꽤 이상하게 느껴졌다.

FastAPI 서버는 정상적으로 실행되고 있었다.

프로세스가 죽은 것도 아니었다.

그런데 Docker가 상태를 확인하려고 요청을 보내면 HTTP 422가 돌아왔다.

이런 상황에서는 얼핏 보면 Docker Health Check 자체가 잘못된 것처럼 느껴진다.

하지만 조금 다르게 생각해보면 중요한 단서가 하나 있다.

HTTP 응답이 422로 돌아왔다는 것은 적어도 FastAPI 서버까지 요청이 도착했다는 뜻이다.

포트 자체에 연결하지 못했다면 전혀 다른 형태의 연결 오류가 나왔을 가능성이 높다.

서버가 요청을 받았고 FastAPI가 HTTP 응답까지 만들었다.

그런데 그 응답이 200이 아니라 422였다.

그렇다면 문제를 바라보는 위치가 달라진다.

Docker
   ↓
네트워크 연결
   ↓
FastAPI까지 요청 도착
   ↓
FastAPI가 요청 검증
   ↓
422 반환

이 구조라면:

Docker가 FastAPI에 연결하지 못한다.

보다:

Health Check가 보내는 요청이 해당 FastAPI endpoint가 기대하는 요청 형식과 맞지 않는 것은 아닐까?

라는 질문이 더 자연스럽다.

당시의 정확한 endpoint 정의와 실패 조건을 지금 여기서 기억에 의존해 원인으로 확정하고 싶지는 않다.

하지만 이 경험 때문에 한 가지는 분명해졌다.

Health Check 실패라는 결과만 보고 서버가 죽었다고 판단하면 문제를 완전히 잘못된 위치에서 찾을 수 있다는 것이다.

---

예를 들어 /health가 평범한 Health Check가 아니었다면 문제가 생길 수 있다

가장 단순한 Health Check는 이런 형태다.

@app.get("/health")
async def health():
    return {"status": "ok"}

아무것도 필요하지 않다.

그냥 요청하면 된다.

하지만 만약 endpoint가 다음처럼 만들어져 있다고 생각해보자.

@app.get("/health")
async def health(lib_code: str):
    return {
        "status": "ok",
        "lib_code": lib_code
    }

이 함수에서 lib_code에는 기본값이 없다.

FastAPI는 이를 필수 Query Parameter로 해석할 수 있다.

그런데 Docker는 다음 주소만 호출한다.

http://localhost:8000/health

그러면 Health Check가 기대하는 것은 단순하다.

GET /health

하지만 FastAPI endpoint가 기대하는 것은:

GET /health?lib_code=...

에 가깝다.

결국 Docker 입장에서 보면 서버까지 연결은 성공했지만 Health Check 명령은 성공하지 못한다.

curl -f를 사용한다면 4xx 응답은 실패 exit code로 처리되기 때문에 Docker는 이 Health Check를 실패로 기록할 수 있다.

이 상황이 반복되면 컨테이너는 계속 실행되고 있음에도 unhealthy가 될 수 있다.

이 예를 생각하고 나니 Health Check endpoint는 일반적인 비즈니스 API와 조금 다르게 설계해야겠다는 생각이 들었다.

---

Health Check에는 왜 사용자 정보가 필요하지 않아야 할까

예를 들어 일반 검색 API에는 사용자 정보가 필요할 수 있다.

@app.get("/search")
async def search(
    keyword: str,
    x_user_id: str = Header(...)
):
    ...

이건 자연스럽다.

검색 로그를 사용자별로 구분해야 할 수도 있고 사용 제한을 적용할 수도 있기 때문이다.

그런데 Health Check에도 같은 Header를 요구한다면 이야기가 달라진다.

Docker가 알고 싶은 것은:

이 사용자가 누구인가?

가 아니다.

이 애플리케이션이 지금 요청을 받을 수 있는 상태인가?

다.

사용자 인증이나 비즈니스 데이터는 Health Check의 목적과 관계가 없다.

그런데 일반 API에서 사용하던 dependency를 그대로 Health Check에도 적용하면 의도하지 않게 인증 Header나 DB 데이터가 필요한 endpoint가 될 수 있다.

이렇게 되면 Health Check는 애플리케이션 자체의 생존 여부보다 훨씬 많은 것을 검사하기 시작한다.

그리고 검사 대상이 많아질수록 unhealthy가 의미하는 것도 모호해진다.

---

여기서 “어디까지 확인해야 건강한 것인가?”라는 질문이 생겼다

처음에는 /health가 정상적으로 200을 반환하기만 하면 충분하다고 생각했다.

그런데 서비스 구조를 생각해보면 FastAPI 프로세스만 살아 있어도 실제 서비스는 사용할 수 없는 경우가 있다.

예를 들어 내 API가 PostgreSQL 없이는 아무것도 할 수 없다고 하자.

FastAPI는 실행 중이다.

/health도 그냥 문자열만 반환하기 때문에 정상이다.

@app.get("/health")
async def health():
    return {"status": "ok"}

하지만 PostgreSQL은 죽어 있다.

실제 사용자 검색 요청은 전부 실패한다.

그런데 Health Check는 계속 이렇게 말한다.

healthy

그러면 이번에는 반대 문제가 생긴다.

Health Check를 너무 단순하게 만들어서 애플리케이션 프로세스가 살아 있다는 사실만 확인하고 실제 서비스 가능 여부는 확인하지 못하고 있는 것이다.

그래서 자연스럽게 이런 생각으로 이어진다.

그렇다면 /health에서 PostgreSQL도 확인하고 Elasticsearch도 확인하고 외부 LLM API도 전부 확인해야 하는 것 아닐까?

처음에는 이쪽이 훨씬 완벽해 보인다.

---

그런데 모든 외부 의존성을 검사하면 또 다른 문제가 생긴다

예를 들어 Health Check를 다음처럼 구성한다고 생각해보자.

/health 호출
   ↓
PostgreSQL 확인
   ↓
Elasticsearch 확인
   ↓
Redis 확인
   ↓
외부 AI API 확인
   ↓
모두 성공하면 200

이렇게 하면 정말 서비스 전체가 정상인지 확인하는 것처럼 보인다.

하지만 다시 생각해보면 Health Check 자체가 상당히 무거워졌다.

30초마다 실행한다고 하면 PostgreSQL에도 30초마다 요청이 간다.

Elasticsearch에도 간다.

외부 API까지 호출한다면 불필요한 네트워크 요청이나 비용이 발생할 수도 있다.

더 큰 문제는 외부 서비스 하나가 일시적으로 느려졌을 때다.

FastAPI 프로세스에는 아무 문제가 없는데 외부 시스템의 응답이 늦어서 Health Check timeout을 넘는다.

그러면 Docker는 FastAPI 컨테이너를 unhealthy로 기록한다.

즉:

외부 서비스 문제
        ↓
Health Check 실패
        ↓
FastAPI unhealthy

가 된다.

이것이 원하는 의미인지 생각해야 한다.

내 애플리케이션 자체가 죽은 것과, 특정 외부 의존성이 일시적으로 사용할 수 없는 것은 운영 관점에서 서로 다른 문제일 수 있기 때문이다.

---

그래서 Health Check 하나에 너무 많은 의미를 넣으면 안 된다고 생각하게 됐다

이 지점에서 Health Check의 목적을 조금 나눠서 생각하는 편이 자연스러웠다.

가장 단순한 검사는 이런 질문에 답한다.

FastAPI 프로세스가 HTTP 요청을 받을 수 있는가?

이 경우에는 매우 가벼운 endpoint면 충분하다.

@app.get("/health")
async def health():
    return {"status": "ok"}

여기에는 DB Query도 필요하지 않고 인증도 필요하지 않다.

반면 운영 모니터링에서는 별도의 질문도 중요하다.

PostgreSQL에 연결할 수 있는가?

Elasticsearch가 검색 요청을 받을 수 있는가?

실제 핵심 기능을 수행할 수 있는가?

이것들은 더 깊은 상태 확인이다.

나는 지금 다시 구성한다면 이 모든 질문을 하나의 /health에 몰아넣기보다 목적에 따라 검사 수준을 나누는 방법을 먼저 생각할 것 같다.

예를 들어 애플리케이션 자체의 가벼운 상태 확인과 외부 의존성까지 확인하는 상태를 분리하는 식이다.

이렇게 해야 unhealthy가 떴을 때 그 상태가 무엇을 의미하는지도 더 명확해진다.

---

starting 상태가 존재하는 이유도 실제로 생각해보면 자연스러웠다

Health Check를 처음 켜면 컨테이너가 즉시 healthy가 되는 것이 아니라 starting 상태를 거친다.

Docker 공식 문서에서는 Health Check가 있는 컨테이너는 처음 starting 상태를 가지며, 검사 성공 시 healthy, 정해진 횟수만큼 연속 실패하면 unhealthy로 전환된다고 설명한다.

처음에는 이걸 단순한 상태 표시 정도로 생각했다.

그런데 실제 애플리케이션 부팅 과정을 보면 starting이 왜 필요한지 이해하기 쉽다.

컨테이너 프로세스가 시작됐다고 해서 애플리케이션이 바로 요청을 받을 준비가 끝나는 것은 아니다.

FastAPI를 띄우기 전에 설정 파일을 읽을 수도 있다.

DB Pool을 초기화할 수도 있다.

모델이나 데이터를 메모리에 올릴 수도 있다.

여러 초기화 작업이 끝난 뒤에야 실제 API가 정상적으로 동작하는 서비스도 있다.

즉:

Container Process Started

와:

Application Ready

사이에 시간이 존재할 수 있다.

Docker Compose 공식 문서도 docker compose up이 기본적으로 컨테이너가 running이 되는 것만 기다릴 뿐 내부 서비스가 실제 요청을 받을 준비가 끝나는 것까지 자동으로 기다리는 것은 아니라고 설명한다. 이런 경우 healthcheck와 depends_on: condition: service_healthy를 이용해 의존 서비스의 준비 상태를 기준으로 다음 서비스를 시작할 수 있다.

이 설명을 보고 나니 예전에 생각했던:

컨테이너가 떴는데 왜 DB 연결에 실패하지?

같은 현상도 이해하기 쉬워졌다.

프로세스의 시작 순서와 서비스가 실제로 준비되는 순서는 같은 것이 아니었다.

---

그래서 start_period를 단순 대기시간으로 보면 부족했다

예를 들어 애플리케이션 부팅에 평소 15초 정도가 필요한데 Health Check가 컨테이너 시작 직후부터 실패를 세기 시작한다고 하자.

아직 애플리케이션이 정상적으로 초기화 중인데 Docker 입장에서는:

첫 검사 실패
두 번째 검사 실패
세 번째 검사 실패

라고 기록할 수 있다.

그러면 서비스가 정상적으로 준비되기도 전에 unhealthy가 될 수 있다.

이 문제를 완화하기 위해 Docker Health Check에는 start_period가 있다.

Docker 공식 문서에서는 start_period를 컨테이너가 초기화될 시간을 주는 옵션으로 설명하며, 이 기간 중의 probe 실패는 retry 횟수에 포함하지 않는다. 다만 이 기간 안에 한 번 성공하면 컨테이너가 시작된 것으로 보고 이후 실패는 정상적으로 계산한다.

처음에는:

start_period: 30s

을 그냥 “30초 기다렸다 검사한다”고 이해하기 쉬웠다.

하지만 실제 의미를 보면 조금 더 세밀하다.

초기화 중 발생할 수 있는 정상적인 실패를 즉시 서비스 장애로 판단하지 않도록 유예 기간을 제공하는 것에 가깝다.

이 차이를 이해하면 값을 정할 때도 단순히 크게 잡기보다 실제 애플리케이션이 정상적으로 부팅되는 시간을 먼저 측정하고 싶어진다.

---

그렇다면 start_period를 아주 크게 잡으면 안전할까

여기까지 생각하면 또 극단적인 해결책이 떠오른다.

애플리케이션이 준비되는 데 시간이 필요하다면:

start_period: 5m

처럼 아주 크게 만들면 초기화 중 unhealthy가 되는 문제를 피할 수 있을 것 같다.

하지만 그만큼 실제로 애플리케이션이 시작 단계에서 실패했을 때 문제를 발견하는 시간도 늦어질 수 있다.

예를 들어 애플리케이션이 정상적으로는 10초 안에 준비되는데 잘못된 설정 때문에 영원히 제대로 실행되지 않는다고 하자.

start_period를 과도하게 길게 잡으면:

실제 문제 발생
    ↓
하지만 아직 start period
    ↓
실패가 retry에 반영되지 않음
    ↓
문제 판단 지연

이라는 상황이 될 수 있다.

결국 start_period 역시:

클수록 안전하다.

가 아니라:

정상적인 초기화에 필요한 시간은 허용하되, 비정상적인 초기화 실패는 너무 늦지 않게 발견할 수 있는 값

으로 보는 편이 더 자연스러웠다.

---

interval, timeout, retries도 각각 왜 있는지를 생각해야 했다

Health Check 설정을 보면 숫자가 여러 개 있다.

healthcheck:
  interval: 30s
  timeout: 5s
  retries: 3

처음에는 인터넷 예제를 보고 거의 그대로 복사하기 쉽다.

나 역시 이런 값들은 그냥 무난한 기본 설정 정도로 보기 쉬웠다.

그런데 각각이 어떤 질문에 대한 설정인지 생각해보면 의미가 달라진다.

interval은:

얼마나 자주 상태를 확인할 것인가?

에 대한 값이다.

timeout은:

검사 하나가 얼마나 오래 걸리면 실패라고 판단할 것인가?

다.

retries는:

일시적인 한 번의 실패를 바로 장애로 볼 것인지, 몇 번 연속 실패해야 상태를 바꿀 것인지?

를 결정한다.

Docker 공식 문서에서도 Health Check 명령이 timeout을 넘기면 실패로 처리되고, 설정된 retries만큼 연속 실패해야 unhealthy가 된다고 설명한다.

세 값을 따로 생각하면 Health Check가 결국 얼마나 민감하게 장애를 판단할 것인지 설정하는 것이라는 생각이 들었다.

---

너무 민감한 Health Check는 정상 서비스도 unhealthy로 만들 수 있다

예를 들어 평소 /health가 100ms 안에 응답하지만 가끔 서버 부하가 올라가 1초 정도 걸릴 수 있다고 하자.

그런데:

timeout: 500ms

로 설정했다면 정상적으로 조금 느려진 상황도 실패로 볼 수 있다.

interval도 매우 짧고 retries도 1이라면 일시적인 지연 한 번만으로 바로 unhealthy가 될 수 있다.

반대로:

interval: 10m
retries: 10

처럼 지나치게 느슨하면 실제 장애를 발견하는 데 너무 오래 걸릴 수 있다.

그래서 Health Check 수치를 정할 때도 단순히 “30초, 5초, 3회가 일반적이다”라고 끝내면 부족하다.

실제 애플리케이션이 정상일 때 /health가 어느 정도 시간 안에 응답하는지,

순간적인 지연이 어느 정도 발생하는지,

장애를 몇 초 안에 발견해야 하는지,

검사 자체가 시스템에 어느 정도 부하를 만드는지를 생각해야 한다.

결국 이 값들도 서비스의 정상 동작을 먼저 알아야 정할 수 있는 숫자였다.

---

그런데 unhealthy의 원인은 애플리케이션 코드가 아닐 수도 있었다

Health Check가 실패하면 개발자는 자연스럽게 FastAPI 코드를 먼저 본다.

하지만 Health Check 명령 자체가 실행되지 않는 경우도 있다.

예를 들어 Dockerfile을 가볍게 만들기 위해 최소한의 Python 이미지로 구성했고 그 안에 curl을 설치하지 않았다고 하자.

그런데 healthcheck는 다음과 같다.

test: ["CMD", "curl", "-f", "http://localhost:8000/health"]

FastAPI에는 아무 문제가 없다.

/health도 정상이다.

하지만 컨테이너 안에서 curl이라는 명령을 실행할 수 없다.

그러면 Health Check는 실패한다.

즉:

FastAPI 정상

/health 정상

하지만

healthcheck 명령 실행 불가

→ unhealthy

가 가능하다.

이걸 생각하고 나니 Health Check가 실패했을 때 가장 먼저 해야 할 일은 /health 코드를 수정하는 것이 아니라 Docker가 실제로 어떤 명령을 실행했고 그 명령이 왜 실패했는지를 직접 확인하는 것이라는 생각이 들었다.

Docker 공식 문서는 Health Check 명령이 출력한 stdout/stderr 일부를 health status에 저장하며 docker inspect를 통해 확인할 수 있다고 설명한다.

---

그래서 docker inspect가 훨씬 중요해졌다

컨테이너가 unhealthy라고 보이면 docker ps만 계속 볼 필요는 없다.

docker ps는 결과만 보여준다.

내가 알고 싶은 것은 왜 실패했는가다.

현재 상태를 확인하려면 예를 들어:

docker inspect container_name

으로 정보를 볼 수 있고 Health 관련 부분만 확인하도록 출력 범위를 줄일 수도 있다.

Health Check 로그에는 검사 결과와 출력이 남기 때문에 이런 상황을 구분할 수 있다.

curl: command not found

인지,

Connection refused

인지,

HTTP 422

인지,

Operation timed out

인지에 따라 봐야 할 위치가 전혀 다르다.

이 네 가지는 전부 최종적으로는:

unhealthy

라는 한 단어가 되지만 원인은 각각 다르다.

curl이 없다면 이미지 구성 문제다.

Connection refused라면 프로세스, 포트, bind 주소, 시작 시점 등을 본다.

HTTP 422라면 요청 형식과 endpoint 정의를 본다.

Timeout이라면 endpoint 안에서 무엇을 기다리고 있는지 본다.

이렇게 생각하면 unhealthy는 오류의 원인이 아니라 여기서부터 조사를 시작하라는 상태 표시에 더 가까웠다.

---

Health endpoint에서 DB까지 확인하도록 만들었다면 timeout도 다시 생각해야 했다

예를 들어 /health를 다음처럼 만든다고 생각해보자.

@app.get("/health")
async def health():
    async with pool.acquire() as conn:
        await conn.fetchval("SELECT 1")

    return {"status": "ok"}

이제 이 endpoint는 FastAPI만 확인하지 않는다.

PostgreSQL Connection Pool에서 Connection을 하나 가져오고 실제 Query가 성공해야 200을 반환한다.

이 방식의 장점은 분명하다.

PostgreSQL까지 사용할 수 있어야 healthy가 된다.

그런데 앞에서 Connection Pool 문제를 생각했던 내용을 연결해보면 한 가지 상황이 떠오른다.

실제 사용자 요청이 급증해서 Connection Pool이 모두 사용 중이다.

Health Check가 /health를 호출한다.

/health도 Connection을 얻기 위해 기다린다.

Health Check timeout은 3초다.

3초 안에 Connection을 얻지 못한다.

Health Check 실패.

높은 DB 부하
    ↓
Health Check도 DB Connection 대기
    ↓
timeout
    ↓
unhealthy

여기에서 컨테이너가 unhealthy가 된 것은 틀린 정보일까?

완전히 틀렸다고 하기도 어렵다.

실제 서비스가 DB Connection을 제때 확보하지 못하고 있으니 사용자 요청도 느려지고 있을 수 있기 때문이다.

하지만 이것을 FastAPI 프로세스 자체가 죽었다고 해석하면 역시 잘못이다.

이처럼 Health Check endpoint가 무엇을 검사하느냐에 따라 unhealthy가 의미하는 범위가 달라진다.

---

이때부터 Health Check는 “코드 한 줄”이 아니라 운영 정책이라고 생각하게 됐다

처음에는 다음 한 줄이 Health Check라고 생각했다.

test: ["CMD", "curl", "-f", "http://localhost:8000/health"]

그런데 실제로는 이 한 줄보다 그 뒤의 질문들이 더 중요했다.

/health가 무엇을 검사하는가.

HTTP 서버만 보는가.

DB도 보는가.

Elasticsearch도 보는가.

외부 AI API도 보는가.

얼마나 늦으면 실패인가.

몇 번 실패하면 장애인가.

부팅 중에는 얼마나 기다려줄 것인가.

Health Check가 실패한 뒤 어떤 시스템이 그 상태를 이용하는가.

Docker Compose에서는 의존 서비스의 Health Check를 service_healthy 조건으로 이용해 다른 서비스를 시작할 수도 있다. 즉 Health Check 결과는 단순 화면 표시를 넘어 서비스 시작 순서에도 영향을 줄 수 있다.

이걸 보고 나니 Health Check를 그냥 “Docker에 넣는 좋은 설정 하나” 정도로 취급하면 안 된다는 생각이 들었다.

무엇을 정상이라고 정의할 것인지 결정하는 운영 정책에 가까웠다.

---

정상 기준을 너무 엄격하게 만들면 장애가 전파될 수도 있다

예를 들어 FastAPI가 PostgreSQL과 Elasticsearch를 사용한다고 하자.

Health Check가 둘 다 확인한다.

FastAPI OK
PostgreSQL OK
Elasticsearch 실패

그러면 컨테이너는 unhealthy가 된다.

이 상태를 다른 자동화가 보고 해당 컨테이너를 계속 재시작하도록 구성되어 있다면 어떻게 될까?

Elasticsearch가 잠깐 느렸던 문제 때문에 정상적인 FastAPI 프로세스까지 반복적으로 재시작될 수 있다.

그 과정에서 DB Pool도 다시 만들어지고 진행 중인 요청도 영향을 받을 수 있다.

즉 Health Check가 실제 문제를 감지한 것은 맞지만 문제에 대한 대응 방법이 적절한지는 또 다른 문제다.

이 부분 때문에 Health Check와 restart policy를 하나로 생각하면 안 된다고 느꼈다.

Health Check는 상태를 판단한다.

그 상태를 보고 무엇을 할지는 별도의 운영 정책이다.

---

반대로 너무 단순한 Health Check는 거짓으로 healthy라고 말할 수도 있다

반대 상황도 존재한다.

@app.get("/health")
async def health():
    return {"status": "ok"}

이 endpoint는 거의 실패하지 않을 수 있다.

FastAPI event loop가 요청 자체를 받을 수만 있으면 200을 반환한다.

그런데 실제 핵심 검색 API는 Elasticsearch 연결 문제 때문에 전부 500을 반환하고 있다고 하자.

사용자 입장에서는 서비스 장애다.

Health Check 입장에서는:

healthy

다.

이런 상태를 보면 Health Check를 복잡하게 만들고 싶은 유혹이 다시 생긴다.

그래서 결국 완벽한 하나의 endpoint를 만드는 문제라기보다 어떤 수준의 건강 상태를 어떤 목적으로 측정할 것인지 나누는 문제에 가깝다고 생각한다.

---

지금 다시 만든다면 최소한 애플리케이션 자체 확인은 최대한 단순하게 둘 것 같다

지금의 내가 Docker 자체 Health Check를 만든다면 기본 endpoint는 상당히 가볍게 유지하려고 할 것 같다.

예를 들어:

@app.get("/health")
async def health():
    return {
        "status": "ok"
    }

이 endpoint에는 사용자 Header를 요구하지 않는다.

검색 Query Parameter도 필요하지 않다.

사용자 인증도 붙이지 않는다.

LLM API도 호출하지 않는다.

그리고 가능하면 이 endpoint 자체가 다른 복잡한 서비스 로직에 의존하지 않도록 한다.

이렇게 하는 이유는 단순히 구현이 쉽기 때문이 아니다.

Docker가 unhealthy라고 말했을 때 의미를 명확하게 하고 싶기 때문이다.

이 FastAPI 애플리케이션이 최소한 HTTP 요청에 응답할 수 있는가?

에 집중한다.

그다음 PostgreSQL, Elasticsearch 같은 의존성은 별도의 상세 상태 검사나 모니터링으로 확인하는 구조를 고려한다.

---

그러면 422 같은 오류도 훨씬 줄이기 쉬워진다

Health Check endpoint에 입력값이 없으면 Docker가 어떤 요청을 만들어야 할지 고민할 필요가 거의 없다.

GET /health

하나면 된다.

반대로 Health endpoint가 일반 비즈니스 API와 같은 dependency 구조를 사용하면서:

X-User-ID 필요

libCode 필요

Query Parameter 필요

같은 요구사항이 붙기 시작하면 Docker Compose의 Health Check에도 그 모든 조건을 맞춰줘야 한다.

그리고 애플리케이션 요구사항이 바뀔 때 Health Check 설정까지 같이 변경해야 한다.

Health Check의 목적에 필요하지 않은 입력값 때문에 422가 발생한다면 운영상 불필요한 결합이 생긴 셈이다.

그래서 예전에 Health Check에서 422를 봤던 경험을 다시 생각하면, 단순히:

curl URL을 잘못 썼다.

정도로만 기억하기보다 Health Check endpoint가 정말 Health Check에 필요한 만큼만 단순했는가라는 질문을 같이 하게 된다.

---

직접 확인할 때도 Docker가 실행하는 환경에서 확인해야 했다

호스트에서 다음 요청이 성공한다고 하자.

curl http://localhost:8000/health

그렇다고 Docker Health Check도 반드시 성공한다고 단정할 수는 없다.

Health Check 명령은 컨테이너 안에서 실행된다. Docker 공식 HEALTHCHECK 문서도 검사 명령을 컨테이너 내부에서 실행해 상태를 판단한다고 정의한다.

따라서 문제를 재현하려면 실제 컨테이너 안에서 같은 명령을 실행해보는 편이 더 직접적이다.

docker exec -it container_name \
  curl -f http://localhost:8000/health

이렇게 했을 때도 실패한다면 Docker가 Health Check에서 보고 있는 환경과 훨씬 가까운 조건에서 확인할 수 있다.

여기서:

curl 자체가 없음

을 발견할 수도 있고,

Connection refused

를 볼 수도 있고,

실제 FastAPI의:

422 Unprocessable Entity

를 볼 수도 있다.

나는 지금이라면 unhealthy가 떴을 때 설정 파일을 바로 수정하기 전에 Docker가 실행하고 있는 Health Check 명령을 컨테이너 내부에서 그대로 한번 실행해보는 것부터 시작할 것 같다.

복잡한 추측보다 훨씬 빠르게 문제 범위를 좁힐 수 있기 때문이다.

---

결국 중요한 것은 healthy라는 초록색 상태 자체가 아니었다

Health Check를 처음 적용할 때는 목표가 단순했다.

docker ps에서:

healthy

라고 보이면 성공이고,

unhealthy

라고 보이면 실패라고 생각했다.

그런데 운영 관점에서 보면 더 중요한 질문이 남는다.

무엇을 확인했기 때문에 healthy라고 말할 수 있는가?

아무것도 하지 않고 200 OK만 반환한다면 프로세스 생존 확인에는 도움이 되지만 실제 의존성 문제는 알 수 없다.

반대로 DB, Elasticsearch, 외부 API까지 모두 검사한다면 실제 서비스 가능 여부는 더 잘 볼 수 있지만 Health Check 자체가 무거워지고 외부 장애까지 애플리케이션 장애로 표현할 수 있다.

정답 하나가 존재한다기보다 서비스에서 Health Check를 어떤 의미로 사용할지 결정해야 한다.

그래서 지금은 Health Check를 만들 때 코드부터 쓰기보다 먼저 문장으로 정의해보는 편이 좋다고 생각한다.

예를 들면:

이 Health Check의 목적은 FastAPI 프로세스가 HTTP 요청을 받을 수 있는 상태인지 확인하는 것이다.

라고 정했다면 /health는 단순하게 만든다.

반대로:

이 검사는 사용자의 핵심 검색 요청을 실제로 처리할 수 있는 상태인지 확인한다.

가 목적이라면 PostgreSQL이나 Elasticsearch까지 포함해야 할 수 있다.

두 검사는 이름은 모두 Health Check라고 부를 수 있지만 실제로 대답하는 질문은 다르다.

---

마무리

FastAPI 컨테이너가 unhealthy라고 표시됐을 때 처음에는 Docker가 애플리케이션에 문제가 있다고 판단했다고 생각했다.

하지만 Health Check의 동작을 다시 보고 나니 표현을 조금 바꾸는 것이 더 정확했다.

Docker가 알고 있는 것은 내가 Health Check에 작성한 명령뿐이다.

그 명령을 실행하고 exit code가 성공이면 healthy, 연속해서 정해진 횟수만큼 실패하면 unhealthy로 상태를 바꾼다. 검사 명령의 exit status 0은 성공, 1은 unhealthy를 의미하며, 출력 내용은 일정 범위까지 docker inspect로 확인할 수 있다.

결국:

unhealthy

라는 말은

FastAPI 전체가 죽었다.

라는 진단 결과가 아니다.

더 정확하게는:

내가 정의한 Health Check 명령이 계속 실패하고 있다.

에 가깝다.

그래서 지금 다시 같은 상황을 만나면 unhealthy라는 단어 자체를 고치려고 하지 않을 것 같다.

먼저 Docker가 실제로 무슨 명령을 실행했는지 확인한다.

그 명령을 컨테이너 안에서 직접 실행해본다.

HTTP 응답이 있는지 본다.

응답이 422라면 FastAPI 요청 형식과 endpoint 정의를 본다.

연결 자체가 되지 않는다면 프로세스와 포트를 확인한다.

Timeout이라면 Health endpoint가 내부에서 무엇을 기다리는지 본다.

초기화 중에만 실패한다면 start_period가 실제 부팅시간과 맞는지 확인한다.

그리고 그 모든 것을 보기 전에 한 가지를 먼저 정한다.

내가 이 Health Check로 확인하고 싶은 “건강함”은 정확히 무엇인가?

이 질문이 명확하지 않으면 /health가 200을 반환해도 그것이 무엇을 보장하는지 설명하기 어렵고, 반대로 unhealthy가 되어도 실제로 어느 부분이 고장났는지 알기 어렵다.

결국 Docker Health Check는 단순히 운영 환경에 붙이는 한 줄짜리 검사 명령이 아니었다.

서비스에서 무엇을 정상이라고 정의할 것인지 코드로 표현하는 작은 운영 규칙에 더 가까웠다.

그리고 그 정의가 단순하고 명확할수록 문제가 생겼을 때도 unhealthy라는 결과에서 실제 원인까지 훨씬 자연스럽게 따라갈 수 있다고 생각한다.