11장. 모니터링과 트러블슈팅

ClickHouse는 자기 내부 상태를 전부 SQL로 보여줍니다 — system 테이블이라는 창을 통해서. 앞 10개 장의 아키텍처 지식을 "증상 → 진단 → 원인 격리 → 대응"의 운영 무기로 바꿔봅시다.

11.1 System 테이블 맵 — 무엇을 어디서 보는가

대부분의 ClickHouse 문제는 system 테이블 쿼리만으로 진단할 수 있습니다. 각 테이블이 앞 장들의 개념과 어떻게 연결되는지 봅시다.

11.2 케이스 스터디 — "Too many parts"를 단계별로 격리하기

가장 흔한 운영 사고인 INSERT 거부를 예로, 증상 → system 테이블 진단 → 원인 격리 → 대응의 사고 흐름을 따라가 봅시다.

이 플로우의 각 단계에 해당하는 실제 쿼리입니다.

-- 1단계: 어느 테이블이 문제인지 확인
SELECT database, `table`,
    count() AS active_parts,
    uniq(partition) AS partitions,
    countIf(level = 0) AS unmerged_parts
FROM system.parts
WHERE active
GROUP BY database, `table`
HAVING active_parts > 300
ORDER BY active_parts DESC;

-- 2단계: 파티션별 분포 (과도한 파티셔닝 여부)
SELECT partition, count() AS parts, min(level) AS min_level
FROM system.parts
WHERE database = 'mydb' AND `table` = 'mytable' AND active
GROUP BY partition ORDER BY parts DESC LIMIT 20;

-- 3단계: 머지가 밀리고 있는지 확인
SELECT count() AS running_merges,
       sum(num_parts) AS merging_parts,
       formatReadableSize(sum(total_size_bytes_compressed)) AS total_size
FROM system.merges;

11.3 문제별 진단 가이드

문제: 쿼리 성능 저하

-- 느린 쿼리 Top 10
SELECT query_id, query_duration_ms, read_rows,
    formatReadableSize(read_bytes) AS read_size,
    formatReadableSize(peak_memory_usage) AS peak_mem,
    query
FROM system.query_log
WHERE type = 'QueryFinish' AND query_kind = 'Select'
  AND event_date >= today() - 1
ORDER BY query_duration_ms DESC LIMIT 10;

-- 인덱스 skip 효과 확인: Granules X/Y 비율이 핵심
EXPLAIN indexes = 1 SELECT ... FROM mytable WHERE ...;

문제: 레플리카 지연 (Replication Lag)

8장에서 배운 복제 구조를 떠올리면 진단이 자연스럽습니다 — 레플리카는 복제 로그의 큐를 처리하는 소비자이므로, 큐에 무엇이 쌓였는지가 병목의 정체를 알려줍니다.

문제: Mutation이 끝나지 않음 / 디스크 공간 부족

-- 멈춘 mutation 확인: parts_to_do가 줄지 않으면 진행 정지
SELECT database, `table`, mutation_id, command,
       is_done, parts_to_do, latest_fail_reason
FROM system.mutations
WHERE is_done = 0
ORDER BY create_time ASC;

-- 문제 mutation 강제 취소
KILL MUTATION WHERE mutation_id = 'mutation_0000000001';

-- 테이블별 디스크 사용량 (inactive 파트 포함)
SELECT database, `table`,
    formatReadableSize(sum(bytes_on_disk)) AS total_size,
    countIf(active = 0) AS inactive_parts,
    formatReadableSize(sumIf(bytes_on_disk, active = 0)) AS inactive_size
FROM system.parts
GROUP BY database, `table`
ORDER BY sum(bytes_on_disk) DESC LIMIT 20;

11.4 상시 모니터링 — 사고가 나기 전에 보는 지표

-- 파트 건강 상태: level0_pct가 높으면 머지가 밀리고 있다는 신호
SELECT database, `table`,
    count() AS active_parts,
    countIf(level = 0) AS level0_parts,
    round(countIf(level = 0) / count() * 100, 1) AS level0_pct,
    max(modification_time) AS last_insert
FROM system.parts
WHERE active
GROUP BY database, `table`
HAVING active_parts > 10
ORDER BY level0_pct DESC;

-- 시간대별 쿼리 성능 추이 (p95 추적)
SELECT
    toStartOfHour(event_time) AS hour,
    count() AS queries,
    round(avg(query_duration_ms)) AS avg_ms,
    round(quantile(0.95)(query_duration_ms)) AS p95_ms
FROM system.query_log
WHERE type = 'QueryFinish' AND query_kind = 'Select'
  AND event_date >= today() - 1
GROUP BY hour ORDER BY hour;

실시간 스레드·머지·복제 활동은 system.metrics에서 Query, Merge, PartMutation, GlobalThreadActive, ReplicatedSend/Fetch 같은 메트릭으로 확인합니다.

11.5 트러블슈팅 플로우차트 — 전체 지도

문제 발생
  │
  ├── INSERT 실패?
  │     ├── "Too many parts" → §11.2 진단 플로우
  │     └── 타임아웃 → 배치 크기·네트워크 확인
  │
  ├── 쿼리가 느리다?
  │     ├── EXPLAIN indexes=1 → Granule skip 확인 (7장)
  │     ├── system.query_log → read_bytes, peak_memory 확인
  │     └── 파트 수 확인 → 머지 밀림 여부 (6장)
  │
  ├── 레플리카 지연? → system.replicas 큐 분해 (8장)
  │
  ├── 디스크 부족? → inactive 파트 + 머지 중 임시 공간 (6장)
  │
  └── Mutation 멈춤? → system.mutations → KILL MUTATION (10장)

✍️ 이해도 체크