Prometheus HTTP API 및 PromQL

ClickHouse는 TimeSeries 테이블을 통해 Prometheus HTTP API를 구현합니다. 하나의 핸들러가 remote write, remote read, 즉시 PromQL 쿼리 및 범위 PromQL 쿼리를 처리합니다. Prometheus 서버가 스크레이프할 수 있도록 ClickHouse 자체 메트릭을 노출하려면 Prometheus 메트릭 엔드포인트를 참조하십시오.

사전 요구 사항

설정 단계는 ClickHouse Cloud와 자가 관리형 ClickHouse가 서로 다릅니다. 사용 중인 배포 방식에 해당하는 섹션을 따르십시오.

ClickHouse Cloud

ClickHouse Cloud의 PromQL 지원은 비공개 프리뷰 단계입니다. 비공개 프리뷰에 참여 중인 서비스에는 enable_time_series_table 설정과 Prometheus API 엔드포인트가 이미 구성되어 있습니다. 그 외의 ClickHouse Cloud 서비스에는 이러한 구성이 적용되어 있지 않으며, 사용자가 해당 서비스에서 직접 이 기능을 활성화할 수도 없습니다. 다음 섹션에서 설명하는 SET enable_time_series_table SQL 문과 http_handlers 구성은 자가 관리형 배포에만 해당합니다.

비공개 프리뷰에 참여 중인 서비스라면 TimeSeries 테이블 생성부터 이어서 진행하십시오. 해당 서비스는 엔드포인트 표에 나열된 엔드포인트 경로를 제공합니다.

자가 관리형: TimeSeries 설정 활성화

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

SET enable_time_series_table = 1;

HTTP API 요청의 경우 API 사용자 프로필에서 enable_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/format_query`	PromQL 표현식 포맷팅
`/prometheus/api/v1/series`	시리즈 메타데이터
`/prometheus/api/v1/metadata`	메트릭 패밀리 메타데이터

이 예시에서는 핸들러에서 database와 table을 생략합니다. 각 요청에는 table 쿼리 매개변수가 반드시 포함되어야 합니다(주어진 PromQL 표현식만 파싱하므로 테이블이 필요 없는 /format_query는 제외). 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`를 사용합니다.

TimeSeries 테이블 생성

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

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

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"

쿼리 엔드포인트는 form body로 전달된 매개변수도 허용합니다. --get 없이 실행하면 curl은 매개변수를 application/x-www-form-urlencoded 형식으로 POST 요청에 담아 전송합니다:

curl --user default:<password> \
  "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"

PromQL 표현식을 평가하지 않고 파싱하여 포맷팅하려면 format-query 엔드포인트를 사용하십시오:

curl --user default:<password> --get \
  "https://clickhouse.example.com:8443/prometheus/api/v1/format_query" \
  --data-urlencode "query=sum by(job)(http_requests_total{code=\"200\"})/2"

표현식은 파싱된 쿼리에서 직렬화되어 반환되며, 이때 공백은 정규화되고 주석은 제거되며 불필요한 괄호는 삭제되고 duration은 초 단위 숫자로 변환됩니다: sum by (job) (http_requests_total{code="200"}) / 2. 이 엔드포인트는 표현식을 평가하지 않으므로 database 및 table 매개변수가 필요하지 않습니다. 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: POST
      customQueryParameters: database=prometheus&table=metrics
    secureJsonData:
      basicAuthPassword: <password>

Grafana는 이 기준 URL 뒤에 /api/v1/query 또는 /api/v1/query_range를 추가하고, 각 요청에 customQueryParameters를 추가합니다. httpMethod: POST를 사용하면 Grafana는 쿼리 매개변수를 request body로 전송합니다. ClickHouse는 request body와 URL 쿼리 문자열을 모두 읽으므로 customQueryParameters는 계속 적용됩니다. URL에는 길이 제한이 있으므로 긴 PromQL 표현식에는 POST를 사용하십시오.

쿼리 엔드포인트인 /api/v1/query, /api/v1/query_range, /api/v1/format_query와 메타데이터 엔드포인트 /api/v1/series, /api/v1/labels, /api/v1/label/<name>/values, /api/v1/metadata만 구현되어 있습니다. /api/v1/series에는 최소 하나의 match[] 시리즈 셀렉터가 필요하며, 선택 사항인 start, end, limit 매개변수를 지원하고, 각 셀렉터와 일치하는 시리즈의 합집합을 반환합니다. /api/v1/labels는 동일한 매개변수를 허용하며, match[]는 선택 사항이고 일치하는 시리즈의 정렬된 레이블 이름을 반환합니다(셀렉터가 제공되지 않은 경우 모든 시리즈의 레이블 이름을 반환합니다). /api/v1/label/<name>/values는 /api/v1/labels와 동일한 매개변수를 허용하며 하나의 레이블에 대한 정렬된 값을 반환합니다. 이때 <name>에는 [a-zA-Z0-9_] 범위를 벗어나는 문자를 포함하는 레이블 이름에 대해 Prometheus의 U__... 이스케이프를 선택적으로 사용할 수 있습니다. 이러한 엔드포인트는 Grafana Prometheus 데이터 소스가 레이블 탐색, 템플릿 변수, 쿼리 빌더 자동 완성에 사용하는 기능을 모두 다룹니다.

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>

기본 개념

ClickHouse 개념

모범 사례

사전 요구 사항

ClickHouse Cloud

자가 관리형: TimeSeries 설정 활성화

자가 관리형: Prometheus API 엔드포인트 구성

TimeSeries 테이블 생성

remote write를 통한 메트릭 수집

PromQL로 쿼리

Grafana

SQL 진입점

메트릭 메타데이터 쿼리

remote read를 통해 메트릭 읽기

​사전 요구 사항

​ClickHouse Cloud

​자가 관리형: TimeSeries 설정 활성화

​자가 관리형: Prometheus API 엔드포인트 구성

​TimeSeries 테이블 생성

​remote write를 통한 메트릭 수집

​PromQL로 쿼리

​Grafana

​SQL 진입점

​메트릭 메타데이터 쿼리

​remote read를 통해 메트릭 읽기

사전 요구 사항

ClickHouse Cloud

자가 관리형: TimeSeries 설정 활성화

자가 관리형: Prometheus API 엔드포인트 구성

TimeSeries 테이블 생성

remote write를 통한 메트릭 수집

PromQL로 쿼리

Grafana

SQL 진입점

메트릭 메타데이터 쿼리

remote read를 통해 메트릭 읽기