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>

设置：

名称 默认值 描述
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。一个处理程序可处理 远程写入、远程读取、即时 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 查询
/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 无 用于匹配所有以配置前缀开头的请求路径的规则过滤器。
table 无 TimeSeries 表的名称。未指定时，请求必须提供 table 查询参数。配置的名称可以包含数据库名称。
database 无 包含该表的数据库。请求可通过查询参数提供该值。未指定时，ClickHouse 会使用完全限定的 table 值中的数据库，或回退到 default。

通过 远程写入 摄取指标

ClickHouse 支持 Prometheus 远程写入 协议。配置 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 表。

要将多个并发远程写入请求中的数据合并为更少的 parts，请在 URL 中添加 async_insert 设置 (或在 user profile 中启用该设置) ，以启用异步插入：

remote_write:
  - url: https://clickhouse.example.com:8443/prometheus/api/v1/write?database=prometheus&table=metrics&async_insert=1

ClickHouse 仅在数据已刷新到 TimeSeries 表的所有内部表后，才会确认异步远程写入请求，不受 wait_for_async_insert 设置影响：远程写入协议将已确认的写入视为持久化写入。如果刷新失败，请求会返回错误，Prometheus 将重试。

使用 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。

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 限制返回的指标族数量。负值表示不限制；零表示不返回任何指标族。
limit_per_metric 限制每个指标族返回的元数据对象数量。零和负值表示不限制。

默认的 Metrics 目标表是按指标族名称排序的 ReplacingMergeTree：它会保留每个指标族最近写入的元数据条目。只有在目标表仍保留这些条目时，才会返回每个指标族的多个条目——例如在其 parts 合并之前，或该表使用会保留这些条目的引擎时。

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"

通过远程读取读取指标

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