Prometheus HTTP API 和 PromQL

ClickHouse 基于 TimeSeries 表实现 Prometheus HTTP API。一个处理程序可处理远程写入、远程读取、即时 PromQL 查询和范围 PromQL 查询。若要暴露 ClickHouse 自身的指标以供 Prometheus 服务器抓取，请参阅 Prometheus 指标端点。

前置条件

ClickHouse Cloud 与自管理 ClickHouse 的设置步骤有所不同。请参照与你的部署方式相对应的章节进行操作。

ClickHouse Cloud

ClickHouse Cloud 中的 PromQL 支持目前处于私有预览阶段。参与私有预览的服务已配置好 enable_time_series_table 设置以及 Prometheus API 端点。其他 ClickHouse Cloud 服务不具备该配置，你也无法自行在这类服务上启用该功能。后续章节中的 SET enable_time_series_table 语句和 http_handlers 配置仅适用于自管理部署。

如果你的服务参与了私有预览，请直接跳至创建 TimeSeries 表。该服务会提供端点表中列出的端点路径。

自管理：启用 TimeSeries 设置

为创建和访问该表的用户启用 enable_time_series_table 设置：

SET enable_time_series_table = 1;

对于 HTTP API 请求，请在 API 用户的 profile 中启用 enable_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/format_query`	PromQL 表达式格式化
`/prometheus/api/v1/series`	序列元数据
`/prometheus/api/v1/metadata`	指标家族元数据

该示例未在处理程序中指定 database 和 table。每个请求都必须提供 table 查询参数 (/format_query 除外，它只解析给定的 PromQL 表达式，不需要表) 。还可以提供 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`。

创建 TimeSeries 表

创建数据库和 TimeSeries 表：

CREATE DATABASE prometheus;
CREATE TABLE prometheus.metrics ENGINE = TimeSeries;

通过远程写入摄取指标

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，ClickHouse 会使用异步插入。该功能默认启用，可通过 URL (或 user profile) 中的 async_insert 设置开启或关闭。 ClickHouse 仅在数据已刷写到 TimeSeries 表的所有内部表后，才会确认异步远程写入请求，不受 wait_for_async_insert 设置影响：远程写入协议将已确认的写入视为持久化写入。如果刷写失败，请求会返回错误，Prometheus 将重试。由于每个请求都要等待其刷写完成，异步插入会限制单个发送方的写入速度。Prometheus 对每个远程写入分片一次只发送一个请求。当多个分片同时发送时，自适应刷写超时会逐步增大至 async_insert_busy_timeout_max_ms，除非待处理请求的数据量先达到 async_insert_max_data_size。请求会一直等到其所在批次被刷写，而刷写最晚会在该批次开始后经过上述时长时发生。因此在持续负载下，每个分片的写入速率约为 samples per request / async_insert_busy_timeout_max_ms，其中 Prometheus 默认每个请求最多发送 2,000 个样本。要提高该速率，可以：

在 remote_write 的 queue_config 中调高 max_shards (默认为 50) 或 max_samples_per_send。Prometheus 在写入滞后时会自动增加分片，最多增至 max_shards。
在 URL 或 user profile 中调低 async_insert_busy_timeout_max_ms，例如 &async_insert_busy_timeout_max_ms=50。这样刷写会更加频繁，而每次刷写都会在内部表中创建新的 parts。
通过 async_insert=0 禁用异步插入。这样每个请求都会在内部表中创建各自的 parts。

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

查询端点也接受以表单请求正文形式传递的参数。若不使用 --get，curl 会通过 POST 以 application/x-www-form-urlencoded 发送这些参数：

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 表达式，而不对其求值：

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"

该表达式会从解析后的查询中序列化返回，其中空白已归一化、注释已移除、冗余括号已去除，时长则以解析器接受的单位表示：sum by (job) (http_requests_total{code="200"}) / 2。时长会保留单位，而不会转换为秒数，因此 rate(x[5m]) 返回为 rate(x[5m])；如果时长无法用单一单位的整数值表示，则会组合使用所需的单位，因此 rate(x[90s]) 返回为 rate(x[1m30s])。该端点不会对表达式求值，因此不需要 database 和 table 参数。有关 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: POST
      customQueryParameters: database=prometheus&table=metrics
    secureJsonData:
      basicAuthPassword: <password>

Grafana 会将 /api/v1/query 或 /api/v1/query_range 追加到此基础 URL，并在每个请求中添加 customQueryParameters。在 httpMethod: POST 下，Grafana 会将查询参数放在请求正文中发送。ClickHouse 会同时读取请求正文和 URL 查询字符串，因此 customQueryParameters 仍然生效。对于较长的 PromQL 表达式，请使用 POST，因为 URL 存在长度限制。

目前仅实现了查询端点 /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> 可选地使用 Prometheus 的 U__... 转义方式来表示包含 [a-zA-Z0-9_] 之外字符的标记名称。这些端点涵盖了 Grafana Prometheus 数据源用于浏览标记、模板变量和查询构建器自动补全的功能。

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>

记录规则

ClickHouse 不会评估 Prometheus 规则文件。可刷新materialized view 可以起到记录规则的作用：它按调度计划计算 PromQL 表达式，并将结果追加到 TimeSeries 表中。以下视图每分钟将 sum by (job) (rate(http_requests_total[5m])) 记录为 job:http_requests:rate5m：

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 设置指标名称，并为结果中的每个数据系列追加一个样本。还可以在同一个 Map 中添加额外的标记，例如 map('__name__', 'job:http_requests:rate5m', 'team', 'web')。记录下来的数据系列可以像其他指标一样查询：

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 中查看。视图与 Prometheus 记录规则存在以下差异：

求值时间为刷新运行时的 now()。除按调度计划刷新外，视图还会在以下情况下刷新：创建后立即刷新 (除非创建时指定了 EMPTY) ；若刷新并非协调式，则在服务器重启后刷新 (位于 Replicated 或 Shared 数据库之外的视图，或设置了 all_replicas = 1 的视图，不会记录其上次刷新) ；以及错过某次计划刷新后，通过 SYSTEM START VIEW 恢复时刷新。请参照示例将 now() 向下取整到时间间隔，以免这些刷新在两次计划刷新之间插入额外的样本。即便如此，额外的刷新仍可能在同一个取整后的时间戳上写入第二个样本。对于五分钟的规则，请使用 toStartOfInterval(now(), INTERVAL 5 MINUTE)。
错过的求值不会补算。服务器宕机或视图停止后，视图只会对当前时间间隔求值，之前的时间间隔将保持为空。若某次刷新耗时超过时间间隔，也会出现同样的情况。
从结果中消失的数据系列不会被打上陈旧标记，因此在回溯周期 (默认 5 分钟) 内，查询仍会返回其最后记录的值。
没有规则文件：每条规则都是一个独立的视图，且不会出现在 /api/v1/rules 的列表中。

基础知识

ClickHouse 基本概念

最佳实践

前置条件

ClickHouse Cloud

自管理：启用 TimeSeries 设置

自管理：配置 Prometheus API 端点

创建 TimeSeries 表

通过远程写入摄取指标

使用 PromQL 查询

Grafana

SQL 入口

查询指标元数据

通过远程读取读取指标

记录规则

​前置条件

​ClickHouse Cloud

​自管理：启用 TimeSeries 设置

​自管理：配置 Prometheus API 端点

​创建 TimeSeries 表

​通过 远程写入 摄取指标

​使用 PromQL 查询

​Grafana

​SQL 入口

​查询指标元数据

​通过远程读取读取指标

​记录规则

前置条件

ClickHouse Cloud

自管理：启用 TimeSeries 设置

自管理：配置 Prometheus API 端点

创建 TimeSeries 表

通过远程写入摄取指标

使用 PromQL 查询

Grafana

SQL 入口

查询指标元数据

通过远程读取读取指标

记录规则