altinity-expert-clickhouse-metrics

リアルタイムのメトリクスと飽和状態

system.metrics、system.events、system.asynchronous_metrics、system.metric_log、system.asynchronous_metric_log を使って、「現在どのリソースが飽和しているか、1 時間前も飽和していたか」に答えます。 接続モード、クラスター、時間範囲がまだ決まっていない場合は、まず altinity-expert-clickhouse-connection を実行してください。

クエリパック

• checks.sql — 14 個のステートメントに 12 個のチェック（id は metrics-01 から metrics-12）を含みます。メモリ、実行中のクエリ、接続の飽和状態の概要、CPU コア数に対するロードアベレージ、レプリケーションメトリクス、パーティションあたりのパーツ数の上限と挿入しきい値の比較、バックグラウンドプールの使用率、起動後の失敗およびスロットリングのカウンター、過去 6 時間のメモリとロードアベレージ、過去 1 時間のクエリレート、ブロックデバイスのキュー深度、稼働時間とバージョン、Prometheus エンドポイント設定を確認します。チェック metrics-02 と metrics-10 は、それぞれ補完的な @requires version<26.8 と @requires version>=26.8 のヘッダー付きで 2 回登場します。サーバーのバージョンに一致する方だけを実行してください。チェック metrics-07 と metrics-08 には system.asynchronous_metric_log が、metrics-09 には system.metric_log が必要です。
• reference.md — 背景情報（設定、サイジング、アンチパターン）を記載しています。推奨事項の説明が必要な場合にのみ読んでください。

クエリパックの実行方法

1. このスキルのディレクトリから各パックファイルを読み込みます（スキルローダーがディレクトリパスを出力します）。
2. ステートメントはファイル全体ではなく、1 つずつ実行します。ステートメントは ; で終わり、-- @check <id> <title> ヘッダーで始まります。id を結果とともに保持してください。
3. -- @requires に従ってください。指定されたテーブルがない場合、keeper が必要なのにサーバーに Keeper/ZooKeeper がない場合、またはバージョン条件を満たさない場合は、そのステートメントをスキップします。スキップした id と理由を記載してください。
4. クラスターのマクロが存在する場合は、{cluster} をそのまま使用します。それ以外の場合は、接続スキルの書き換えルールを適用してください。ほかの {placeholder} はすべてテンプレート変数です。実際の値に置き換えるか、ステートメントをスキップしてください。
5. エラーが発生した場合は、チェック id とエラーの最初の行を記録してから続行します。UNKNOWN_IDENTIFIER の場合に限り、DESCRIBE TABLE system.<table> を実行して、不足しているカラムを除外してください。
6. severity カラムは、その行の判定結果です。そのまま転記し、再判定しないでください。

解釈ルール

• 飽和率とその深刻度は SQL で計算されます。そのまま記載してください。以下のルールでは、リソースが飽和している状態の意味を説明します。
• 15 分間にわたり CPU コア数を超えるロードアベレージが続く場合、ホストは単に高負荷なのではなく、CPU がボトルネックになっています。1 分間のロードが高くても、15 分間のロードが通常であればスパイクであり、通常は対応不要です。
• 実行中のクエリ数が max_concurrent_queries に近づくと、新しいクエリはキューに入り、その後 TOO_MANY_SIMULTANEOUS_QUERIES で失敗します。まず遅いクエリを修正してください。上限を引き上げると、拒否がメモリ負荷に変わります。
• 接続数が max_connections に近づくと、ClickHouse のエラーではなく、クライアント側で接続タイムアウトとして表面化します。上限を引き上げる前に、接続プールのリークがないか確認してください。
• ブロックデバイスの処理中操作数が 128 を超えると、ディスクキューが飽和し、すべての読み取りがその後ろで待機します。200 を超えると、ClickHouse の動作にかかわらず、そのデバイスがボトルネックです。
• パーティションあたりの最大パーツ数が parts_to_delay_insert を超えると、すでに INSERT が遅くなっています。parts_to_throw_insert を超えると、INSERT は TOO_MANY_PARTS で失敗します。どちらも INSERT の問題ではなく、マージの問題です。
• metrics-06 の RejectedInserts または DelayedInserts がゼロ以外であれば、パーツ数が原因で INSERT がスロットリングされていることが確認できます。
• ZooKeeperHardwareExceptions がゼロ以外の場合、Keeper セッションが失われており、レプリケーションと ON CLUSTER DDL が停止します。ZooKeeperUserExceptions は、ほとんどの場合問題ありません（ノードが存在する、ノードが存在しないなど）。
• metrics-06 のカウンターはサーバー起動以降の累積値なので、metrics-11 の稼働時間と合わせて確認してください。稼働期間が数か月に及ぶホストでカウンターが大きくても、過去の値である可能性があります。
• 稼働時間が 1 時間未満の場合、観測期間中にサーバーが再起動しています。このレポートのカウンターやレートを信頼する前に、原因を調べるため system.crash_log と system.text_log を確認してください。
• metrics-12 が Prometheus エンドポイントなしと報告している場合は、監視の不足であり、サーバー障害ではありません。深刻度は Minor として報告してください。

詳細調査用ステートメント

チェックで、パックがカバーしていない項目が示された場合、パターンに一致する名前を持つすべてのメトリクス、非同期メトリクス、イベントを検索します。

SELECT 'metrics' AS source, metric AS name, toString(value) AS value, description FROM system.metrics WHERE metric ILIKE '%{pattern}%' UNION ALL SELECT 'asynchronous_metrics', metric, toString(value), description FROM system.asynchronous_metrics WHERE metric ILIKE '%{pattern}%' UNION ALL SELECT 'events', event, toString(value), description FROM system.events WHERE event ILIKE '%{pattern}%' ORDER BY source, name;

非同期メトリクスを 1 つ、過去 6 時間分、15 分間隔でプロットします。

SELECT toStartOfFifteenMinutes(event_time) AS ts, round(avg(value), 2) AS avg_value, round(max(value), 2) AS max_value FROM system.asynchronous_metric_log WHERE event_time > now() - INTERVAL 6 HOUR AND metric = '{metric}' GROUP BY ts ORDER BY ts;

レポート形式

1. ヘッダー：接続モード、クラスターまたは「単一ノード」、ClickHouse のバージョン、時間範囲。
2. 検出事項：列を check、severity、object、evidence、recommendation とする表。検出事項ごとに 1 行を記載し、Critical を先頭にします。Evidence には結果の行にある数値を引用します。
3. 問題のないチェック：問題のある行が返されなかったチェック ID を 1 行に列挙します。
4. スキップおよび失敗したチェック：ID と理由、または最初のエラー行を記載します。このセクションは必ず含めてください。
5. 次のステップ：次に読み込むスキルと、直ちに行う対応。

次のスキル

• メモリ飽和、またはカウンターに MEMORY_LIMIT_EXCEEDED がある場合 → スキル altinity-expert-clickhouse-memory を読み込みます
• 読み取り専用レプリカ、レプリカ遅延、キューの増加、または Keeper ハードウェア例外がある場合 → スキル altinity-expert-clickhouse-replication を読み込みます
• パーティションあたりのパーツ数が遅延または例外発生のしきい値に近い場合、または MergesAndMutations プールが飽和している場合 → スキル altinity-expert-clickhouse-merges を読み込みます
• INSERT が拒否または遅延されている場合 → スキル altinity-expert-clickhouse-ingestion を読み込みます
• ロードアベレージが高い場合、または多数の実行中クエリが特定のクエリに起因すると判明した場合 → スキル altinity-expert-clickhouse-reporting を読み込みます
• ディスクキューが飽和している場合、またはデバイスが遅い場合 → スキル altinity-expert-clickhouse-storage を読み込みます
• 最近の再起動またはクラッシュの原因を調べる必要がある場合 → スキル altinity-expert-clickhouse-logs を読み込みます
• カウンターに関連するパーツの作成、マージ、削除のレートを確認する場合 → スキル altinity-expert-clickhouse-part-log を読み込みます