dashboard-review

dashboard-review

使用する場面

次のようなタスクでは、このスキルを使用します。

• Kibana ダッシュボードの JSON ファイルを変更する PR をレビューする
• ブランチ間のダッシュボードの変更を比較する
• ダッシュボードのエクスポートで何が変更されたかを要約する
• 公式のダッシュボードガイドラインに照らして変更を確認する

使用しない場面

次の作業では、このスキルを主なガイドとして使用しないでください。

• 新しいダッシュボードを作成する、または Kibana からエクスポートする（dashboard-guidelines）
• ダッシュボードの命名規則とファイル構成（dashboard-guidelines → references/kibana-assets-layout.md）
• パッケージ全体のコマンドのオーケストレーション（elastic-package-cli）
• テストスイートの選択（integration-testing）

前提条件

kbdash がインストールされている必要があります。

go install github.com/efd6/kbdash@latest

出力内で [!] が先頭に付いた行は、ダッシュボードの JSON に潜在的な問題があることを示す警告です（整合性の不一致、不完全な抽出、解析エラーなど）。各警告タイプの説明は、kbdash -h を実行して確認してください。

レビュー手順

手順の詳細については、references/review-procedure.md をお読みください。大まかな流れは次のとおりです。

1. 特定：変更されたダッシュボードファイル（追加、削除、変更）を特定します。
2. 抽出：kbdash で変更前後の説明を抽出します。
3. 比較：説明を比較し、変更を意味のあるものか、見た目だけのものかに分類します。
4. 検証：問題の可能性がある箇所を報告する前に、生の JSON で確認します。
5. 整形：ダッシュボードごとにセクションを分け、変更を箇条書きにして出力します。
6. 確認：追加または変更されたダッシュボードがガイドラインに準拠しているか確認します。

ガイドライン準拠チェック

変更内容を要約した後、追加または変更された各ダッシュボードの最終状態を公式ダッシュボードガイドラインに照らして確認します。 各ダッシュボードの変更内容の要約の後に、「ガイドラインに関する注記」サブセクションを設けて、違反事項を報告してください。

次の問題がないか確認してください：

• TSVB パネル： TSVB を使用する visualization パネルがあれば指摘します。ガイドラインでは、新しいビジュアライゼーションにはすべて Lens を使用することが求められています。既存の TSVB を Lens に移行することも推奨されています。
• データセットフィルターの欠落： 各ビジュアライゼーションでは、data_stream.dataset または同等に具体的なスコープでフィルタリングしてください。スコープを指定せずに広範なインデックスパターン（metrics-*、logs-*）をクエリしているパネルがあれば指摘します。
• 参照によるビジュアライゼーション： ビジュアライゼーションパネルと Lens パネルは値を埋め込む必要があります。kbdash が [!] <type> ref: … (definition not inlined) と示す、参照による lens、visualization、map パネルがあれば指摘します。保存済み検索は本質的に参照を使用し、別個の [!] saved search ref 警告が表示されますが、これは指摘しないでください。
• 非推奨の入力コントロール： input-control-vis タイプは非推奨です。ダッシュボード標準のコントロールを使用してください。
• パッケージ名のタイトル接頭辞： [<Package Name> ...] に一致するパネルタイトルは不要な重複を生みます。該当するものがあれば指摘します。
• 広範なワイルドカードフィルター： スコープの指定がなく、追加の条件もない -* パターンを使用するフィルターは、パフォーマンス上の懸念があります。
• パネル数が多い： kbdash はパネルセクションの見出しに件数を含めます（Panels (N total, …)）。N が約 20 を超える場合は、その旨を記載します。ガイドラインでは、ダッシュボードを分割し、ドリルダウンで相互にリンクすることを推奨しています。
• data_stream.dataset ではなく event.dataset を使ったクエリ： 保存オブジェクトのクエリ（ダッシュボード、保存済み検索、パッケージ化された ML ジョブのデータフィード）では、data_stream.dataset でフィルタリングする必要があります。一部の入力（例：packetbeat）は event.dataset を設定しないため、event.dataset フィルターは何も一致しないままになります。フィールド名を変更または再マッピングする差分内に保存オブジェクトのクエリがあれば、すべて指摘します。
• YAML ダッシュボードソースの同期ずれ： パッケージで _dev/shared/kibana/*.yaml に YAML ダッシュボードソースを保持し、kb-dashboard で kibana/dashboard/*.json にコンパイルしている場合、両方をコミットし、同期させる必要があります。そのダッシュボードの YAML ソースがあるのに JSON のみを編集している場合は指摘します。
• 再生成時の差分： 再コンパイル PR では、変更箇所は state.adHocDataViews、state.internalReferences、および各レイヤーの index キー（Kibana 9.3 以降の ES|QL／Discover の修正）のみに限定されることが想定されます。「再生成」PR でこれら以外に差分がある場合は、確認が必要です。
• Kibana アセットタグの欠落： kbdash は各ダッシュボードについて Tags: セクションを表示します（パッケージディレクトリに対して実行した場合、kibana/tag/ から解決されます）。新しいコンテンツパックのダッシュボードには Kibana アセットタグを設定することが想定されます。タグがない場合は、その旨を記載します（重要度：低）。
• ナビゲーションリンクの網羅性： ダッシュボードにリンクパネルがある場合、パッケージ内のすべてのダッシュボードに対応するエントリーがあることを確認します。kbdash <package-dir> を実行すると、各リンクパネルの Link: 行と並んで、すべてのダッシュボードタイトル（=== … === の見出し）が表示されます。タイトルに一致するリンクがないダッシュボードがあれば、その旨を記載します。

実際に存在する問題のみ報告してください。問題のないチェック項目は省略します。変更されていないパネルに以前から存在する違反は、個別に列挙せず、「既存の N 個のパネルも TSVB を使用しています」のように簡潔に一度だけ記載してください。新規追加または変更されたパネルの確認を優先してください。

他のスキルへの引き継ぎ

レビュー完了後：

1. 構造上の問題が見つかった場合は、作成またはエクスポートに関するガイダンスとして dashboard-guidelines を参照します
2. ダッシュボードの変更にリリースノートの項目が必要な場合は、package-spec を参照します
3. 検証コマンドについては、elastic-package-cli を参照します

参考資料

• references/review-procedure.md — 抽出、比較、出力形式の全手順