ClickHouse Cloud API 기반 메트릭 가이드

CHC의 모니터링 및 비용 데이터를 프로그래매틱하게 활용하는 방법을 다룹니다.

• ClickHouse Cloud 메트릭과 제공 정보의 이해
• 제공 방식 개요
• 제공 데이터 및 API 접근 방법
• 1. Cloud REST API
• API Key 생성 방법
• Rate Limits 및 제약사항
• 2. Billing API 상세
• Endpoint 1: GET /organizations/{organizationId}/billing
• Endpoint 2: GET /organizations/{organizationId}/usageCost
• Endpoint 3: GET /organizations/{organizationId}/services
• 3. Prometheus Metrics API
• Organization 레벨 메트릭
• Service 레벨 메트릭 (필터링)
• 4. System Tables 접근
• 접근 방법 1: ClickHouse MCP Server (AI 활용)
• 접근 방법 2: clickhouse-client (CLI)
• 주요 System Tables 쿼리 예시
• 사용 방법과 필요한 정보
• 필수 정보 체크리스트
• Organization ID 조회 방법
• Service ID 및 Endpoint 조회
• API 조합 활용 방안
• 1. 비용-리소스 통합 분석
• 2. Prometheus + Grafana 모니터링
• 3. AI 기반 비용 분석 (Claude + MCP)
• 4. 비용 최적화 워크플로우
• 5. Multi-Cloud 비용 통합
• 참고 자료
• 공식 문서
• 테스트 저장소
• 정리

ClickHouse Cloud 메트릭과 제공 정보의 이해

ClickHouse Cloud(CHC)는 관리형 서비스로서 사용자가 인프라를 직접 관리할 필요가 없지만, 비용 최적화와 성능 모니터링을 위해서는 시스템 상태를 파악할 수 있어야 합니다. CHC는 이를 위해 세 가지 주요 방식으로 메트릭과 정보를 제공합니다.

제공 방식 개요

참고 문서:

• CHC API 공식 문서
• OpenAPI Specification
• Swagger UI

제공 데이터 및 API 접근 방법

1. Cloud REST API

API Key 생성 방법

공식 가이드: Managing API Keys

Step 1: ClickHouse Cloud Console → Settings → API Keys

Step 2: New API Key 생성

Step 3: Key ID와 Secret 저장

API Key 포맷:

(실제 키 값은 아닙니다.)

Key ID: K8xY2mNp9qRsT
Secret: vW3zAb5cDe7fGh9iJk1lMn2oP3qR

Full Key: K8xY2mNp9qRsT:vW3zAb5cDe7fGh9iJk1lMn2oP3qR

보안 주의사항:

• Secret은 생성 시 한 번만 표시됨
• 분실 시 재생성 필요
• 환경 변수나 Secret Manager에 안전하게 보관
• Git 저장소에 절대 커밋하지 말 것

Rate Limits 및 제약사항

공식 문서: API Rate Limits

Rate Limit 초과시 Response:

{
  "status": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 10 seconds."
}

2. Billing API 상세

Endpoint 1: GET /organizations/{organizationId}/billing

공식 문서: Billing API Reference

Full URL:

https://api.clickhouse.cloud/v1/organizations/{organizationId}/billing?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD

Request Parameters:

Request 예시:

curl -X GET \
  'https://api.clickhouse.cloud/v1/organizations/9142daed-a43f-455a-a112-f721d02b80af/billing?startDate=2025-11-28&endDate=2025-11-30' \
  -H 'Authorization: Bearer YOUR_KEY:YOUR_SECRET'

Response 예시 (실제 데이터 - Seoul 서비스):

Response 필드 설명:

데이터 해석 예시 (위 결과 기준):

• 11/28: 높은 비용 (120 CHC) - 대량 작업 추정
• 11/29: 중간 비용 (34.58 CHC) - 정상 운영
• 11/30: 낮은 비용 (10.09 CHC) - 낮은 활동 또는 부분 집계

Endpoint 2: GET /organizations/{organizationId}/usageCost

공식 문서: UsageCost API

특징:

• Billing API보다 상세한 breakdown
• 최대 조회 기간: 31일
• ClickPipes 비용 포함

Request 예시:

curl -X GET \
  'https://api.clickhouse.cloud/v1/organizations/9142daed-a43f-455a-a112-f721d02b80af/usageCost?startDate=2025-11-30&endDate=2025-11-30' \
  -H 'Authorization: Bearer YOUR_KEY:YOUR_SECRET'

Response 예시:

상세 메트릭 설명:

Endpoint 3: GET /organizations/{organizationId}/services

공식 문서: Services API Reference

Request 예시:

curl -X GET \
  'https://api.clickhouse.cloud/v1/organizations/9142daed-a43f-455a-a112-f721d02b80af/services' \
  -H 'Authorization: Bearer YOUR_KEY:YOUR_SECRET'

Response 예시:

3. Prometheus Metrics API

공식 문서: Prometheus Integration

Organization 레벨 메트릭

Endpoint:

GET /organizations/{organizationId}/prometheus

Request 예시:

curl -X GET \
  'https://api.clickhouse.cloud/v1/organizations/9142daed-a43f-455a-a112-f721d02b80af/prometheus' \
  -H 'Authorization: Bearer YOUR_KEY:YOUR_SECRET'

Response 예시 (Prometheus Text Format):

Service 레벨 메트릭 (필터링)

Endpoint:

GET /organizations/{organizationId}/services/{serviceId}/prometheus?metrics=METRIC1,METRIC2

Request 예시:

curl -X GET \
  'https://api.clickhouse.cloud/v1/organizations/9142daed-a43f-455a-a112-f721d02b80af/services/c5ccc996-e105-4f61-aa12-4769ea485f7f/prometheus?metrics=LoadAverage1,OSMemoryAvailable,Query' \
  -H 'Authorization: Bearer YOUR_KEY:YOUR_SECRET'

Response 예시:

주요 제공 메트릭 목록:

System Resource Metrics:

• CGroupUserTimeNormalized, CGroupSystemTimeNormalized - CPU (cores)
• CGroupMaxCPU - 할당된 최대 CPU
• LoadAverage1, LoadAverage5, LoadAverage15 - 시스템 부하
• OSMemoryTotal, OSMemoryAvailable - 메모리 (bytes)
• OSMemoryBuffers, OSMemoryCached - 메모리 상세
• FilesystemMainPathTotalBytes, FilesystemMainPathUsedBytes - 디스크 (bytes)
• OSProcessesRunning - 실행 중인 프로세스 수

Query Metrics:

• Query - 전체 쿼리 수
• SelectQuery, InsertQuery - SELECT/INSERT 쿼리 수
• FailedQuery - 실패한 쿼리 수
• QueryTimeMicroseconds - 총 쿼리 실행 시간 (누적)

Storage Metrics:

• PartsActive - 활성 데이터 파트
• PartsOutdated - 비활성 파트
• Merge - Merge 작업 수
• MergedRows - Merge된 총 행 수
• BackgroundPoolTaskActive - Background task 수

Network Metrics:

• NetworkReceiveBytes, NetworkSendBytes - 네트워크 I/O (bytes, 누적)

4. System Tables 접근

공식 문서: System Tables Overview

접근 방법 1: ClickHouse MCP Server (AI 활용)

MCP 서버 설정: ClickHouse MCP Server

Claude Desktop 설정 (claude_desktop_config.json):

{
  "mcpServers": {
    "clickhouse-seoul": {
      "command": "npx",
      "args": [
        "-y",
        "@clickhouse/mcp-server-clickhouse",
        "https://c5ccc996-e105-4f61-aa12-4769ea485f7f.ap-northeast-2.aws.clickhouse.cloud:8443",
        "default",
        "your-password"
      ]
    }
  }
}

Claude와 대화로 조회:

User: "최근 1시간 CPU와 Memory 사용률을 조회해줘"

Claude (AI): [자동으로 MCP를 통해 쿼리 실행]

실제 실행된 쿼리:

실제 결과 (Seoul 서비스, 2025-11-30 11:00-12:00):

데이터 해석:

• CPU 사용량: 0.0461 + 0.0218 = 0.0679 cores (2 cores 중 3.4%)
• Memory 사용량: (264.5GB - 239.5GB) ÷ 1024³ = 25 GB (9.5%)
• 피크 CPU: 0.99 cores (49.5%)
• Sample 수: 약 3,600개 (1초당 1개 × 3,600초)

접근 방법 2: clickhouse-client (CLI)

공식 문서: clickhouse-client

연결 예시:

clickhouse-client \
  --host c5ccc996-e105-4f61-aa12-4769ea485f7f.ap-northeast-2.aws.clickhouse.cloud \
  --port 9440 \
  --secure \
  --user default \
  --password YOUR_PASSWORD \
  --query "SELECT version()"

출력:

25.8.1.8702

주요 System Tables 쿼리 예시

1. asynchronous_metric_log - 실시간 리소스 메트릭

공식 문서: asynchronous_metric_log

쿼리:

실제 결과 (Seoul 서비스, 2025-11-30 11:15-11:24):

2. query_log - 쿼리 실행 이력

공식 문서: query_log

쿼리:

실제 결과 (Seoul 서비스, 최근 1시간):

3. parts - Storage 파트 정보

공식 문서: parts

쿼리:

SELECT
    sum(rows) as total_rows,
    formatReadableSize(sum(bytes_on_disk)) as total_size_on_disk,
    formatReadableSize(sum(data_uncompressed_bytes)) as total_size_uncompressed,
    count() as active_parts,
    round(sum(bytes_on_disk) / sum(data_uncompressed_bytes) * 100, 2) as compression_ratio_pct
FROM system.parts
WHERE active = 1

실제 결과 (Seoul 서비스):

해석:

• 압축률: 10.97% (약 9.1배 압축)
• Active Parts: 833개 (적정 수준)
• 총 데이터: 약 9.5억 행

4. part_log - Merge 작업 이력

공식 문서: part_log

쿼리:

SELECT
    event_type,
    count() as event_count
FROM system.part_log
WHERE event_time >= now() - INTERVAL 24 HOUR
GROUP BY event_type
ORDER BY event_count DESC

실제 결과 (Seoul 서비스, 최근 24시간):

5. metric_log - Network I/O 통계

공식 문서: metric_log

쿼리:

SELECT
    formatReadableSize(sum(ProfileEvent_NetworkReceiveBytes)) as network_rx,
    formatReadableSize(sum(ProfileEvent_NetworkSendBytes)) as network_tx,
    formatReadableSize(sum(ProfileEvent_NetworkReceiveBytes) +
                       sum(ProfileEvent_NetworkSendBytes)) as total_network_io
FROM system.metric_log
WHERE event_time >= now() - INTERVAL 1 HOUR

실제 결과 (Seoul 서비스, 최근 1시간):

6. processes - 현재 실행 중인 쿼리

공식 문서: processes

쿼리:

SELECT
    query_id,
    user,
    elapsed as seconds_running,
    formatReadableSize(memory_usage) as memory,
    substring(query, 1, 100) as query_preview
FROM system.processes
ORDER BY elapsed DESC
LIMIT 5

실제 결과 (Seoul 서비스, 조회 시점):

사용 방법과 필요한 정보

필수 정보 체크리스트

API 사용을 위해 필요한 정보:

Cloud API 사용시:

• ✅ API Key (Key ID + Secret)
• ✅ Organization ID
• ✅ Service ID (서비스별 조회시)

System Tables 사용시:

• ✅ Service Endpoint (Host)
• ✅ Port (HTTPS: 8443, Native: 9440)
• ✅ Username (기본값: default)
• ✅ Password

Organization ID 조회 방법

Endpoint:

GET https://api.clickhouse.cloud/v1/organizations

Request:

curl -X GET 'https://api.clickhouse.cloud/v1/organizations' \
  -H 'Authorization: Bearer YOUR_KEY:YOUR_SECRET'

Response:

{
  "result": [
    {
      "id": "9142daed-a43f-455a-a112-f721d02b80af",
      "name": "My Organization",
      "createdAt": "2024-06-15T08:30:00Z"
    }
  ]
}

Service ID 및 Endpoint 조회

Request:

curl -X GET \
  'https://api.clickhouse.cloud/v1/organizations/9142daed-a43f-455a-a112-f721d02b80af/services' \
  -H 'Authorization: Bearer YOUR_KEY:YOUR_SECRET'

Response (핵심 정보만 발췌):

API 조합 활용 방안

1. 비용-리소스 통합 분석

목적: Billing API의 비용 데이터와 System Tables의 리소스 사용률을 결합하여 효율성 분석

활용 시나리오:

• 비용 효율성 분석: 할당 대비 실제 사용률 계산
• 낭비 비용 탐지: Idle 시간대 비용 낭비 측정
• 쿼리당/GB당 비용: 워크로드별 비용 최적화
• 이상 비용 탐지: 평소 대비 급등한 비용 Alert

2. Prometheus + Grafana 모니터링

목적: Prometheus API를 Grafana에 연동하여 실시간 대시보드 구축

데이터 플로우:

1. Grafana → Prometheus API 1분마다 scrape
2. Prometheus 포맷 파싱 → Grafana time-series 변환
3. 대시보드 패널에 실시간 표시

주요 메트릭:

• CPU 사용률 트렌드
• Memory 사용률 트렌드
• 쿼리 처리량 (QPS)
• Storage 증가 추이

참고: Grafana Prometheus Data Source

3. AI 기반 비용 분석 (Claude + MCP)

목적: AI를 활용하여 자연어로 비용 및 메트릭 분석

활용 예시:

사용자: "지난 주 서울 서비스의 비용 급등 원인을 분석해줘"

Claude (AI 자동 분석):

1. daily_billing 테이블에서 지난 주 비용 조회
2. query_log에서 쿼리 패턴 분석
3. asynchronous_metric_log에서 리소스 사용 추이 확인
4. 비용 급등 시점과 쿼리/리소스 패턴 상관관계 분석
5. 자연어로 원인 설명 및 권장사항 제시

장점:

• SQL 작성 불필요
• 복잡한 다중 테이블 조인 자동 처리
• 인사이트 자동 도출
• 대화형 심화 분석 가능

4. 비용 최적화 워크플로우

목적: API를 조합하여 자동화된 비용 최적화

워크플로우:

1. Billing API → 일별 비용 수집 → ClickHouse 저장
2. System Tables → 시간별 리소스 사용률 수집
3. 분석 → 효율성 계산, 낭비 비용 측정
4. Alert → 비정상 패턴 감지시 Slack 알림
5. Auto-scaling → 효율성 기준 자동 Scale 조정

5. Multi-Cloud 비용 통합

목적: CHC 비용을 AWS, GCP, Azure 비용과 통합 관리

데이터 통합:

• CHC Billing API → ClickHouse 저장
• AWS Cost Explorer API → ClickHouse 저장
• GCP Billing Export → BigQuery → ClickHouse 복제
• 단일 대시보드에서 통합 분석

활용:

• 전체 Cloud 비용 중 CHC 비중 파악
• 서비스별 인프라 비용 배분
• Cross-cloud 비용 최적화 기회 발견

참고 자료

공식 문서

API 관련:

• ClickHouse Cloud API Overview
• API Authentication
• OpenAPI Specification
• Swagger UI Documentation

Billing & Cost:

• Billing API Announcement
• CHC Pricing
• Understanding CHC Credits

Prometheus Integration:

• Prometheus Monitoring
• Prometheus API Reference

System Tables:

• System Tables Overview
• asynchronous_metric_log
• metric_log
• query_log
• parts
• part_log

ClickHouse MCP Server:

• MCP Server GitHub
• Model Context Protocol

테스트 저장소

실제 CHC API 테스트 코드 및 예시:

clickhouse-hols/chc-api-test at main · litkhai/clickhouse-hols

ClickHouse Hands-on Labs . Contribute to litkhai/clickhouse-hols development by creating an account on GitHub.

github.com

정리

ClickHouse Cloud는 세 가지 방식으로 메트릭을 제공합니다:

1. Cloud REST API

• 일별 비용 데이터 (Billing/UsageCost)
• 서비스 관리 및 상태 조회
• Organization 레벨 인증
• 주 사용처: FinOps, 비용 분석, 자동화

2. Prometheus Metrics API

• 1분 간격 시스템 메트릭
• Prometheus 포맷 표준
• Grafana 등 모니터링 도구 연동
• 주 사용처: 실시간 모니터링, Alerting

3. System Tables

• 초 단위 상세 메트릭
• SQL로 자유로운 분석
• 1000+ 메트릭 제공
• 주 사용처: 성능 튜닝, 디버깅, 심화 분석

이 세 가지를 조합하면 비용 최적화, 성능 모니터링, 이상 탐지 등 다양한 use case를 구현할 수 있습니다.