refactor: 문서 사람처럼 작성하기

This commit is contained in:
donghyeon-ka
2026-09-22 16:24:58 +09:00
parent 1549e62b5e
commit f3bed70991
158 changed files with 4381 additions and 832 deletions
@@ -20,7 +20,7 @@ source:
# 메모리 증상 하나로 계층을 단정하지 않는다
메모리 지연이나 OOM 이 보이면 「메모리 부족」으로 닫지 말고 「문제를 진단할 때의 분류」의 다섯 갈래로 먼저 가른다. Guest Virtual Memory · Virtualization Translation · Host Memory · Dynamic Memory · NUMA 다섯이다. 「Swap Used만 보고 장애를 판단하면 안 된다」· 「NUMA는 실제 장비 topology부터 확인한다」· 「결론」에서는 따로 요구한 판독도 이 한 절차로 묶었다.
메모리 지연이나 OOM을 분석할 때는 게스트 가상 메모리, 주소 변환, 호스트 메모리, 동적 메모리 회수, NUMA를 구분해서 본다. 예를 들어 swap 사용량이 남아 있다는 사실과 현재 swap I/O가 발생한다는 사실은 다르고, NUMA 문제도 실제 호스트가 여러 NUMA node를 가질 때만 비교할 수 있다.
## 메모리 증상 하나로 결론내리면 안 되는 이유
@@ -67,7 +67,7 @@ storage latency 가 같이 증가하는가?
### 4. OOM 은 발생 계층을 확인한 뒤에 부른다
「Guest OOM과 Host OOM」에서는 게스트 OOM 과 호스트 OOM 을 갈랐다. 게스트 RAM 이 모자라서 게스트 커널이 프로세스를 죽이면 Keycloak 프로세스 종료 같은 결과가 된다. 호스트 물리 RAM 이 모자라서 호스트 커널이 QEMU 를 victim 으로 고르면 그 VM 전체가 중단될 수 있다.
「Guest OOM과 Host OOM」에서는 게스트 OOM 과 호스트 OOM 을 갈랐다. 게스트 RAM이 부족해 게스트 커널의 OOM killer가 프로세스를 종료하면 Keycloak 프로세스가 종료될 수 있다. 호스트 물리 RAM 이 모자라서 호스트 커널이 QEMU 를 victim 으로 고르면 그 VM 전체가 중단될 수 있다.
cgroup memory limit 이 걸린 환경은 예외로 둔다. 호스트 전체 RAM 에 여유가 있어도 그 cgroup 경계에서 OOM 이 발생할 수 있다고 같은 절이 적었다.
@@ -103,7 +103,7 @@ NUMA node 가 하나인 호스트에서는 NUMA 갈래의 우선순위를 낮춰
- 게스트에서 Swap Used 만 보고 「메모리 부족」으로 닫은 판독 : swap-in/out 이 지속되는지를 재지 않았다
- 게스트 free -h 에 여유가 보여 호스트를 보지 않은 판독 : 호스트 reclaim 과 호스트 스왑을 확인하지 않았다
- Keycloak 프로세스가 죽었는데 호스트 커널 로그를 보지 않은 판독 : 게스트 OOM 인지 호스트 OOM 인지 갈리지 않는다
- Keycloak 프로세스가 종료됐는데 호스트 커널 로그를 확인하지 않은 판독 : 게스트 OOM 인지 호스트 OOM 인지 갈리지 않는다
- 호스트 RAM 에 여유가 있다는 이유로 OOM 을 다른 갈래로 넘긴 판독 : cgroup 경계를 확인하지 않았다
- 토폴로지를 재지 않고 vCPU pinning 부터 손댄 조치 : NUMA 갈래가 이 호스트에 걸리는지 모른다
- 게스트와 호스트를 다른 시각에 찍어 한 표로 놓은 기록 : 같은 시간축이 아니다
@@ -17,7 +17,7 @@ source:
# 메모리 실험 결과에는 Host · VM · Workload 조건을 함께 남긴다
메모리 측정은 값만 남기면 다음 사람이 그 값을 어디에 쓸 수 있는지 알 수 없다. 「실험 시 반드시 같이 기록할 것」에서는 실험마다 함께 적을 조건을 Host 여덟 · VM 일곱 · Workload 다섯으로 못박았다. 이유도 한 줄로 적었는데, 조건을 남기지 않으면 「Memory pressure에서 느려졌다」는 결과를 다른 환경에 재사용하기 어렵다는 것이다.
메모리 실험 결과에는 측정값과 함께 호스트, VM, 워크로드 조건을 남긴다. 같은 메모리 압박이라도 호스트 RAM, swap·zswap 상태, VM 메모리 설정, NUMA 구성, 워크로드가 다르면 결과가 달라질 수 있기 때문이다.
## 조건표가 결과만큼 중요한 이유