11장. 모니터링과 트러블슈팅 — 살아있는 클러스터 다루기

운영 중인 클러스터는 살아있는 시스템입니다. 한 노드의 heap 압박이 다른 노드의 증상으로 전파되죠. green이 yellow가 되는 순간 무슨 일이 벌어지는지, 어떤 명령을 어떤 순서로 쳐야 하는지를 시나리오로 익힙니다.

11.1 Cluster health — green, yellow, red의 진짜 의미

GET /_cluster/health
{
  "status": "yellow",
  "number_of_nodes": 6,
  "active_primary_shards": 120,
  "unassigned_shards": 5,      ← 미할당 shard 수
  "number_of_pending_tasks": 0
}

노드 하나가 죽었을 때 클러스터가 어떻게 반응하는지, 상태 전이 전체를 따라가 봅시다.

11.2 진단 도구 3종 세트 — _cat, _nodes/stats, hot_threads

_cat API는 사람이 읽기 좋은 표를 반환합니다. 운영자가 가장 자주 치는 명령부터.

# 노드별 핵심 지표 한 줄씩
GET /_cat/nodes?v&h=name,node.role,heap.percent,cpu,load_1m,disk.used_percent

name     node.role  heap.percent  cpu  load_1m  disk.used_percent
es-01    cdfhirstw  68            45   2.10     67.3
es-03    cdfhirstw  85            62   3.01     71.8   ← heap 임계!

# shard 상태 (STARTED / RELOCATING / INITIALIZING / UNASSIGNED)
GET /_cat/shards?v&h=index,shard,prirep,state,docs,store,node

11.3 색인이 거부될 때 — thread pool과 429

"클라이언트에서 429 에러가 폭주해요"는 ES가 고장 난 것이 아니라 스스로를 보호하는 중이라는 신호입니다. 각 노드의 write thread pool에는 큐가 있고, 큐가 가득 차면 요청을 거부합니다.

11.4 JVM heap과 circuit breaker

heap 진단의 위험 신호: heap_used_percent > 75% 지속, old GC가 분당 수 회 이상, breaker의 tripped 카운터 증가. circuit breaker는 OOM 직전에 ES가 요청을 스스로 거부한 흔적입니다.

GET /_nodes/stats/breaker
"breakers": {
  "fielddata": { "tripped": 12 },   ← text 필드 fielddata 사용 의심 (10장)
  "parent":    { "tripped": 3 }
}

heap을 늘리기 전에 순서대로 점검하세요: ① 진짜 메모리 부족인가(cardinality 폭증, fielddata, 비싼 쿼리) ② cluster state가 큰가(shard 폭증 — 10장) ③ 쿼리가 비싼가(deep agg, deep paging). 해결 후에도 부족할 때만 RAM 추가 — 단, heap 31GB는 절대 넘기지 않습니다(compressed oops, 10장).

11.5 디스크 watermark — 85 / 90 / 95%의 3단 방어선

디스크가 차오르면 ES는 단계적으로 강하게 개입합니다. 마지막 단계는 꽤 충격적입니다: 모든 인덱스가 read-only가 됩니다.

11.6 shard가 UNASSIGNED일 때 — allocation/explain

미할당 shard의 원인은 추측하지 말고 물어보세요. 왜 할당이 안 되는지 ES가 직접 설명해 줍니다.

GET /_cluster/allocation/explain
{
  "unassigned_info": { "reason": "NODE_LEFT" },
  "node_allocation_decisions": [{
    "node_name": "es-03",
    "deciders": [{
      "decider": "disk_threshold",
      "explanation": "the node is above the high watermark..."   ← 원인이 그대로
    }]
  }]
}

11.7 증상별 진단 플로우

# "검색이 갑자기 느려졌다"
1. _cluster/health          → red? yellow? unassigned?
2. _cat/nodes?v             → 어느 노드가 heap·CPU 높은가
3. _nodes/hot_threads       → 지금 무슨 일을 하고 있나
4. _cat/thread_pool/search?v → queue·rejected?
5. slow log                 → 어떤 쿼리가 느린가 (query vs fetch phase 구분)
6. _nodes/stats/breaker     → fielddata tripped?

# "색인이 느리다 / 429 폭주"
1. _cat/thread_pool/write?v      → queue·rejected
2. _nodes/stats/indexing_pressure → 거부 카운트 (8.x)
3. _cat/allocation?v             → 디스크 watermark 임박?
4. _cluster/pending_tasks        → master 큐 적체 (mapping 폭증?)
5. _nodes/hot_threads            → merge 폭주? mapping update?

✍️ 이해도 체크