> ## Documentation Index > Fetch the complete documentation index at: https://private-7c7dfe99-trino-dialect.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > ClickHouse의 Prometheus HTTP API 지원: remote write, remote read, PromQL 쿼리, 서버 메트릭. # Prometheus 프로토콜 및 PromQL export const CloudNotSupportedBadge = () => { return
ClickHouse Cloud에서 지원되지 않음 ; };
## ClickHouse 서버 메트릭 노출
ClickHouse Cloud를 사용하는 경우 [Prometheus 통합](/ko/products/cloud/features/monitoring/prometheus)을 통해 Prometheus에 메트릭을 노출할 수 있습니다. Prometheus 서버가 ClickHouse 자체 메트릭을 스크레이프해야 하는 경우 전용 포트를 구성하십시오: ```xml theme={null} 9363 /metrics true true true true true true ``` 동일한 포트에서 더 확장된 핸들러를 구성하려면 `` 섹션을 사용할 수 있습니다. 이 섹션은 [``](/ko/concepts/features/interfaces/http)와 유사하지만 Prometheus 프로토콜에서 작동합니다: ```xml theme={null} 9363 /metrics expose_metrics true true true true true true production ``` 설정: | Name | Default | Description | | ---------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `port` | 없음 | ClickHouse 메트릭을 제공하는 포트입니다. | | `endpoint` | `/metrics` | 메트릭을 수집할 HTTP 엔드포인트입니다. `/`로 시작합니다. `` 섹션과 함께 사용하면 안 됩니다. | | `url` / `headers` / `method` | 없음 | 요청에 일치하는 핸들러를 찾는 데 사용하는 필터입니다. [``](/ko/concepts/features/interfaces/http) 섹션의 동일한 이름의 필드와 유사합니다. | | `info` | true | 서버 아이덴티티 레이블(`name`, `version`, `version_describe`, `version_major`, `version_minor`, `version_patch`)과 함께 `ClickHouse_Info` Gauge를 노출합니다. | | `metrics` | true | [`system.metrics`](/ko/reference/system-tables/metrics)의 메트릭을 노출합니다. | | `asynchronous_metrics` | true | [`system.asynchronous_metrics`](/ko/reference/system-tables/asynchronous_metrics)의 메트릭을 노출합니다. | | `events` | true | [`system.events`](/ko/reference/system-tables/events)의 메트릭을 노출합니다. | | `errors` | true | [`system.errors`](/ko/reference/system-tables/errors)의 오류 수를 노출합니다. | | `histograms` | true | [`system.histogram_metrics`](/ko/reference/system-tables/histogram_metrics)의 메트릭을 노출합니다. | | `dimensional_metrics` | true | [`system.dimensional_metrics`](/ko/reference/system-tables/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`)이 해당합니다. 엔드포인트가 실제로 노출하는 항목에 따라 달라지므로, 한 엔드포인트에서는 유효한 이름이 다른 엔드포인트에서는 거부될 수 있습니다. | 엔드포인트를 확인하십시오: ```bash theme={null} curl http://127.0.0.1:9363/metrics ```
## Prometheus HTTP API 및 PromQL
ClickHouse는 [`TimeSeries`](/ko/reference/engines/table-engines/integrations/time-series) 테이블을 통해 Prometheus HTTP API를 구현합니다. 하나의 핸들러가 remote write, remote read, 즉시 PromQL 쿼리 및 범위 PromQL 쿼리를 처리합니다.
### 사전 요구 사항
테이블을 생성하고 액세스하는 사용자에 대해 [`allow_experimental_time_series_table`](/ko/reference/settings/session-settings/allow-experimental#allow_experimental_time_series_table) 설정을 활성화하십시오: ```sql theme={null} SET allow_experimental_time_series_table = 1; ``` 데이터베이스와 `TimeSeries` 테이블을 생성합니다. ```sql theme={null} CREATE DATABASE prometheus; CREATE TABLE prometheus.metrics ENGINE = TimeSeries; ``` HTTP API 요청의 경우 API 사용자 profile에서 `allow_experimental_time_series_table`을 활성화하십시오.
### Prometheus API 구성
기본 ClickHouse HTTP 포트에 prefix 기반으로 라우팅되는 핸들러 하나를 구성합니다: ```xml theme={null} /prometheus/api/v1 prometheus_api_v1 ``` ``는 `/ping` 및 SQL 요청 같은 엔드포인트에 대한 기본 제공 핸들러를 유지합니다. 위의 prefix는 하나의 핸들러를 통해 이러한 엔드포인트를 노출합니다. | 엔드포인트 | 용도 | | -------------------------------- | ----------------------- | | `/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 쿼리 | 이 예시에서는 핸들러에서 `database`와 `table`을 생략합니다. 각 요청에는 `table` 쿼리 매개변수가 반드시 포함되어야 합니다. `database`를 지정하거나, `prometheus.metrics`와 같은 정규화된 테이블 이름을 사용하거나, 데이터베이스를 생략해 `default`를 사용할 수도 있습니다. 따라서 하나의 핸들러로 여러 `TimeSeries` 테이블을 처리할 수 있습니다. 모든 요청에 하나의 고정 테이블을 사용하려면 핸들러에서 이를 구성하십시오. ```xml theme={null} prometheus_api_v1 prometheus metrics
 ``` 핸들러에 구성된 테이블은 요청 매개변수로 재정의할 수 없습니다. 라우팅 및 핸들러 설정: | 이름 | 기본값 | 설명 | | ------------ | ---- | ---------------------------------------------------------------------------------------------------------------------- | | `url_prefix` | none | 구성된 접두사로 시작하는 모든 요청 경로와 일치하는 규칙 필터입니다. | | `table` | none | `TimeSeries` 테이블 이름입니다. 생략하면 요청에서 `table` 쿼리 매개변수를 제공해야 합니다. 구성된 이름에는 데이터베이스를 포함할 수 있습니다. | | `database` | none | 테이블이 포함된 데이터베이스입니다. 요청에서 쿼리 매개변수로 지정할 수 있습니다. 생략하면 ClickHouse는 정규화된 `table` 값에 지정된 데이터베이스를 사용하며, 없으면 `default`를 사용합니다. |
### 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: ``` Prometheus는 샘플을 `prometheus.metrics` 테이블로 전송합니다.
### PromQL로 쿼리
특정 시점에서 PromQL 표현식을 평가하려면 instant-query 엔드포인트를 사용하십시오: ```bash theme={null} curl --user default: --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: --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 기능](/ko/reference/functions/table-functions/prometheusQueryRange#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: GET customQueryParameters: database=prometheus&table=metrics secureJsonData: basicAuthPassword: ``` Grafana는 이 기준 URL 뒤에 `/api/v1/query` 또는 `/api/v1/query_range`를 추가하고, 각 요청에 `customQueryParameters`를 추가합니다. 쿼리 엔드포인트인 `/api/v1/query` 및 `/api/v1/query_range`만 구현되어 있습니다. Grafana Prometheus 데이터 소스에서 레이블 탐색, 템플릿 변수, 쿼리 빌더 자동 완성에 사용하는 메타데이터 엔드포인트(`/api/v1/series`, `/api/v1/labels`, `/api/v1/label//values`)는 구현되어 있지 않으므로 오류를 반환합니다. 쿼리 빌더 대신 코드 모드에서 PromQL 표현식을 작성하십시오.
#### SQL 진입점
ClickHouse는 HTTP API, `promql` 방언, [`prometheusQuery`](/ko/reference/functions/table-functions/prometheusQuery) 및 [`prometheusQueryRange`](/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() ); ```
### 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: ```