clickhouse-managed-postgres-rca

ClickHouse Managed Postgres RCA

使用するタイミング

ユーザーから、ClickHouse 管理下の Postgres インスタンスでの遅延、高 CPU 使用率、低スループット、キャッシュスラッシング、または原因不明の問題が報告されたら、必ず実行してください。

利用できるもの

https://api.clickhouse.cloud 上の 2 つの API（ClickHouse Cloud の API キーとシークレットのペアを使った HTTP Basic 認証）：

• Prometheus メトリクス — Prometheus タグの操作 postgresInstancePrometheusGet。Prometheus エクスポジション形式で返されます。1 つの Postgres サービスのシステムメトリクスとワークロードメトリクスです。
• Slow Query Patterns — Postgres タグの操作 slowQueryPatternsGetList。正規化されたクエリパターンについて、ダイジェストごとのレイテンシ、IO、呼び出し統計を返します。ベータ版です。

どちらのエンドポイントにも、パスパラメーターとして organizationId と serviceId が必要です。ユーザーから両方と、API キーとシークレットのペアを提供してもらう必要があります。

利用できないもの

• クエリプラン／EXPLAIN 出力。
• テーブルごとのスキャン種別カウンター（seq_scan／idx_scan）。
• autovacuum または最終 ANALYZE のタイムスタンプ。

プランツリーではなく、IO とタイミングのシグナルに基づいて判断してください。

ワークフロー

6 つのステップを順番に実行します。先に進んでステップを飛ばさないでください。

ステップ 2 と 3 は認証情報を共有するだけで、データ上の依存関係はありません。並列実行（バックグラウンドでの curl、& と wait）して、順次実行時の約 2 秒から約 1 秒に短縮してください。

1. 最新の API 仕様を確認する

これらのエンドポイントはベータ版のため、パス、パラメーター、JSON フィールド名が変わる可能性があります。rules/openapi-discovery.md に従って、次を行います。

1. https://api.clickhouse.cloud/v1 から OpenAPI 仕様を取得します。
2. operationId で 2 つの操作を特定します。
   • postgresInstancePrometheusGet（Prometheus タグ）
   • slowQueryPatternsGetList（Postgres タグ）
3. パスのテンプレート、必須クエリパラメーター、および（Slow Query エンドポイントについては）レスポンススキーマを特定します。
4. スキーマのプロパティの説明から、セッション単位のロールマップ { semantic role → actual field name } を作成します。

以降のすべてのリクエストと引用では、特定した名前を使用してください。記憶を頼りにフィールド名を決め打ちしないでください。

2. システムゲージのため Prometheus を 1 回スクレイプする

rules/prometheus-scrape.md に従ってください。スクレイプは 1 回、待機は不要です。 差分が不要なゲージ（現在値）を確認します。 CacheHitRatio、ActiveConnections、MemoryUsedPercent、FilesystemUsedPercent が対象です。

キャッシュに収まるはずのワークロードで CacheHitRatio が約 95％を大きく下回る場合、それだけで有力なシグナルになります。ActiveConnections がプール上限に向かって増加している場合も、それだけで有力なシグナルです。これらの判断に変化率は必要ありません。

カウンターの差分を確認するための 2 回目のスクレイプは任意です。ステップ 4 のトリアージで書き込みの輻輳が疑われる場合に限り使用してください（デッドロックとロールバックの発生率が重要で、Slow Query Patterns API では代替できません）。最も一般的な RCA パターンである読み取り経路のケースでは、1 回のスクレイプで十分です。

3. 上位の低速クエリパターンを取得する

低速クエリパターンをリクエストします。重要なフィールドとその読み取り方については、rules/slow-query-patterns-fields.md に従ってください。これは主要な診断手段です。リクエストした期間内のパターンごとの累積合計（呼び出し回数、実行時間、ブロック数、行数）を返します。これは、2 回の 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 を参照してください。