API 참조
조직 전체 메트릭 엔드포인트(
GET /v1/organizations/{organizationId}/prometheus)는 자동 서비스 디스커버리 대신 더 이상 사용되지 않습니다. 기존 조직에서는 계속 사용할 수 있지만, 새로 생성된 조직에서는 대신 디스커버리 엔드포인트를 사용합니다. 이 엔드포인트에 대한 액세스가 필요하면 ClickHouse 지원팀에 문의하십시오.
이러한 엔드포인트의 전체 요청 및 응답 스키마는 Cloud API 참조에서 확인할 수 있습니다.
기본 인증에는 ClickHouse Cloud API Key를 사용하십시오:
ClickPipes의 경우 메트릭에 다음 레이블도 포함됩니다:
ClickHouse Cloud는 값이 항상
1인 gauge 타입의 특수 메트릭 ClickHouse_ServiceInfo를 제공합니다. 이 메트릭에는 모든 메트릭 레이블과 함께 다음 레이블이 포함됩니다:
메트릭을 조회하는 요청은 유휴 상태(idle)인 서비스를 재개하지 않습니다. 서비스가
idle 상태인 경우에는 ClickHouse_ServiceInfo 메트릭만 반환됩니다.
ClickPipes의 경우에도 이와 유사하게 ClickPipes_Info라는 gauge 메트릭이 있으며, 메트릭 레이블 외에 다음 레이블을 포함합니다:
Prometheus 구성
Prometheus 서버는 지정된 인터벌마다 구성된 대상에서 메트릭을 수집합니다. 아래는 ClickHouse Cloud Prometheus 엔드포인트를 사용하도록 Prometheus 서버를 구성하는 예시입니다.honor_labels 구성 매개변수는 인스턴스 레이블 값이 올바르게 채워지도록 true로 설정해야 합니다. 또한 위 예시에서는 filtered_metrics를 true로 설정했지만, 이는 사용자 선호에 따라 구성해야 합니다. 조직 내 모든 서비스를 스크레이프하려면 자동 서비스 검색을 사용하세요.
자동 서비스 검색
디스커버리 엔드포인트는 조직 내 서비스별로 하나의 스크레이프 대상을 Prometheus HTTP 서비스 디스커버리 (http_sd) 포맷으로 반환합니다. Prometheus는 디스커버리 폴링마다 대상 목록을 갱신하고 발견된 각 대상을 스크레이프하므로, 새로 생성된 서비스는 자동으로 포함되고 삭제된 서비스는 대상 목록에서 제거됩니다. API Key에 해당 서비스를 볼 권한이 있는 경우에만 포함되며, 삭제 중이거나 이미 삭제된 서비스는 제외됩니다.
사용하려면 http_sd_configs job에서 디스커버리 엔드포인트를 지정하십시오:
basic_auth를 설정합니다. http_sd_configs 아래의 블록은 디스커버리 폴링을 인증하고, 스크레이프 작업의 블록은 서비스별 메트릭 스크레이프를 인증합니다. 정적 구성과 마찬가지로 인스턴스 레이블이 올바르게 설정되도록 honor_labels: true를 지정합니다.
디스커버리 응답 예시:
__meta_clickhouse_region, __meta_clickhouse_provider, __meta_clickhouse_tag_<key> 레이블로 포함됩니다. __meta_clickhouse_tagpresent_<key>는 값이 없는 태그를 포함한 모든 태그에서 true입니다. 태그 키에 포함된 영문자, 숫자, 밑줄 이외의 문자는 _로 변환됩니다. Prometheus는 리레이블링(relabeling) 후 __meta_ 레이블을 삭제하므로, 대상을 필터링하거나 이 레이블을 유지하려면 relabel_configs를 사용하십시오:
filtered_metrics=true로 스크레이프됩니다. 전체 메트릭 세트를 스크레이프하는 대상을 발견하려면 디스커버리 URL에 ?filtered_metrics=false를 추가하십시오. 전체 엔드포인트 사양은 Cloud API 참조에서 확인할 수 있습니다.
Grafana와 통합하는 주요 방법은 두 가지입니다.
- 메트릭 엔드포인트 – 이 방식의 장점은 추가 구성 요소나 인프라가 필요 없다는 점입니다. 이 옵션은 Grafana Cloud에서만 사용할 수 있으며, ClickHouse Cloud Prometheus 엔드포인트 URL과 자격 증명만 있으면 됩니다.
- Grafana Alloy - Grafana Alloy는 Grafana Agent를 대체하는 공급업체 중립적 OpenTelemetry(OTel) collector 배포판입니다. 스크레이퍼로 사용할 수 있고 자체 인프라에 배포할 수 있으며, 모든 Prometheus 엔드포인트와 호환됩니다.
Grafana Cloud와 메트릭 엔드포인트
- Grafana Cloud 계정에 로그인하세요
- 메트릭 엔드포인트를 선택하여 새 연결을 추가하세요
- Scrape URL이 Prometheus 엔드포인트를 가리키도록 구성하고, 기본 인증을 사용해 API Key/secret으로 연결을 설정하세요
- 연결을 테스트하여 정상적으로 접속되는지 확인하세요

구성이 완료되면 대시보드 구성에 사용할 수 있도록 선택 가능한 드롭다운에 메트릭이 표시됩니다:


Alloy를 사용하는 Grafana Cloud
Grafana Cloud를 사용 중이라면 Grafana에서 Alloy 메뉴로 이동한 후, 화면의 안내에 따라 Alloy를 설치할 수 있습니다:
이렇게 하면 인증 토큰을 사용해 Grafana Cloud 엔드포인트로 데이터를 전송하는
prometheus.remote_write 컴포넌트가 포함되도록 Alloy가 구성됩니다. 이후에는 ClickHouse Cloud Prometheus 엔드포인트를 위한 스크레이퍼가 포함되도록 Alloy 구성(Linux에서는 /etc/alloy/config.alloy에 있음)만 수정하면 됩니다.
다음은 ClickHouse Cloud 엔드포인트에서 메트릭을 스크레이프하기 위한 prometheus.scrape 컴포넌트와 자동으로 구성된 prometheus.remote_write 컴포넌트가 포함된 Alloy 구성 예시입니다. basic_auth 구성 컴포넌트에는 각각 사용자 이름과 비밀번호로 Cloud API Key ID와 시크릿이 포함된다는 점에 유의하십시오.
honor_labels 구성 매개변수를 true로 설정해야 합니다.
Alloy를 사용하는 자가 관리형 Grafana
자가 관리형 Grafana 사용자는 Alloy 에이전트 설치 지침을 여기에서 확인할 수 있습니다. Alloy가 Prometheus 메트릭을 원하는 대상으로 전송하도록 이미 구성되어 있다고 가정합니다. 아래의prometheus.scrape 컴포넌트는 Alloy가 ClickHouse Cloud 엔드포인트를 스크레이프하게 합니다. prometheus.remote_write가 스크레이프된 메트릭을 수신한다고 가정합니다. 이 구성이 없다면 forward_to key를 대상에 맞게 조정하십시오.

인스턴스 레이블이 올바르게 채워지려면
honor_labels 구성 매개변수를 true로 설정해야 합니다.
Datadog와 통합하기
Datadog Agent와 OpenMetrics 통합을 사용해 ClickHouse Cloud 엔드포인트에서 메트릭을 수집할 수 있습니다. 아래에는 이 Agent와 통합에 대한 간단한 예시 구성이 나와 있습니다. 다만, 실제로는 가장 필요한 메트릭만 선별하는 것이 좋습니다. 아래의 일괄 예시는 수천 개의 메트릭-인스턴스 조합을 내보내며, Datadog는 이를 커스텀 메트릭으로 처리합니다.
관련 페이지
- 모니터링 개요 — ClickHouse Cloud의 모든 모니터링 방법을 비교합니다
- Cloud Console 모니터링 — 외부 도구 없이 사용할 수 있는 기본 제공 대시보드
- 커뮤니티 및 파트너 통합 — Datadog agent 통합 및 커뮤니티 솔루션
- 시스템 테이블 쿼리 — 시스템 메트릭에 SQL로 직접 액세스
- ClickHouse Managed Postgres Prometheus 엔드포인트 — ClickHouse Managed Postgres 서비스의 메트릭을 스크레이프합니다