使用 Prometheus 增强 ClickHouse Cloud 监控

今天，我们很高兴地宣布 ClickHouse Cloud 现在支持使用 Prometheus 进行增强监控。此功能已全面推出，使云实例的监控比以往更加容易，满足了用户的使用习惯，并允许他们使用首选工具进行可观测性分析。

这个广受欢迎的功能请求解决了许多组织在采用云服务时的一个需求——独立于 ClickHouse 本身监控其正常运行时间和性能的能力。

希望试用此功能的用户应访问我们的文档。我们在文档中为希望学习如何与 Datadog 和 Grafana 集成的用户提供了简单的示例。

如果您有兴趣了解有关使用 Prometheus API 相对于现有方法的优势的更多信息，以及有效实施它的一些挑战，请继续阅读。

对于组织而言，集中监控他们所依赖的云服务的能力至关重要。从历史上看，希望监控 ClickHouse Cloud 的用户会依赖于查询系统表来获取他们需要的指标。这对于许多基础设施工程师来说是一个障碍，他们需要使用 SQL 从系统表中探索和提取指标。即使精通 SQL，在许多情况下，在 ClickHouse 中构建正确的查询并找到合适的系统表也可能非常耗时。这还不包括为代理配置适当的访问控制和权限的需求。

虽然诸如 Datadog 之类的代理可以用于监控 ClickHouse Cloud，但这些通常带有局限性——特别是在 Datadog 的情况下，我们的云代理层的路由意味着相同的实例不会在多个调用中被查询，这使得后续指标难以解释。可以通过一些仔细的配置和使用 clusterAllReplicas 函数来克服这一点，但这些集成也会遇到一个常见问题：它们通过 SELECT 查询持续轮询指标意味着实例永远不会空闲。

鉴于我们的用户依赖 ClickHouse Cloud 实例在不使用时能够空闲，从而最大限度地降低计算成本，因此这种行为（加上监控使用情况）是非常不受欢迎的，并且是许多用户的障碍。

最后，Prometheus 格式现在几乎已成为这种数据形式的标准，并受到 Grafana 和 Datadog 等流行工具的支持，具有开箱即用的集成。

一个简单的端点，可以为实例提供 Prometheus 指标，而不会阻止未使用的实例空闲或唤醒，这显然是首选解决方案。

因此，任何端点都有一些相当简单的要求

• 以 Prometheus 格式交付指标 - 与现有的常用监控代理兼容。
• 不唤醒空闲实例 - 这些实例应仅返回一条简单的消息，指示其状态。
• 不阻止实例空闲 - 在确定实例是否应空闲时，不应考虑对此端点的请求。

虽然我们本可以可能通过为每个 ClickHouse 实例配置来交付此功能，例如，使用现有的配置 ClickHouse 中的 Prometheus 端点的能力，但这对于我们的用户来说是一个不完美的解决方案。确保当实例空闲时这些请求不被转发在技术上实现起来并不优雅。此外，这意味着用户需要为每个实例创建一个具有适当角色和权限的用户，并将这些凭据分发给他们的代理。对于许多组织来说，这将代表安全风险，并且显得不必要地复杂。

此端点的逻辑位置是我们的现有 Cloud API。此 API 已经允许用户创建和配置实例。此外，它还提供了组织级别的访问控制，用户只需点击几下即可创建（和撤销！）API 密钥。通过 Cloud API 公开此端点，我们可以最大限度地减少安全攻击面，并提供一个易于使用的端点，无需了解 ClickHouse 或 SQL！

因此，我们提供了一个简单的 Cloud API 端点，用户可以在其中安全地请求特定组织和实例的 Prometheus 指标。

API 密钥是组织级别的，可以定义为“开发者”或“管理员”。开发者访问权限足以满足 Prometheus 端点的需求，确保泄露的凭据不会允许创建或中断服务。

通过 Cloud API 实施端点的决定意味着实施保持简单。Cloud API 已经知道每个实例的状态，允许它不向空闲实例发出请求。假设实例正在运行，则使用具有有限权限范围的特定用户发出请求。在考虑是否使实例空闲时，数据平面随后会忽略来自此用户的请求。

这仅剩下要制定用于系统表的适当查询。鉴于我们期望用户有兴趣收集的指标分布在许多系统表中，因此生成的查询非常复杂，并且具有明显的开销。为了避免在每次对端点的请求时都发出此查询，我们利用了最近发布的 ClickHouse 功能：可刷新的物化视图。

此视图定期（目前每分钟）执行查询，将结果发送到目标表 system.custom_metrics，并原子性地更新其当前行。此目标表仅包含结果集，使用 Memory 引擎，并且可以被 Cloud API 有效地查询。对于好奇的读者，我们在下面展示了表格和视图的示例

CREATE TABLE system.custom_metrics
(
	`name` String,
	`value` Float64,
	`help` String,
	`labels` Map(String, String),
	`type` String
)
ENGINE = Memory

CREATE MATERIALIZED VIEW system.custom_metrics_refresher
REFRESH EVERY 1 MINUTE TO system.custom_metrics
(
	`name` String,
	`value` Nullable(Float64),
	`help` String,
	`labels` Map(String, String),
	`type` String
)
AS SELECT
	concat('ClickHouse_', event) AS name,
	toFloat64(value) AS value,
	description AS help,
	map('hostname', hostName(), 'table', 'system.events') AS labels,
	'counter' AS type
FROM system.events
UNION ALL
//other metrics

通过这种方法，物化视图的刷新率控制查询的执行频率，确保默认情况下最多每 60 秒运行一次。这也防止了恶意或配置错误的代理对服务施加查询压力并占用计算资源。

要使用该端点，您首先需要在 ClickHouse Cloud 中创建一个 API 密钥。此过程如下所示

有了可用的端点，查询端点需要我们获取组织和实例 ID。

有了这些，您可以发出一个简单的 HTTP 请求

export KEY_SECRET=<key_secret>
export KEY_ID=<key_id>
export ORG_ID=<org id>
export INSTANCE_ID=<instance id>
curl --silent --user $KEY_ID:$KEY_SECRET https://api.control-plane.clickhouse-staging.com/v1/organizations/$ORG_ID/services/$INSTANCE_ID/prometheus 

…
# HELP ClickHouse_ServiceInfo Information about service, including cluster status and ClickHouse version
# TYPE ClickHouse_ServiceInfo untyped
ClickHouse_ServiceInfo{clickhouse_org="c2ba4799-a76e-456f-a71a-b021b1fafe60",clickhouse_service="12f4a114-9746-4a75-9ce5-161ec3a73c4c",clickhouse_service_name="test service",clickhouse_cluster_status="running",clickhouse_version="24.5",scrape="full"} 1

# HELP ClickHouseProfileEvents_Query Number of queries to be interpreted and potentially executed. Does not include queries that failed to parse or were rejected due to AST size limits, quota limits or limits on the number of simultaneously running queries. May include internal queries initiated by ClickHouse itself. Does not count subqueries.
# TYPE ClickHouseProfileEvents_Query counter
ClickHouseProfileEvents_Query{clickhouse_org="c2ba4799-a76e-456f-a71a-b021b1fafe60",clickhouse_service="12f4a114-9746-4a75-9ce5-161ec3a73c4c",clickhouse_service_name="test service",hostname="c-cream-ma-20-server-3vd2ehh-0",instance="c-cream-ma-20-server-3vd2ehh-0",table="system.events"} 6

# HELP ClickHouseProfileEvents_QueriesWithSubqueries Count queries with all subqueries
# TYPE ClickHouseProfileEvents_QueriesWithSubqueries counter
ClickHouseProfileEvents_QueriesWithSubqueries{clickhouse_org="c2ba4799-a76e-456f-a71a-b021b1fafe60",clickhouse_service="12f4a114-9746-4a75-9ce5-161ec3a73c4c",clickhouse_service_name="test service",hostname="c-cream-ma-20-server-3vd2ehh-0",instance="c-cream-ma-20-server-3vd2ehh-0",table="system.events"} 230

# HELP ClickHouseProfileEvents_SelectQueriesWithSubqueries Count SELECT queries with all subqueries
# TYPE ClickHouseProfileEvents_SelectQueriesWithSubqueries counter
ClickHouseProfileEvents_SelectQueriesWithSubqueries{clickhouse_org="c2ba4799-a76e-456f-a71a-b021b1fafe60",clickhouse_service="12f4a114-9746-4a75-9ce5-161ec3a73c4c",clickhouse_service_name="test service",hostname="c-cream-ma-20-server-3vd2ehh-0",instance="c-cream-ma-20-server-3vd2ehh-0",table="system.events"} 224

# HELP ClickHouseProfileEvents_FileOpen Number of files opened.
# TYPE ClickHouseProfileEvents_FileOpen counter
ClickHouseProfileEvents_FileOpen{clickhouse_org="c2ba4799-a76e-456f-a71a-b021b1fafe60",clickhouse_service="12f4a114-9746-4a75-9ce5-161ec3a73c4c",clickhouse_service_name="test service",hostname="c-cream-ma-20-server-3vd2ehh-0",instance="c-cream-ma-20-server-3vd2ehh-0",table="system.events"} 4157

# HELP ClickHouseProfileEvents_Seek Number of times the 'lseek' function was called.
# TYPE ClickHouseProfileEvents_Seek counter
ClickHouseProfileEvents_Seek{clickhouse_org="c2ba4799-a76e-456f-a71a-b021b1fafe60",clickhouse_service="12f4a114-9746-4a75-9ce5-161ec3a73c4c",clickhouse_service_name="test service",hostname="c-cream-ma-20-server-3vd2ehh-0",instance="c-cream-ma-20-server-3vd2ehh-0",table="system.events"} 1840
…

ClickHouse Cloud Prometheus 端点公开与原生 ClickHouse Prometheus 端点相同的指标集。以上表示收集的指标的一小部分示例——我们目前公开了 1000 多个指标，我们发现这些指标对于监控 ClickHouse 非常有用。您可以在 ClickHouse 文档中查看公开了哪些指标。

如果您需要监控 ClickHouse Cloud，但发现缺少某些指标，请告诉我们！

如果实例空闲，则响应会指示如此

# HELP ClickHouse_ServiceInfo Information about service, including cluster status and ClickHouse version
# TYPE ClickHouse_ServiceInfo untyped
ClickHouse_ServiceInfo{clickhouse_org="c2ba4799-a76e-456f-a71a-b021b1fafe60",clickhouse_service="12f4a114-9746-4a75-9ce5-161ec3a73c4c",clickhouse_service_name="test service",clickhouse_cluster_status="idle",clickhouse_version="24.5",scrape="full"}

要安装 Prometheus，您可以按照官方 Prometheus 指南。

下面是如何为 ClickHouse Cloud 配置 Prometheus 抓取作业的简单示例。您将需要上面步骤中的 <ORG_ID>、<INSTANCE_ID>、<KEY_ID> 和 <KEY_SECRET>。请注意 honor_labels 配置参数。需要在 true 中设置它，以便正确填充实例标签。

global:
  scrape_interval: 15s
scrape_configs:
  - job_name: "prometheus"
    static_configs:
    - targets: ["localhost:9090"]
  - job_name: "clickhouse"
    static_configs:
      - targets: ["api.clickhouse.cloud"]
    scheme: https
    metrics_path: "/v1/organizations/<ORG_ID>/services/<INSTANCE_ID>/prometheus"
    basic_auth:
      username: <KEY_ID>
      password: <KEY_SECRET>
    honor_labels: true

您可以使用 Datadog Agent 和 OpenMetrics 集成从 ClickHouse Cloud 端点收集指标。以下是此代理的简单配置示例。

init_config:

instances:
   - openmetrics_endpoint: 'https://api.control-plane.clickhouse.com/v1/organizations/97a33bdb-4db3-4067-b14f-ce40f621aae1/services/f7fefb6e-41a5-48fa-9f5f-deaaa442d5d8/prometheus'
     namespace: 'clickhouse'
     metrics:
         - '^ClickHouse_.*'
     username: username
     password: password

我们在下面展示了使用此代理收集的指标监控 ClickHouse 的大型插入工作负载

您可以查阅我们的文档，以获取有关与 Datadog 和 Grafana 集成的完整指南。

Prometheus 集成的发布应该允许用户使用他们最喜欢的可观测性工具来监控 ClickHouse Cloud。指标集代表了我们发现对监控 ClickHouse 有用的指标。我们预计此集合会扩展，并且我们鼓励用户突出显示他们认为缺少的任何指标或其他集成，如果他们有扩展和自定义这些指标的需求！