> ## 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：远程写入、远程读取、PromQL 查询和服务器指标。

# Prometheus 协议和 PromQL

export const CloudNotSupportedBadge = () => {
  return <a href="https://clickhouse.com/docs/products/cloud/guides/cloud-compatibility#list-of-unsupported-features" className="cloudNotSupportedBadge">
            <div className="cloudNotSupportedIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.5" d="M6.33366 12.6666L12.3739 12.6667C13.6593 12.6667 14.7073 11.6187 14.7073 10.3334C14.7073 9.04804 13.6593 8.00003 12.3739 8.00003C12.3739 8.00003 12.3337 7.66659 12.0003 7.33325M10.667 5.33322C8.00033 2.33325 4.45395 4.78537 4.14195 6.68203C2.55728 6.7627 1.29395 8.06203 1.29395 9.6667C1.29395 11.3234 2.66699 12.6666 4.00033 12.6666" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.5" d="M2.66699 14L12.0003 4.66663" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>

        </div>
            ClickHouse Cloud 不支持此功能
        </a>;
};

<div id="expose">
  ## 暴露 ClickHouse 服务器指标
</div>

<Note>
  如果你使用的是 ClickHouse Cloud，可以通过 [Prometheus 集成](/zh/products/cloud/features/monitoring/prometheus) 向 Prometheus 暴露指标。
</Note>

当 Prometheus 服务器需要抓取 ClickHouse 自身指标时，请配置专用端口：

```xml theme={null}
<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>`](/zh/concepts/features/interfaces/http) 类似，但适用于 Prometheus 协议：

```xml theme={null}
<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>`](/zh/concepts/features/interfaces/http) 部分中的同名字段。                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `info`                       | true       | 导出带有服务器身份标记 (`name`、`version`、`version_describe`、`version_major`、`version_minor`、`version_patch`) 的 `ClickHouse_Info` Gauge。                                                                                                                                                                                                                                                                                                                                                                                  |
| `metrics`                    | true       | 导出 [`system.metrics`](/zh/reference/system-tables/metrics) 中的指标。                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `asynchronous_metrics`       | true       | 导出 [`system.asynchronous_metrics`](/zh/reference/system-tables/asynchronous_metrics) 中的指标。                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `events`                     | true       | 导出 [`system.events`](/zh/reference/system-tables/events) 中的指标。                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `errors`                     | true       | 导出 [`system.errors`](/zh/reference/system-tables/errors) 中的错误计数。                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `histograms`                 | true       | 导出 [`system.histogram_metrics`](/zh/reference/system-tables/histogram_metrics) 中的指标。                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `dimensional_metrics`        | true       | 导出 [`system.dimensional_metrics`](/zh/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
```

<CloudNotSupportedBadge />

<div id="prometheus-http-api-and-promql">
  ## Prometheus HTTP API 和 PromQL
</div>

ClickHouse 基于 [`TimeSeries`](/zh/reference/engines/table-engines/integrations/time-series) 表实现 Prometheus HTTP API。一个处理程序可处理 远程写入、远程读取、即时 PromQL 查询和范围 PromQL 查询。

<div id="prerequisites">
  ### 前置条件
</div>

为创建和访问该表的用户启用 [`allow_experimental_time_series_table`](/zh/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`。

<div id="configure-prometheus-api">
  ### 配置 Prometheus API
</div>

在主 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 远程写入 |
| `/prometheus/api/v1/read`        | Prometheus 远程读取 |
| `/prometheus/api/v1/query`       | 即时 PromQL 查询    |
| `/prometheus/api/v1/query_range` | 范围 PromQL 查询    |

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

若要让所有请求使用同一个固定表，请在处理程序中进行配置：

```xml theme={null}
<handler>
    <type>prometheus_api_v1</type>
    <database>prometheus</database>
    <table>metrics</table>
</handler>
```

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

路由和 处理程序 设置：

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

<div id="remote-write">
  ### 通过 远程写入 摄取指标
</div>

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

<div id="promql-query-support">
  ### 使用 PromQL 查询
</div>

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

```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"
```

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

```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"
```

有关 HTTP API、`promql` 方言及表函数支持的函数和聚合运算符列表，请参阅[支持的 PromQL 功能](/zh/reference/functions/table-functions/prometheusQueryRange#supported-promql-features)。

<div id="grafana">
  #### Grafana
</div>

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

```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: <password>
```

Grafana 会将 `/api/v1/query` 或 `/api/v1/query_range` 追加到此基础 URL，并在每个请求中添加 `customQueryParameters`。

<Note>
  目前仅实现了查询端点 `/api/v1/query` 和 `/api/v1/query_range`。Grafana Prometheus 数据源用于浏览标记、模板变量和查询构建器自动补全的元数据端点 (`/api/v1/series`、`/api/v1/labels`、`/api/v1/label/<name>/values`) 尚未实现，调用时会返回错误。请使用代码模式编写 PromQL 表达式，而不要使用查询构建器。
</Note>

<div id="sql-entry-points">
  #### SQL 入口
</div>

ClickHouse 的 HTTP API、`promql` 方言以及 [`prometheusQuery`](/zh/reference/functions/table-functions/prometheusQuery) 和 [`prometheusQueryRange`](/zh/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()
);
```

<div id="remote-read">
  ### 通过远程读取读取指标
</div>

ClickHouse 在 `/prometheus/api/v1/read` 提供对 [Prometheus 远程读取协议](https://prometheus.io/docs/prometheus/latest/querying/remote_read_api/)的支持。

配置 Prometheus 服务器从同一个 `TimeSeries` 表中读取数据：

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