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>

设置：

名称	默认值	描述
`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。一个处理程序可处理远程写入、远程读取、即时 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 远程写入
`/prometheus/api/v1/read`	Prometheus 远程读取
`/prometheus/api/v1/query`	即时 PromQL 查询
`/prometheus/api/v1/query_range`	范围 PromQL 查询

该示例未在处理程序中指定 database 和 table。每个请求都必须提供 table 查询参数。还可以提供 database、使用如 prometheus.metrics 这样的限定表名，或者省略数据库以使用 default。这样，一个处理程序即可为多个 TimeSeries 表提供服务。若要让所有请求使用同一个固定表，请在处理程序中进行配置：

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

在处理程序中配置的表不能被请求参数覆盖。路由和处理程序设置：

名称	默认值	描述
`url_prefix`	无	用于匹配所有以配置前缀开头的请求路径的规则过滤器。
`table`	无	`TimeSeries` 表的名称。未指定时，请求必须提供 `table` 查询参数。配置的名称可以包含数据库名称。
`database`	无	包含该表的数据库。请求可通过查询参数提供该值。未指定时，ClickHouse 会使用完全限定的 `table` 值中的数据库，或回退到 `default`。

通过远程写入摄取指标

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 表。

使用 PromQL 查询

使用即时查询端点，在某一时间点评估 PromQL 表达式：

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"

使用范围查询端点计算指定时间范围内的表达式：

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

配置 Prometheus 数据源时，基础 URL 应以 /api/v1 之前的部分结尾：

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 会将 /api/v1/query 或 /api/v1/query_range 追加到此基础 URL，并在每个请求中添加 customQueryParameters。

目前仅实现了查询端点 /api/v1/query 和 /api/v1/query_range。Grafana Prometheus 数据源用于浏览标记、模板变量和查询构建器自动补全的元数据端点 (/api/v1/series、/api/v1/labels、/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()
);

通过远程读取读取指标

ClickHouse 在 /prometheus/api/v1/read 提供对 Prometheus 远程读取协议的支持。配置 Prometheus 服务器从同一个 TimeSeries 表中读取数据：

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

基础知识

ClickHouse 概念

最佳实践

暴露 ClickHouse 服务器指标

Prometheus HTTP API 和 PromQL

前置条件

配置 Prometheus API

通过远程写入摄取指标

使用 PromQL 查询

Grafana

SQL 入口

通过远程读取读取指标

​暴露 ClickHouse 服务器指标

​Prometheus HTTP API 和 PromQL

​前置条件

​配置 Prometheus API

​通过 远程写入 摄取指标

​使用 PromQL 查询

​Grafana

​SQL 入口

​通过远程读取读取指标

暴露 ClickHouse 服务器指标

Prometheus HTTP API 和 PromQL

前置条件

配置 Prometheus API

通过远程写入摄取指标

使用 PromQL 查询

Grafana

SQL 入口

通过远程读取读取指标