altinity-expert-clickhouse-reporting

クエリパフォーマンスの分析

system.query_log、system.processes、system.query_views_log から「どのクエリが遅い、または失敗しており、その理由は何か」に回答します。クエリは normalized_query_hash でグループ化されます。これによりリテラルが統一され、1 行が単一の実行ではなく、クエリパターンを表すようになります。 接続モード、クラスター、時間範囲がまだ確定していない場合は、最初に altinity-expert-clickhouse-connection を実行してください。

クエリパック

• checks.sql — 15 個のチェック：現在実行中のクエリ、最近のパフォーマンス概要、最も遅いクエリ、最も頻繁なクエリパターン、CPU 時間別のクエリ、読み取りデータ量が多すぎるクエリ、アクセスしたテーブル別のクエリ、最近の失敗とエラーコード別の失敗概要、クエリタイプの分布、クエリのピーク時間、ユーザー別のクエリ、INSERT 中のマテリアライズドビューの実行、クエリごとの遅いマテリアライズドビューの内訳、分散クエリのパフォーマンス。そのうち 2 つには system.query_views_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 列はその行の判定です。そのままコピーし、再評価しないでください。

詳細分析のステートメント

query_id が判明している遅いクエリについては、インデックスの選択性を測定します。SelectedMarks を SelectedMarksTotal で割った値は、プライマリインデックスでプルーニングできなかったテーブルの割合です。1 に近い場合は、ORDER BY キーが役に立っていません。

SELECT
    query_id,
    read_rows,
    result_rows,
    formatReadableSize(read_bytes) AS read_bytes,
    ProfileEvents['SelectedParts'] AS selected_parts,
    ProfileEvents['SelectedMarks'] AS selected_marks,
    ProfileEvents['SelectedMarksTotal'] AS selected_marks_total,
    round(ProfileEvents['SelectedMarks'] / nullIf(ProfileEvents['SelectedMarksTotal'], 0), 4) AS marks_read_fraction
FROM clusterAllReplicas('{cluster}', system.query_log)
WHERE query_id = '{query_id}' AND type = 'QueryFinish';

次に、テーブルにさらにプルーニングできるデータスキッピングインデックスがあるか確認します。

SELECT database, table, name AS index_name, type, expr, granularity
FROM clusterAllReplicas('{cluster}', system.data_skipping_indices)
WHERE database = '{database}' AND table = '{table}';

解釈ルール

• read_rows が result_rows を大幅に上回る場合、選択性が低いのであり、サーバーが遅いわけではありません。両方の数値を示し、インデックス分析スキルに案内してください。対処方法は ORDER BY キーまたはスキップインデックスであり、ハードウェアの増強ではありません。
• 調査結果は normalized_query_hash でグループ化します。200 ms のクエリが 5000 回実行されると、60 s のクエリ 1 回よりコストがかかります。これが見えるのはパターンビューだけです。最悪の単一実行ではなく、パターンと合計時間を報告してください。
• 同じ normalized_query_hash が同じ結果で繰り返し現れる場合、クエリキャッシュの候補です。クエリ自体を最適化する前に、キャッシュスキルを確認してください。
• クエリの memory_usage が大きい場合は、スキャンではなく集約または JOIN が原因です。インデックスを推奨するのではなく、メモリスキルに案内してください。
• 多くのパーツにアクセスするクエリ（テーブルのパーツ総数に対して SelectedParts が多い）は、マージの滞留を読み取っています。まずマージを解消してください。クエリプランはすでに最適な場合があります。
• reporting-13 と reporting-14 で見つかった遅いマテリアライズドビューは、それをトリガーする INSERT を遅くするものであり、SELECT を遅くするものではありません。この調査結果は取り込み経路に関するものです。
• 失敗について：type IN ('ExceptionBeforeStart', 'ExceptionWhileProcessing') はそれぞれ異なる状態です。ExceptionBeforeStart はクエリが一度も実行されなかったことを意味します（構文解析、アクセス、または制限による拒否）。ExceptionWhileProcessing はクエリが実行され、その後停止したことを意味し、通常はメモリまたはタイムアウトの制限が原因です。
• 失敗を要約する際は、この診断セッション自体が生成したエラーコード（UNKNOWN_IDENTIFIER、UNKNOWN_TABLE、SYNTAX_ERROR）を無視してください。

レポート形式

1. ヘッダー：接続モード、クラスターまたは「単一ノード」、ClickHouse のバージョン、対象期間。
2. 調査結果：check、severity、object、evidence、recommendation の列を含む表。調査結果ごとに 1 行とし、重大度の高いものから並べます。根拠には結果行の数値を引用します。
3. 問題のないチェック：問題のある行がなかったチェック ID を 1 行で列挙します。
4. スキップおよび失敗したチェック：ID と理由、または最初のエラー行を記載します。このセクションは必ず含めてください。
5. 次のステップ：次に読み込むスキルと、すぐに実行するアクション。

次のスキル

• result_rows に対して read_rows が大幅に多い、マークのプルーニング率が低い、またはスキップインデックスが不足しているか未使用の場合 → スキル altinity-expert-clickhouse-index-analysis を読み込みます
• クエリごとのメモリ使用量が多い、または MEMORY_LIMIT_EXCEEDED エラーが発生している場合 → スキル altinity-expert-clickhouse-memory を読み込みます
• テーブルごとに多数のパーツを読み込むクエリがある場合 → スキル altinity-expert-clickhouse-merges を読み込みます
• 同一クエリが繰り返し実行されている、またはマークキャッシュや非圧縮キャッシュのヒット率が低い場合 → スキル altinity-expert-clickhouse-caches を読み込みます
• 挿入中のマテリアライズドビューが遅い場合 → スキル altinity-expert-clickhouse-ingestion を読み込みます
• ORDER BY、パーティショニング、またはマテリアライズドビューの設計に問題がある場合 → スキル altinity-expert-clickhouse-schema を読み込みます
• 分散クエリがシャードの処理時間の合計より遅い、またはレプリカの 1 つに遅延が発生している場合 → スキル altinity-expert-clickhouse-replication を読み込みます
• エラーコードに ACCESS_DENIED や認証エラーが含まれている場合 → スキル altinity-expert-clickhouse-grants を読み込みます
• クエリのレイテンシーがディスク読み取りスループットと相関している場合 → スキル altinity-expert-clickhouse-storage を読み込みます