모니터링 (system 테이블, Prometheus 엔드포인트, 대시보드, 경보)

지표는 세 테이블에서 나옵니다

ClickHouse 는 자기 상태를 전부 system 테이블로 보여 줍니다. 세 테이블의 성격이 달라서 같이 봐야 합니다.

세 테이블의 값은 system.metric_log 에 초 단위 이력으로 쌓입니다. "그때 무슨 일이 있었나" 를 되짚을 때는 이 테이블입니다.

SELECT toStartOfMinute(event_time) AS m,
       max(CurrentMetric_Query) AS running_q,
       max(CurrentMetric_MemoryTracking) / 1e9 AS mem_gb,
       sum(ProfileEvent_Query) AS queries,
       sum(ProfileEvent_FailedQuery) AS failed,
       sum(ProfileEvent_RejectedInserts) AS rejected
FROM system.metric_log
WHERE event_time > now() - INTERVAL 6 HOUR
GROUP BY m ORDER BY m;

로그 성격의 테이블도 함께 씁니다.

SELECT name, code, value, last_error_time, last_error_message
FROM system.errors
WHERE last_error_time > now() - INTERVAL 1 HOUR
ORDER BY value DESC;

팁 system 로그 테이블은 기본으로 무한히 자랍니다. config.d 에서 각 로그 테이블에 <ttl>event_date + INTERVAL 30 DAY</ttl> 을 주고, metric_log 처럼 큰 것은 collect_interval_milliseconds 를 늘려 줍니다. 로그 테이블 자체가 디스크를 채운 사고가 드물지 않습니다.

Prometheus 엔드포인트

설정 한 조각으로 서버가 Prometheus 형식 지표를 내보냅니다.

<clickhouse>
    <prometheus>
        <endpoint>/metrics</endpoint>
        <port>9363</port>
        <metrics>true</metrics>
        <events>true</events>
        <asynchronous_metrics>true</asynchronous_metrics>
        <errors>true</errors>
    </prometheus>
</clickhouse>

curl -s http://localhost:9363/metrics \
  | grep -E 'ClickHouseMetrics_Query |ClickHouseAsyncMetrics_MaxPartCountForPartition'

지표 이름은 ClickHouseMetrics_, ClickHouseProfileEvents_, ClickHouseAsyncMetrics_, ClickHouseErrorMetric_ 접두어가 붙습니다. 복제본 수십 대를 긁는 쪽이 Prometheus 이고, 서버는 요청받을 때 값을 만들어 줍니다. Keeper 도 같은 방식의 <prometheus> 설정이 있습니다.

Cloud 는 조직 단위 Prometheus 엔드포인트(API 키로 인증)를 제공해 Grafana 나 Datadog 에 붙일 수 있습니다. 서비스 콘솔의 고급 대시보드로도 같은 지표를 봅니다 (ClickHouse Cloud 개요).

대시보드

• 내장 대시보드: 서버 HTTP 포트의 /dashboard 경로(http://host:8123/dashboard)에 쿼리 기반 차트가 들어 있습니다. 차트 정의는 system.dashboards 테이블에 있고 직접 추가할 수 있습니다. 설치 직후 바로 쓸 수 있어 급할 때 좋습니다.
• Grafana: 공식 ClickHouse 데이터 소스 플러그인(grafana-clickhouse-datasource)으로 system 테이블을 직접 쿼리하거나 Prometheus 를 거쳐 봅니다. 공개된 대시보드 템플릿이 여럿 있습니다.
• 자기 관측: ClickStack(HyperDX)으로 ClickHouse 자신의 로그와 트레이스를 ClickHouse 에 넣어 보는 구성도 가능합니다 (ClickStack과 chDB).

대시보드 첫 화면에 두는 패널은 보통 다음과 같습니다. 왼쪽 위에서부터 중요 순서입니다.

1. 실행 중 쿼리 수와 초당 쿼리 수, 실패 수
2. 쿼리 p50 과 p95 (query_log 기준)
3. 메모리: MemoryResident 와 서버 한도, MemoryTracking
4. INSERT: 초당 행 수, RejectedInserts, DelayedInserts
5. 파트: MaxPartCountForPartition, 머지 풀 사용량
6. 복제: ReplicasMaxAbsoluteDelay, ReplicasMaxQueueSize, ReadonlyReplica
7. 디스크 여유 (system.disks), CPU, 네트워크

경보 목록

실제로 걸어 두고 밤에 깨울 가치가 있는 것만 모았습니다. 수치는 출발점입니다.

경보를 SQL 로 만들려면 Grafana 의 ClickHouse 데이터 소스에서 아래 같은 쿼리를 주기적으로 돌립니다.

SELECT
    (SELECT value FROM system.asynchronous_metrics
     WHERE metric = 'MaxPartCountForPartition') AS max_parts,
    (SELECT value FROM system.asynchronous_metrics
     WHERE metric = 'ReplicasMaxAbsoluteDelay') AS max_delay,
    (SELECT value FROM system.metrics WHERE metric = 'ReadonlyReplica') AS readonly_replicas,
    (SELECT count() FROM system.mutations WHERE NOT is_done) AS pending_mutations;

상태 확인 엔드포인트

curl -s http://localhost:8123/ping              # Ok.
curl -s http://localhost:8123/replicas_status   # Ok. 또는 뒤처진 복제본 목록 (503)
curl -s 'http://localhost:8123/?query=SELECT%201'

로드 밸런서 헬스 체크에는 /replicas_status 를 쓰면 뒤처진 복제본을 자동으로 빼 줍니다. 허용 지연은 max_replica_delay_for_distributed_queries 를 따릅니다.

운영 루틴

• 매일 아침: 전날 system.errors 상위, 실패 쿼리 수, 백업 상태, 디스크 추세를 한 화면에서 봅니다.
• 매주: query_log p95 상위 20 개 쿼리 모양을 뽑아 성능 회귀를 찾습니다 (느린 쿼리 진단).
• 매달: system.settings_changes 와 릴리스 노트로 다음 업그레이드를 준비하고, 로그 테이블 크기와 TTL 을 확인합니다.
• 배포 뒤: 배포 전후 30 분의 metric_log 를 비교해 메모리와 쿼리 수의 변화를 봅니다.

공식 문서

• Monitoring 개요
• system.metrics, system.events, system.asynchronous_metrics
• Prometheus 설정
• system.metric_log, system.errors
• Grafana ClickHouse data source
• ClickHouse Cloud Prometheus 연동