> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Prometheus HTTP API 및 PromQL

> ClickHouse의 Prometheus HTTP API 지원: TimeSeries 테이블을 통한 remote write, remote read 및 PromQL 쿼리.

비공개 프리뷰

ClickHouse는 [`TimeSeries`](https://clickhouse.com/docs/ko/reference/engines/table-engines/integrations/time-series) 테이블을 통해 Prometheus HTTP API를 구현합니다. 하나의 핸들러가 remote write, remote read, 즉시 PromQL 쿼리 및 범위 PromQL 쿼리를 처리합니다.

Prometheus 서버가 스크레이프할 수 있도록 ClickHouse 자체 메트릭을 노출하려면 [Prometheus 메트릭 엔드포인트](https://clickhouse.com/docs/ko/concepts/features/interfaces/prometheus-metrics.md)를 참조하십시오.

## 사전 요구 사항

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

### ClickHouse Cloud

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

비공개 프리뷰에 참여 중인 서비스라면 [TimeSeries 테이블 생성](#create-a-timeseries-table)부터 이어서 진행하십시오. 해당 서비스는 [엔드포인트 표](#configure-prometheus-api)에 나열된 엔드포인트 경로를 제공합니다.

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

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

```sql theme={null}
SET enable_time_series_table = 1;
```

HTTP API 요청의 경우 API 사용자 프로필에서 `enable_time_series_table`을 활성화하십시오.

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

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

```xml theme={null}
<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` 테이블을 처리할 수 있습니다.

모든 요청에 하나의 고정 테이블을 사용하려면 핸들러에서 이를 구성하십시오.

```xml theme={null}
<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` 테이블을 생성합니다.

```sql theme={null}
CREATE DATABASE prometheus;
CREATE TABLE prometheus.metrics ENGINE = TimeSeries;
```

## remote write를 통한 메트릭 수집

ClickHouse는 [Prometheus remote-write 프로토콜](https://prometheus.io/docs/specs/remote_write_spec/)을 지원합니다. Prometheus가 핸들러에 쓰도록 구성하십시오:

```yaml theme={null}
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 요청의 데이터를 더 적은 수의 파트로 일괄 처리하기 위해 ClickHouse는 [비동기 삽입](https://clickhouse.com/docs/ko/reference/settings/session-settings/async-insert.md#async_insert)을 사용합니다. 비동기 삽입은 기본적으로 활성화되어 있으며, URL(또는 사용자 프로필)의 `async_insert` 설정으로 켜거나 끌 수 있습니다.

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

각 요청은 자신의 플러시가 끝날 때까지 기다리므로, 비동기 삽입을 사용하면 단일 송신자의 쓰기 속도가 제한됩니다. Prometheus는 remote-write 세그먼트당 한 번에 하나의 요청만 전송합니다. 여러 세그먼트가 동시에 전송하면, 대기 중인 요청이 먼저 [`async_insert_max_data_size`](https://clickhouse.com/docs/ko/reference/settings/session-settings/async-insert#async_insert_max_data_size)에 도달하지 않는 한 적응형 플러시 타임아웃이 [`async_insert_busy_timeout_max_ms`](https://clickhouse.com/docs/ko/reference/settings/session-settings/async-insert#async_insert_busy_timeout_max_ms)까지 늘어납니다. 요청은 자신이 속한 배치가 플러시될 때까지 대기하며, 플러시는 배치가 시작된 후 최대 이 시간이 지난 뒤에 이루어집니다. 따라서 부하가 지속되는 상황에서 각 세그먼트의 쓰기 속도는 대략 `samples per request / async_insert_busy_timeout_max_ms`이며, Prometheus는 기본적으로 요청당 최대 2,000개의 샘플을 전송합니다. 이 속도를 높이는 방법은 다음과 같습니다.

* [`remote_write`](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#remote_write)의 `queue_config`에서 `max_shards`(기본값 50) 또는 `max_samples_per_send`를 늘리십시오. Prometheus는 처리가 뒤처지면 `max_shards`까지 자동으로 세그먼트를 추가합니다.
* URL 또는 사용자 프로필에서 `async_insert_busy_timeout_max_ms`를 낮추십시오(예: `&async_insert_busy_timeout_max_ms=50`). 이렇게 하면 플러시가 더 자주 발생하며, 플러시할 때마다 내부 테이블에 새 파트가 생성됩니다.
* `async_insert=0`으로 비동기 삽입을 비활성화하십시오. 이 경우 요청마다 내부 테이블에 별도의 파트가 생성됩니다.

## PromQL로 쿼리

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

```bash theme={null}
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 엔드포인트를 사용하여 지정한 시간 범위에서 표현식을 평가합니다:

```bash theme={null}
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` 요청에 담아 전송합니다:

```bash theme={null}
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 엔드포인트를 사용하십시오:

```bash theme={null}
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`. duration은 초 단위 숫자로 변환되지 않고 단위를 유지하므로 `rate(x[5m])`은 `rate(x[5m])`으로 반환됩니다. 단일 단위의 정수로 표현할 수 없는 경우에는 필요한 단위를 조합하여 표시하므로 `rate(x[90s])`는 `rate(x[1m30s])`로 반환됩니다. 이 엔드포인트는 표현식을 평가하지 않으므로 `database` 및 `table` 매개변수가 필요하지 않습니다.

HTTP API, `promql` 방언 및 테이블 함수에서 지원하는 함수와 집계 연산자 목록은 [지원되는 PromQL 기능](https://clickhouse.com/docs/ko/reference/functions/table-functions/prometheusQueryRange.md#supported-promql-features)을 참조하십시오.

### Grafana

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

```yaml theme={null}
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`를 사용하십시오.

> [!NOTE]
>
> 쿼리 엔드포인트인 `/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`](https://clickhouse.com/docs/ko/reference/functions/table-functions/prometheusQuery) 및 [`prometheusQueryRange`](https://clickhouse.com/docs/ko/reference/functions/table-functions/prometheusQueryRange) 테이블 함수에서 동일한 PromQL 컨버터를 사용합니다.

`clickhouse-client`에서 PromQL을 직접 실행합니다:

```bash theme={null}
clickhouse-client \
  --dialect promql \
  --promql_database prometheus \
  --promql_table metrics \
  --query 'rate(http_requests_total[5m])'
```

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

```sql theme={null}
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`입니다. 각 메트릭 패밀리에서 가장 최근에 기록된 메타데이터 항목을 유지합니다. 대상 테이블에 여러 항목이 저장되어 있는 동안에만 패밀리당 여러 항목이 반환됩니다. 즉, 파트가 머지되기 전이거나 테이블이 항목을 보존하는 엔진으로 정의된 경우입니다.

```bash theme={null}
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 프로토콜](https://prometheus.io/docs/prometheus/latest/querying/remote_read_api/)을 지원합니다.

동일한 `TimeSeries` 테이블에서 읽도록 Prometheus 서버를 구성합니다:

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

## 기록 규칙(Recording rules)

ClickHouse는 Prometheus 규칙 파일을 평가하지 않습니다. 대신 [갱신 가능 구체화 뷰](https://clickhouse.com/docs/ko/reference/statements/create/view.md#refreshable-materialized-view)를 사용하면 [기록 규칙(recording rule)](https://prometheus.io/docs/prometheus/latest/configuration/recording_rules/)의 역할을 대신할 수 있습니다. 갱신 가능 구체화 뷰는 정해진 일정에 따라 PromQL 표현식을 평가하고 그 결과를 `TimeSeries` 테이블에 추가합니다. 다음 뷰는 `sum by (job) (rate(http_requests_total[5m]))`를 1분마다 `job:http_requests:rate5m`으로 기록합니다.

```sql theme={null}
CREATE MATERIALIZED VIEW prometheus.job_http_requests_rate5m
REFRESH EVERY 1 MINUTE APPEND TO prometheus.metrics (tags, samples) AS
SELECT
    mapUpdate(CAST(tags, 'Map(String, String)'), map('__name__', 'job:http_requests:rate5m')) AS tags,
    [(timestamp, value)] AS samples
FROM prometheusQuery(prometheus.metrics, 'sum by (job) (rate(http_requests_total[5m]))', toStartOfMinute(now()));
```

갱신할 때마다 현재 분의 시작 시점을 기준으로 표현식을 평가하고, `mapUpdate`로 메트릭 이름을 설정한 다음, 결과의 각 시계열마다 샘플(sample)을 하나씩 추가합니다. 같은 맵에 추가 레이블을 넣을 수도 있습니다(예: `map('__name__', 'job:http_requests:rate5m', 'team', 'web')`). 이렇게 기록된 시계열은 다른 메트릭과 동일한 방식으로 쿼리할 수 있습니다:

```bash theme={null}
curl --user default:<password> --get \
  "https://clickhouse.example.com:8443/prometheus/api/v1/query" \
  --data-urlencode "query=job:http_requests:rate5m" \
  --data-urlencode "database=prometheus" \
  --data-urlencode "table=metrics"
```

마지막 평가 시간과 오류는 [`system.view_refreshes`](https://clickhouse.com/docs/ko/reference/system-tables/view_refreshes)에서 확인할 수 있습니다.

뷰(view)는 다음과 같은 점에서 Prometheus 기록 규칙(recording rule)과 다릅니다.

* 평가 시점은 갱신이 실행되는 시점의 `now()`입니다. 뷰는 일정에 따른 갱신 외에도 다음과 같은 경우에 갱신됩니다. 생성 직후(`EMPTY`로 생성한 경우 제외), 갱신이 조정되지 않는 뷰의 서버 재시작 후(Replicated 또는 Shared 데이터베이스(database) 외부의 뷰나 `all_replicas = 1`로 설정된 뷰는 마지막 갱신을 기억하지 않음), 그리고 예정된 갱신을 놓친 뒤 `SYSTEM START VIEW`로 재개될 때입니다. 이러한 갱신으로 인해 예정된 갱신 사이에 샘플이 추가되지 않도록, 예시처럼 `now()`를 인터벌 단위로 내림하십시오. 다만 이렇게 하더라도 추가 갱신이 동일한 반올림된 타임스탬프에 두 번째 샘플을 기록할 수 있습니다. 5분 단위 규칙이라면 `toStartOfInterval(now(), INTERVAL 5 MINUTE)`를 사용하십시오.
* 누락된 평가는 나중에 보충되지 않습니다. 서버가 중단되었거나 뷰가 중지되었던 경우, 이후 뷰는 현재 인터벌만 평가하며 그 이전 인터벌은 빈 상태로 남습니다. 갱신에 걸리는 시간이 인터벌보다 긴 경우에도 마찬가지입니다.
* 결과에서 빠진 시계열에는 staleness 마커가 붙지 않습니다. 따라서 쿼리는 룩백 기간(기본값 5분) 동안 해당 시계열의 마지막 기록 값을 계속 반환합니다.
* 별도의 규칙 파일은 없으며, 각 규칙이 하나의 독립된 뷰입니다. 또한 규칙은 `/api/v1/rules`에 나열되지 않습니다.
