Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Prometheus 프로토콜 및 PromQL

View as MarkdownEdit this pageReport an issueSet up docs MCP

ClickHouse 서버 메트릭 노출

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
ClickHouse Cloud에서 지원되지 않음

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를 추가합니다.

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>
Navigation