doris-profile-reader

Doris Profile Reader

目的

このスキルは、Apache Doris のクエリ実行時プロファイルにおける実際のボトルネックを特定するために使用します。基本原則は、オペレーターを高コストと判断する前に、実際の処理と、依存関係による待機、キュー待ち、バックプレッシャーによる待機を切り分けることです。実行計画に結合が含まれる場合は、実行時の直接的なボトルネックと、特に不適切な結合順序やランタイムフィルターの方向といった実行計画の形状に起因する原因も切り分けます。

必須の読み取り順序

1. 分析のワークフローと出力要件について、references/reading-workflow.md を読みます。
2. カウンターの意味と優先順位、特に待機カウンターについて、references/counter-semantics.md を読みます。
3. 該当するオペレーターファミリーについて、references/operator-guide.md を読みます。
4. プロファイルに偏り、不適切な結合／分散の選択、弱い枝刈り、ソート／スピル／リソースの圧迫、外部スキャン／カタログ、ライフサイクル待ちが見られる場合、またはユーザーがプロファイルのみを根拠とした課題レベルの根本原因を求めている場合は、references/failure-patterns.md を読みます。
5. プロファイルまたは実行計画に複数の結合、大規模なハッシュ結合／ネステッドループ結合のビルド、大規模なスキャン（結合によって枝刈りできた可能性があるもの）、高速／低速の対になった実行計画、ヒント／並べ替えた SQL が含まれる場合、または結合の形状／並べ替えについて質問された場合は、references/join-order-diagnosis.md を読みます。
6. プロファイルまたは実行計画に RuntimeFilterInfo、RF... <-、RF... ->、JRFs、WaitForRuntimeFilter、AcquireRuntimeFilter が含まれる場合は、references/runtime-filters.md を読みます。
7. ソースに基づくオペレーター／カウンターの一覧として、references/source-profile-inventory.md を使用します。カウンターやオペレーターが説明ドキュメントに記載されていなくても無視せず、この一覧で調べ、counter-semantics.md のルールに従って分類します。
8. ユーザーが修正、回避策、緩和策、チューニング、SQL の書き換えを求める場合、または要求された出力スキーマに解決策の項目が含まれる場合は、references/solution-playbook.md を読みます。
9. 根本原因の層を特定した後、解決策を求められている場合は、references/known-issues-solutions.md を読みます。これは過去の根拠として使用し、プロファイルの診断の代わりにはしません。

絶対に守るべき解釈ルール

• WaitForDependencyTime、WaitForDependency[...]Time、WaitForData0、WaitForDataN、WaitForRpcBufferQueue、WaitForBroadcastBuffer、PendingFinishDependency、またはパイプラインのブロック／待機カウンターを、演算子の直接的な計算コストと見なさないでください。これらは依存関係、データ到着、キュー、メモリ、またはバックプレッシャーのシグナルです。
• DATA_STREAM_SINK_OPERATOR の高い RpcMaxTime／RpcAvgTime を、一般的な待機カウンターとして扱って無視しないでください。BytesSent と RpcCount がゼロ以外なら、これはエクスチェンジ／RPC パスの証拠です。ウォールタイムに近い、またはローカルのシリアライズ／圧縮／送信タイマーを上回る場合は、ボトルネックの結論に含め、チャネル、受信側、または BE 間の外れ値的な偏りを確認してください。
• セッション変数、最適化の欠如、または大量の行数が、データがエクスチェンジに到達した理由を説明できる場合、ローカルのスキャン／ソート／ウィンドウ／結合のアクティブタイマーが支配的でない限り、それを主な低速原因にしないでください。DATA_STREAM_SINK_OPERATOR の RPC 時間が経過時間を支配する場合は、プラン／データ量を増幅要因として扱い、RPC／BE 間転送を主なボトルネック候補として残してください。
• 複数のプロファイルが提示された場合は、単一プロファイルの待機症状よりも、その差異を優先してください。低速／高速プロファイルで結合順序、プルーニング、instance_num、エクスチェンジ分散、またはバケット／シンク構成が異なる場合は、一般的な RPC、スキャナー、またはエクスチェンジのバックプレッシャーを原因とする前に、そのプラン／データレイアウトの差異を診断してください。
• 結合／射影のホットスポットが、1 つのテーブルの幅広い JSON／VARIANT／文字列列に支配され、単一インスタンスまたは大きく偏った実行になっている場合、式の CPU 使用量だけで結論を止めないでください。実行時の症状は式の CPU 使用量として示しつつ、根本原因として結合順序／分散、またはコストモデルによる幅広い列の処理コストの過小評価が考えられることを述べてください。
• INSERT/SELECT プロファイルでは、目立つ大量行処理の SPLIT_BY_STRING／cardinality(split_by_string(...)) 式を、主な根本原因候補として扱ってください。独立したアクティブなシンク／書き込みタイマーが支配的でない限り、一般的なスキャン／シャッフル／テーブルシンクのデータ量より下位に置かないでください。
• INSERT の偏りについては、受信側または UNION／ローカルエクスチェンジの偏りを、ターゲットのバケット数、バケットキー、書き込みバケット並列度、および偏った値に関連付けてください。正確な DDL がない場合は、エクスチェンジの偏りだけで結論を止めず、ターゲットのバケット／キー設計の不一致、または書き込みバケット数の不足が考えられると結論づけてください。
• 全件スキャンまたは INSERT が行数だけを理由に遅いと結論づける前に、SQL／プランのテキストから SPLIT_BY_STRING、正規表現、trim／replace の連鎖、INSTR、COALESCE、NULLIF などの文字列処理が重い式を探してください。大量の行では、ProjectionTime カウンターが見えなくても、これらの式は根本原因候補として残ります。
• 出力がごく少量なのにタブレット／スキャナー数が多いポイントクエリまたは限定的な範囲のクエリでは、バケット／タブレットのプルーニングについて明確に判断してください。ワークロード負荷の証拠がない限り、高い ScannerWorkerWaitTime はファンアウトの症状です。述語とインデックスが有効なのに多数のタブレットが開かれる場合は、スキャナープールの競合よりも、バケットプルーニングの欠如またはテーブルレイアウトを優先して考えてください。
• 待機らしきカウンターが最大の演算子を、その値だけで順位付けしないでください。まず ExecTime／アクティブタイマー、直接的なカスタムタイマー、行数／バイト数、メモリ／スピル、偏りに基づいて順位付けしてください。
• クエリのボトルネックを順位付けする前に、プロファイルの種類を確認してください。Async-profiler の CPU フレームグラフ、FE の load-image／load-auth プロファイル、ログ、またはキャッシュ済みサマリーは、それぞれのライフサイクル上のホットスポットを示す有効な証拠ですが、BE のクエリ実行時プロファイルではありません。ファイルの種類が要求された低速クエリの質問に合わない場合は、その不一致を伝え、無関係な Doris クエリの結論を無理に導かず、対応する実行時プロファイルを求めてください。
• OOM、スピル後のタイムアウト、またはメモリ制限に関するプロファイルでは、根本原因を選ぶ前にメモリの使用元を特定してください。セッション／グローバルのメモリ設定、スピル状態、演算子ごとのピークメモリ、ハッシュ結合のビルド／プローブメモリ、集約のハッシュ／状態メモリ、ソートバッファー、テーブルシンクバッファー、エクスチェンジバッファー、式の実体化を確認してください。集約状態と式の実体化のコストが該当するかどうかを確認する前に、大規模な結合を根本原因としないでください。
• セッション／設定の証拠は、演算子の形状からの推測より優先される場合があります。並列スキャンの無効化、非常に小さい parallel_pipeline_task_num、低いメモリ使用率／上限、二段階読み取りの無効化、ローカルシャッフルの無効化など、明示的な非デフォルト設定は、結合順序の不適切さ、スキャナーの競合、ネットワーク上の外れ値と結論づける前に評価してください。
• 要約する前に、複数のプロファイルを個別に分析してください。各プロファイルについて、支配的なアクティブ／待機／リソースのシグナルを示してから、比較してください。無関係なプロファイルを、一般的なファンアウト、スキャン、結合、または RPC の説明にまとめないでください。
• プロファイルに見えるボトルネックと、イシューの根本原因は分けてください。より深い原因の特定にスキーマ、統計、バージョン、設定、ログ、コメント、または高速／低速の比較が必要で、それらが提示されていない場合は、プロファイルから確認できることを述べ、過度な断定を避けて、具体的に不足している確認事項を挙げてください。
• 解決策の欄では、考えられる検証事項をすべて修正策に変換しないでください。まず解決策の根拠を、プロファイルで確認済み、正確な過去のパターン、コードで裏付けられているが未確認の次の確認事項、過去に該当する解決策なし、のいずれかに判断してください。既知のパターンの証拠にある正確な過去のパラメーター名、値、PR 番号、バージョン番号、SQL 書き換えの形はそのまま保持してください。
• 診断が不確実、またはプロファイルレベルにとどまる場合は、具体的な緩和策よりも、過去の解決策を空欄にして、対象を絞った next_checks を優先してください。誤った具体策を提示するより、具体策を提示しないほうが適切です。
• 要求されたスキーマに historical_solution がある場合、profile_proven または正確な historical_pattern に該当するアクションのみ記入してください。アクションに検証が必要な場合、または近接するパターン群から推定される場合は、historical_solution を空欄にし、そのアクションを next_checks に移してください。
• 複数プロファイルをマージした sum タイマーは、並列インスタンス全体で累積された値として扱ってください。多数のスキャナー、ドライバー、またはフラグメントが並列実行されている場合、タイマーがクエリの経過時間を超えていても、正常なことがあります。
• スキャンでは、RowsRead、ScanRows、ScanBytes、ScannerCpuTime、ScannerGetBlockTime、ScannerWorkerWaitTime、I/O／展開タイマー、述語／遅延読み取りタイマー、行フィルターのカウンターを優先してください。ScannerWorkerWaitTime は重要ですが、スキャンの CPU 時間ではなく、スケジューリング／スレッドプールの待機を示します。
• ランタイムフィルターでは、生成側／ビルド側と、対象／プローブ側のスキャンを区別してください。プランのテキストでは、RFxxx <- expr はビルド側で生成され、RFxxx -> expr は対象スキャンに適用されます。プロファイルでは、RuntimeFilterInfo とスキャン側の待機／フィルターカウンターを見て、RF が役立ったのか、単に待機したのかを判断してください。
• 結合では、順序を評価する前に必ずビルド側とプローブ／対象側を特定してください。選択性の高い結合／RF の生成元が遅くスケジュールされ、そのスキャンをプルーニングできなかったことが根本原因であれば、スキャンが直近のアクティブなボトルネックでも、原因は不適切な結合順序である可能性があります。
• 結合／分散の選択が不適切に見える場合は、見積もり行数と実際の行数、統計／NULL／偏った値の証拠、結合分散、RF の方向（存在する場合）を確認してください。プランナー／統計に関する症状がプロファイルに示されているのに、「大規模なスキャン」や「大規模なビルド」だけで結論を止めないでください。
• 不適切な結合順序を指摘するために、高速プロファイルとの比較を必須にしないでください。空または少量のプローブ／結果に至る前に大量のビルド／スキャン処理が行われたこと、空またはごく小さいフィルターを生成するために RF の生成元側で大規模なスキャンが必要だったこと、または後で選択性の高い／矛盾する結合述語によって除去される巨大な中間結果があったことを示すなら、単一の低速プロファイルだけでも十分な場合があります。
• 「現在の RF により他のスキャンが待機した後、処理をスキップした」ことを、結合順序が良好である証拠として扱わないでください。その空またはごく小さい RF の生成に唯一の高コストなスキャンが必要だった場合、RF の生成元／対象の選択自体が結合順序の検討事項です。
• ビルド／生成元側の大きな処理を先に行い、その後に空またはごく小さいプローブ、保持側、セミ結合キーセット、または矛盾する結合で結果を除去できる場合は、その順序が意味的に強制され、より早いプルーニング／短絡が不可能であることをプロファイルが示していない限り、ビルド／プローブの順序が不適切である可能性が高いと判断してください。
• スキャン、結合、集約、エクスチェンジ、ソート、またはシンク演算子で max が avg を大幅に上回る場合は、原因を一般的なデータ量とする前に偏りを確認してください。インスタンスごとの行数／時間／バイト数、タブレットまたはバケットの割り当て、ローカルシャッフル、分散キー、グローバル／セッションの並列度を比較してください。
• 単一プロファイルで結合順序が不適切であることを示す強いパターンが見られる場合、「疑わしい」「不適切である可能性が高いに近い」「証明されていない」といった曖昧な表現にしないでください。より良い合法な順序の検証が必要な場合は「不適切である可能性が高い」とし、「証明されていない」は、結合順序の診断そのものではなく、正確な代替形状についてのみ使用してください。
• 結合クエリにプラン形状の証拠がある場合、回答では結合順序／ビルド・プローブ／RF の方向が良好、疑わしい、または不適切のいずれかを明示的に判断してください。その判断を、曖昧な「述語の問題」や「プラン形状の問題」に置き換えないでください。
• InitTime、OpenTime、CloseTime、またはプロファイル合計が長いことは重要な場合がありますが、多数のインスタンスにわたる累積値ではなく、既知の待機／依存関係の分岐に支配されていないことを確認してから判断してください。

標準的な回答形式

プロファイルについて説明する場合は、次の順序で回答してください。

1. 結論：可能性の高いボトルネックを1〜2文で述べます。結合が関係する場合は、プランの形状／結合順序が原因である可能性についても触れます。
2. 根拠：オペレーター名と値を示し、プロファイルのカウンターが、実際の処理、データ量、待機／バックプレッシャー、メモリ／スピル、ランタイムフィルターのいずれを示すかを説明します。
3. 推論：根拠が実行プランにどう対応するか、どちら側がビルド側／プローブ側またはRFソース／ターゲットか、誤解を招くカウンターを割り引く理由、結合順序が妥当かどうかを説明します。
4. 次の確認項目：結論がまだ不確かな場合に必要となる、最小限の追加プロファイル／ログ／コードの確認事項を示します。
5. 要求された場合は解決策／緩和策：このプロファイル、またはreferences/known-issues-solutions.mdにある一致する過去のパターンによって直接裏付けられる解決策のみを挙げます。過去の事例にもプロファイルにも裏付けられた解決策がない場合は、その旨を述べ、助言を捏造せず、次の確認項目として扱います。

不確実性は常に明示してください。プロファイルの詳細が不十分な場合は、「確認済み」「可能性が高い」「未確認」を明確に使ってください。

スクリプト

• scripts/extract_source_profile_inventory.py：Doris のソースをスキャンし、ファクトリーで作成されるオペレーターとカウンター／情報の登録を調べます。

スクリプトは根拠を生成するための補助ツールです。読み取りの手順に代わるものではありません。