clickhouse-managed-postgres-rca

ClickHouse Managed Postgres 根因分析

何时使用

每当用户报告 ClickHouse 托管的 Postgres 实例出现速度缓慢、CPU 使用率高、吞吐量低、缓存抖动或任何无法解释的问题时，都应触发。

你可以访问的内容

https://api.clickhouse.cloud 上的两个 API（使用 ClickHouse Cloud API 密钥/密钥对进行 HTTP Basic 身份验证）：

• Prometheus 指标 — Prometheus 标签下的操作 postgresInstancePrometheusGet。返回 Prometheus exposition 格式。提供一个 Postgres 服务的系统指标和工作负载指标。
• 慢查询模式 — Postgres 标签下的操作 slowQueryPatternsGetList。返回规范化查询模式的每个摘要的延迟、IO 和调用统计信息。Beta。

两个端点都需要将 organizationId 和 serviceId 作为路径参数。用户必须提供这两个参数，以及 API 密钥/密钥对。

你无法访问的内容

• 查询计划 / EXPLAIN 输出。
• 每个表的扫描类型计数器（seq_scan / idx_scan）。
• 自动清理或上次 ANALYZE 的时间戳。

根据 IO 和时间信号进行推断，而不是根据计划树。

工作流

按顺序执行六个步骤。不要跳步。

步骤 2 和 3 只共享身份验证信息，没有数据依赖关系。并行运行（在后台执行 curl，使用 & + wait），将总耗时从顺序执行的约 2 秒缩短至约 1 秒。

1. 查明当前 API 的具体形态

这些端点处于 Beta 阶段——路径、参数和 JSON 字段名称都可能变化。按照 rules/openapi-discovery.md 执行以下操作：

1. 从 https://api.clickhouse.cloud/v1 获取 OpenAPI 规范。
2. 按 operationId 查找两个操作：
   • postgresInstancePrometheusGet（Prometheus 标签）
   • slowQueryPatternsGetList（Postgres 标签）
3. 确认它们的路径模板、必需查询参数，以及（对于慢查询端点）响应架构。
4. 根据架构中的属性描述，构建会话范围内的角色映射：{ semantic role → actual field name }。

在之后的每个请求和引用中使用确认过的名称。不要凭记忆硬编码字段名称。

2. 抓取一次 Prometheus 数据，获取系统指标

按照 rules/prometheus-scrape.md 操作。**只抓取一次，不等待。**你需要的是不需要计算差值的指标（当前值）：CacheHitRatio、ActiveConnections、MemoryUsedPercent、FilesystemUsedPercent。

对于本应能装入缓存的工作负载，CacheHitRatio 明显低于约 95% 本身就是有效信号。ActiveConnections 持续攀升并接近连接池上限本身也是有效信号。这些指标不需要变化率。

第二次抓取以计算计数器差值是可选的，仅在步骤 4 的分诊指向写入拥塞时使用（此时死锁和回滚的速率很重要，而慢查询模式 API 无法替代这些信息）。对于读路径场景（最常见的根因分析类型），单次抓取就足够了。

3. 获取排名靠前的慢查询模式

请求慢查询模式。按照 rules/slow-query-patterns-fields.md 了解需要关注的字段及其解读方法。这是主要诊断依据——它会返回你所请求时间窗口内每种模式累积的总量（调用次数、运行时间、块、行），这些就是通常需要通过两次 Prometheus 抓取推导出的“变化率”数据，但这里的数据按查询分类，而且无需等待。

如果没有任何模式返回有意义的 totalDurationUs，那么报告中的问题可能被夸大了，也可能并非由查询引起。停止操作，并告知用户你检查了哪些内容。

4. 分诊：选择合适的启发式方法

按照 rules/triage.md 操作。将 Prometheus 和慢查询的综合信号与某种启发式模式匹配。每种模式都会指向一个特定的启发式文件：

• rules/heuristic-full-scan.md — 读路径全表扫描。
• rules/heuristic-hot-loop.md — 应用中的 N+1 / 热循环。
• rules/heuristic-write-congestion.md — 死锁、写入缓慢、回滚率高。

如果信号与任何模式都无法明确匹配，不要臆造假设。列出排名靠前的模式，并询问用户他们熟悉哪些工作负载。欢迎通过 PR 提交新的启发式方法。

5. 先分析，再提出建议

使用 rules/output-template.md 中的格式。始终包含： 症状、证据、假设（注明仅凭当前表面信息无法排除的其他原因）、短期修复 和长期后续措施。

6. 不要应用修复

遵循 rules/recommend-only.md。绝不执行 DDL。绝不调用 pg_cancel_backend 或 pg_terminate_backend。撰写建议并说明原因，然后交由人工应用。

完整的编译文档

如需在单次上下文加载中获取包含所有展开规则的完整指南，请查看：AGENTS.md。