API 参考文档
组织范围的指标端点 (
GET /v1/organizations/{organizationId}/prometheus) 已弃用,建议改用自动服务发现。现有组织可以继续使用它;新创建的组织则改用发现端点。如果您需要访问此端点,请联系 ClickHouse 支持团队。
这些端点的完整请求和响应 schema 可在 Cloud API 参考文档中查看。
使用您的 ClickHouse Cloud API key 进行基本身份验证:
对于 ClickPipes,指标还会带有以下标签:
ClickHouse Cloud 提供了一个特殊指标
ClickHouse_ServiceInfo,它是一个值始终为 1 的 gauge。该指标除包含所有指标标签外,还包含以下标签:
用于获取指标的请求不会恢复已休眠的服务。如果服务处于
idle 状态,则只会返回 ClickHouse_ServiceInfo 指标。
对于 ClickPipes,也有一个类似的 ClickPipes_Info gauge 指标,除指标标签外,还包含以下标签:
配置 Prometheus
Prometheus 服务器会按照给定的时间间隔从已配置的目标采集指标。下面是一个示例配置,展示如何让 Prometheus 服务器使用 ClickHouse Cloud Prometheus 端点:honor_labels 设为 true,标签才能被正确填充。另请注意,在上述示例中,filtered_metrics 被设置为 true,但实际应根据用户偏好进行配置。如需抓取组织中的所有服务,请使用自动服务发现。
自动服务发现
发现端点会以 Prometheus HTTP 服务发现 (http_sd) 格式,为组织中的每个服务返回一个抓取目标。Prometheus 会在每次发现轮询时刷新目标列表,并抓取每个发现到的目标,因此新创建的服务会自动纳入其中,已删除的服务则会从目标列表中移除。仅包含您的 API key 有权查看的服务;正在删除或已删除的服务不会包含在内。
要使用此功能,请将 http_sd_configs Job 配置为指向发现端点:
basic_auth:http_sd_configs 下的块用于对发现轮询进行身份验证,抓取作业中的块则用于对各服务的指标抓取进行身份验证。与静态配置一样,请设置 honor_labels: true,以正确填充标签。
发现响应示例:
__meta_clickhouse_region、__meta_clickhouse_provider 和 __meta_clickhouse_tag_<key> 标签的形式,附带服务的区域、云服务提供商和标签信息。对于每个标签 (包括没有值的标签) ,__meta_clickhouse_tagpresent_<key> 均为 true。标签键中除字母、数字和下划线以外的字符都会被替换为 _。Prometheus 会在重新标记 (relabeling) 后丢弃 __meta_ 标签,因此请使用 relabel_configs 来过滤目标或保留这些标签:
filtered_metrics=true 抓取指标。若要发现抓取完整指标集的目标,请在服务发现 URL 中添加 ?filtered_metrics=false。完整端点规范请参阅 Cloud API 参考文档。
与 Grafana 集成主要有两种方式:
- 指标端点 – 这种方式的优势在于无需任何额外组件或基础设施。此方案仅适用于 Grafana Cloud,只需提供 ClickHouse Cloud Prometheus 端点 URL 和凭据。
- Grafana Alloy - Grafana Alloy 是 OpenTelemetry (OTel) Collector 的一种供应商中立发行版,用于替代 Grafana Agent。它可用作抓取器,可部署在您自己的基础设施中,并兼容任何 Prometheus 端点。
使用 指标端点 接入 Grafana Cloud
- 登录你的 Grafana Cloud 账户
- 选择 指标端点,添加新连接
- 将 Scrape URL 配置为指向 Prometheus 端点,并使用基本身份验证通过 API key/secret 配置连接
- 测试连接,确保可以成功连通

配置完成后,你应该会在下拉列表中看到这些指标,可选择它们来配置仪表盘:


通过 Alloy 使用 Grafana Cloud
如果你使用的是 Grafana Cloud,可以在 Grafana 中打开 Alloy 菜单,并按照屏幕上的说明安装 Alloy:
这样会将 Alloy 配置为包含一个
prometheus.remote_write 组件,用于通过身份验证令牌将数据发送到 Grafana Cloud 端点。之后,用户只需修改 Alloy 配置 (在 Linux 上位于 /etc/alloy/config.alloy) ,加入一个用于抓取 ClickHouse Cloud Prometheus 端点的抓取器即可。
下面给出了一个 Alloy 配置示例,其中包含一个用于从 ClickHouse Cloud 端点抓取指标的 prometheus.scrape 组件,以及自动配置的 prometheus.remote_write 组件。请注意,basic_auth 配置组件分别将我们的 Cloud API key ID 和 secret 用作用户名和密码。
honor_labels 配置参数设为 true,instance 标签才能被正确填充。
使用 Alloy 的 Grafana 自管理版本
使用 Grafana 自管理版本的用户可在这里找到安装 Alloy agent 的说明。我们假定用户已将 Alloy 配置为把 Prometheus 指标发送到所需的目标端。下面的prometheus.scrape 组件会让 Alloy 抓取 ClickHouse Cloud 端点。我们假定 prometheus.remote_write 会接收抓取到的指标。如果未配置该项,请将 forward_to key 调整为目标端。

请注意,必须将
honor_labels 配置参数设为 true,标签才能正确填充。
与 Datadog 集成
你可以使用 Datadog Agent 和 OpenMetrics 集成,从 ClickHouse Cloud 端点收集指标。下面是该 agent 和集成的一个简单配置示例。不过请注意,你可能只需要选择自己最关心的那些指标。下面这个兜底示例会导出成千上万个“指标-实例”组合,Datadog 会将其视为自定义指标。
相关页面
- 监控概览 — 比较 ClickHouse Cloud 的所有监控方式
- Cloud Console 监控 — 内置仪表盘,无需外部工具
- 社区与合作伙伴集成 — Datadog agent 集成和社区解决方案
- 查询系统表 — 通过 SQL 直接访问系统指标
- ClickHouse Managed Postgres Prometheus 端点 — 从 ClickHouse Managed Postgres 服务抓取指标