Prometheus 프로토콜 및 PromQL

ClickHouse 서버 메트릭 노출

ClickHouse Cloud를 사용하는 경우 Prometheus 통합을 통해 Prometheus에 메트릭을 노출할 수 있습니다.

Prometheus 서버가 ClickHouse 자체 메트릭을 스크레이프해야 하는 경우 전용 포트를 구성하십시오:

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

동일한 포트에서 더 확장된 핸들러를 구성하려면 <prometheus.handlers> 섹션을 사용할 수 있습니다. 이 섹션은 <http_handlers>와 유사하지만 Prometheus 프로토콜에서 작동합니다:

<prometheus>
    <port>9363</port>
    <handlers>
        <my_rule_1>
            <url>/metrics</url>
            <handler>
                <type>expose_metrics</type>
                <metrics>true</metrics>
                <asynchronous_metrics>true</asynchronous_metrics>
                <events>true</events>
                <errors>true</errors>
                <histograms>true</histograms>
                <dimensional_metrics>true</dimensional_metrics>
                <labels>
                    <environment>production</environment>
                    <shard from_env="SHARD_NAME"></shard>
                </labels>
            </handler>
        </my_rule_1>
    </handlers>
</prometheus>

설정:

Name	Default	Description
`port`	없음	ClickHouse 메트릭을 제공하는 포트입니다.
`endpoint`	`/metrics`	메트릭을 수집할 HTTP 엔드포인트입니다. `/`로 시작합니다. `<handlers>` 섹션과 함께 사용하면 안 됩니다.
`url` / `headers` / `method`	없음	요청에 일치하는 핸들러를 찾는 데 사용하는 필터입니다. `<http_handlers>` 섹션의 동일한 이름의 필드와 유사합니다.
`info`	true	서버 아이덴티티 레이블(`name`, `version`, `version_describe`, `version_major`, `version_minor`, `version_patch`)과 함께 `ClickHouse_Info` Gauge를 노출합니다.
`metrics`	true	`system.metrics`의 메트릭을 노출합니다.
`asynchronous_metrics`	true	`system.asynchronous_metrics`의 메트릭을 노출합니다.
`events`	true	`system.events`의 메트릭을 노출합니다.
`errors`	true	`system.errors`의 오류 수를 노출합니다.
`histograms`	true	`system.histogram_metrics`의 메트릭을 노출합니다.
`dimensional_metrics`	true	`system.dimensional_metrics`의 메트릭을 노출합니다.
`labels`	없음	노출되는 모든 메트릭에 추가되는 상수 레이블입니다. 각 하위 요소는 하나의 레이블을 정의합니다. 요소 이름은 레이블 이름이며(`[a-zA-Z_][a-zA-Z0-9_]*`와 일치해야 함), 요소 값은 레이블 값입니다. 레이블 값은 `from_env` 속성과 같은 표준 구성 치환을 지원합니다. 레이블 이름이 `__`로 시작하거나(Prometheus에서 예약됨), 이 엔드포인트가 활성화된 섹션 중 하나에서 이미 내보내는 레이블과 충돌하면 거부됩니다. 따라서 예약된 집합은 엔드포인트에서 현재 활성화된 노출 범위를 따릅니다. `histograms`가 활성화된 경우 `le`, `info`가 활성화된 경우 `ClickHouse_Info` 레이블(`name`, `version`, `version_describe`, `version_major`, `version_minor`, `version_patch`), `histograms` 또는 `dimensional_metrics`가 활성화된 경우 노출된 히스토그램 또는 차원 메트릭 패밀리에서 사용하는 모든 레이블(예: `group`, `direction`, `operation_type`)이 해당합니다. 엔드포인트가 실제로 노출하는 항목에 따라 달라지므로, 한 엔드포인트에서는 유효한 이름이 다른 엔드포인트에서는 거부될 수 있습니다.

엔드포인트를 확인하십시오:

curl http://127.0.0.1:9363/metrics

Prometheus HTTP API 및 PromQL

ClickHouse는 TimeSeries 테이블을 통해 Prometheus HTTP API를 구현합니다. 하나의 핸들러가 remote write, remote read, 즉시 PromQL 쿼리 및 범위 PromQL 쿼리를 처리합니다.

사전 요구 사항

테이블을 생성하고 액세스하는 사용자에 대해 allow_experimental_time_series_table 설정을 활성화하십시오:

SET allow_experimental_time_series_table = 1;

데이터베이스와 TimeSeries 테이블을 생성합니다.

CREATE DATABASE prometheus;
CREATE TABLE prometheus.metrics ENGINE = TimeSeries;

HTTP API 요청의 경우 API 사용자 profile에서 allow_experimental_time_series_table을 활성화하십시오.

Prometheus API 구성

기본 ClickHouse HTTP 포트에 접두사 기반으로 라우팅되는 핸들러 하나를 구성합니다:

<http_handlers>
    <defaults/>
    <rule>
        <url_prefix>/prometheus/api/v1</url_prefix>
        <handler>
            <type>prometheus_api_v1</type>
        </handler>
    </rule>
</http_handlers>

<defaults/>는 /ping 및 SQL 요청 같은 엔드포인트에 대한 기본 제공 핸들러를 유지합니다. 위의 접두사는 하나의 핸들러를 통해 이러한 엔드포인트를 노출합니다.

엔드포인트	용도
`/prometheus/api/v1/write`	Prometheus remote write
`/prometheus/api/v1/read`	Prometheus remote read
`/prometheus/api/v1/query`	즉시 PromQL 쿼리
`/prometheus/api/v1/query_range`	범위 PromQL 쿼리
`/prometheus/api/v1/series`	시리즈 메타데이터
`/prometheus/api/v1/metadata`	메트릭 패밀리 메타데이터

이 예시에서는 핸들러에서 database와 table을 생략합니다. 각 요청에는 table 쿼리 매개변수가 반드시 포함되어야 합니다. database를 지정하거나, prometheus.metrics와 같은 정규화된 테이블 이름을 사용하거나, 데이터베이스를 생략해 default를 사용할 수도 있습니다. 따라서 하나의 핸들러로 여러 TimeSeries 테이블을 처리할 수 있습니다. 모든 요청에 하나의 고정 테이블을 사용하려면 핸들러에서 이를 구성하십시오.

<handler>
    <type>prometheus_api_v1</type>
    <database>prometheus</database>
    <table>metrics</table>
</handler>

핸들러에 구성된 테이블은 요청 매개변수로 재정의할 수 없습니다. 라우팅 및 핸들러 설정:

이름	기본값	설명
`url_prefix`	none	구성된 접두사로 시작하는 모든 요청 경로와 일치하는 규칙 필터입니다.
`table`	none	`TimeSeries` 테이블 이름입니다. 생략하면 요청에서 `table` 쿼리 매개변수를 제공해야 합니다. 구성된 이름에는 데이터베이스를 포함할 수 있습니다.
`database`	none	테이블이 포함된 데이터베이스입니다. 요청에서 쿼리 매개변수로 지정할 수 있습니다. 생략하면 ClickHouse는 정규화된 `table` 값에 지정된 데이터베이스를 사용하며, 없으면 `default`를 사용합니다.

remote write를 통한 메트릭 수집

ClickHouse는 Prometheus remote-write 프로토콜을 지원합니다. Prometheus가 핸들러에 쓰도록 구성하십시오:

remote_write:
  - url: https://clickhouse.example.com:8443/prometheus/api/v1/write?database=prometheus&table=metrics
    basic_auth:
      username: default
      password: <password>

Prometheus는 샘플을 prometheus.metrics 테이블로 전송합니다. 동시에 발생하는 여러 remote-write 요청의 데이터를 더 적은 수의 파트로 일괄 처리하려면 URL에 async_insert 설정을 추가하여 비동기 삽입을 활성화하십시오(또는 사용자 프로필에서 활성화하십시오):

remote_write:
  - url: https://clickhouse.example.com:8443/prometheus/api/v1/write?database=prometheus&table=metrics&async_insert=1

ClickHouse는 wait_for_async_insert 설정과 관계없이 데이터가 TimeSeries 테이블의 모든 내부 테이블에 플러시된 후에만 비동기 remote-write 요청을 승인합니다. remote-write 프로토콜은 승인된 쓰기를 영속성이 보장된 것으로 간주합니다. 플러시에 실패하면 요청에서 오류가 반환되고 Prometheus가 재시도합니다.

PromQL로 쿼리

특정 시점에서 PromQL 표현식을 평가하려면 instant-query 엔드포인트를 사용하십시오:

curl --user default:<password> --get \
  "https://clickhouse.example.com:8443/prometheus/api/v1/query" \
  --data-urlencode "query=rate(http_requests_total[5m])" \
  --data-urlencode "database=prometheus" \
  --data-urlencode "table=metrics"

range-query 엔드포인트를 사용하여 지정한 시간 범위에서 표현식을 평가합니다:

curl --user default:<password> --get \
  "https://clickhouse.example.com:8443/prometheus/api/v1/query_range" \
  --data-urlencode "query=rate(http_requests_total[5m])" \
  --data-urlencode "start=2026-08-15T12:00:00Z" \
  --data-urlencode "end=2026-08-15T13:00:00Z" \
  --data-urlencode "step=60s" \
  --data-urlencode "database=prometheus" \
  --data-urlencode "table=metrics"

HTTP API, promql 방언 및 테이블 함수에서 지원하는 함수와 집계 연산자 목록은 지원되는 PromQL 기능을 참조하십시오.

Grafana

기준 URL이 /api/v1 앞에서 끝나도록 Prometheus 데이터 소스를 구성하십시오:

apiVersion: 1
datasources:
  - name: ClickHouse Prometheus
    type: prometheus
    access: proxy
    url: https://clickhouse.example.com:8443/prometheus
    basicAuth: true
    basicAuthUser: default
    jsonData:
      httpMethod: GET
      customQueryParameters: database=prometheus&table=metrics
    secureJsonData:
      basicAuthPassword: <password>

Grafana는 이 기준 URL 뒤에 /api/v1/query 또는 /api/v1/query_range를 추가하고, 각 요청에 customQueryParameters를 추가합니다.

쿼리 엔드포인트인 /api/v1/query 및 /api/v1/query_range와 메타데이터 엔드포인트 /api/v1/series, /api/v1/labels, /api/v1/metadata만 구현되어 있습니다. /api/v1/series에는 최소 하나의 match[] 시리즈 셀렉터가 필요하며, 선택 사항인 start, end, limit 매개변수를 지원하고, 각 셀렉터와 일치하는 시리즈의 합집합을 반환합니다. /api/v1/labels는 동일한 매개변수를 허용하며, match[]는 선택 사항이고 일치하는 시리즈의 정렬된 레이블 이름을 반환합니다(셀렉터가 제공되지 않은 경우 모든 시리즈의 레이블 이름을 반환합니다). Grafana Prometheus 데이터 소스에서 레이블 탐색, 템플릿 변수, 쿼리 빌더 자동 완성에 사용하는 레이블 값 엔드포인트(/api/v1/label/<name>/values)는 구현되어 있지 않으므로 오류를 반환합니다. 쿼리 빌더 대신 코드 모드에서 PromQL 표현식을 작성하십시오.

SQL 진입점

ClickHouse는 HTTP API, promql 방언, prometheusQuery 및 prometheusQueryRange 테이블 함수에서 동일한 PromQL 컨버터를 사용합니다. clickhouse-client에서 PromQL을 직접 실행합니다:

clickhouse-client \
  --dialect promql \
  --promql_database prometheus \
  --promql_table metrics \
  --query 'rate(http_requests_total[5m])'

테이블 함수를 사용하여 SQL 쿼리에 PromQL을 삽입합니다:

SELECT *
FROM prometheusQuery(
    prometheus.metrics,
    'rate(http_requests_total[5m])',
    now()
);

메트릭 메타데이터 쿼리

/prometheus/api/v1/metadata 엔드포인트는 TimeSeries 테이블의 Metrics 대상 테이블에 저장된 메트릭 메타데이터(각 메트릭 패밀리의 유형, 도움말 텍스트, 단위)를 반환합니다. URL 쿼리 문자열에서 다음 Prometheus 매개변수를 지원합니다.

매개변수	설명
`metric`	지정한 메트릭 패밀리의 메타데이터만 반환합니다.
`limit`	반환할 메트릭 패밀리 수를 제한합니다. 음수 값은 제한 없음을 의미하며, 0이면 메트릭 패밀리를 반환하지 않습니다.
`limit_per_metric`	각 메트릭 패밀리에서 반환할 메타데이터 객체 수를 제한합니다. 0 및 음수 값은 제한 없음을 의미합니다.

기본 Metrics 대상 테이블은 메트릭 패밀리 이름을 기준으로 정렬된 ReplacingMergeTree입니다. 각 메트릭 패밀리에서 가장 최근에 기록된 메타데이터 항목을 유지합니다. 대상 테이블에 여러 항목이 저장되어 있는 동안에만 패밀리당 여러 항목이 반환됩니다. 즉, 파트가 머지되기 전이거나 테이블이 항목을 보존하는 엔진으로 정의된 경우입니다.

curl --user default:<password> --get \
  "https://clickhouse.example.com:8443/prometheus/api/v1/metadata" \
  --data-urlencode "metric=http_requests_total" \
  --data-urlencode "database=prometheus" \
  --data-urlencode "table=metrics"

remote read를 통해 메트릭 읽기

ClickHouse는 /prometheus/api/v1/read에서 Prometheus remote-read 프로토콜을 지원합니다. 동일한 TimeSeries 테이블에서 읽도록 Prometheus 서버를 구성합니다:

remote_read:
  - url: https://clickhouse.example.com:8443/prometheus/api/v1/read?database=prometheus&table=metrics
    basic_auth:
      username: default
      password: <password>

Fundamentals

ClickHouse concepts

Best practices

ClickHouse 서버 메트릭 노출

Prometheus HTTP API 및 PromQL

사전 요구 사항

Prometheus API 구성

remote write를 통한 메트릭 수집

PromQL로 쿼리

Grafana

SQL 진입점

메트릭 메타데이터 쿼리

remote read를 통해 메트릭 읽기

​ClickHouse 서버 메트릭 노출

​Prometheus HTTP API 및 PromQL

​사전 요구 사항

​Prometheus API 구성

​remote write를 통한 메트릭 수집

​PromQL로 쿼리

​Grafana

​SQL 진입점

​메트릭 메타데이터 쿼리

​remote read를 통해 메트릭 읽기

ClickHouse 서버 메트릭 노출

Prometheus HTTP API 및 PromQL

사전 요구 사항

Prometheus API 구성

remote write를 통한 메트릭 수집

PromQL로 쿼리

Grafana

SQL 진입점

메트릭 메타데이터 쿼리

remote read를 통해 메트릭 읽기