dashboard-guidelines

dashboard-guidelines

使用する場面

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

• インテグレーションパッケージ用の新しい Kibana ダッシュボードを作成する
• kibana/ フォルダー内のダッシュボード JSON の変更をレビューする
• Kibana からダッシュボードの更新をエクスポートしてパッケージのソースに反映する
• ダッシュボードの命名とファイル配置がパッケージ仕様に準拠しているか確認する
• data_stream.dataset フィルタリングを通じて、ダッシュボードとデータストリームの整合性を確認する

使用しない場面

次の内容について、主なガイドとしてこのスキルを使用しないでください。

• パッケージおよびデータストリームのディレクトリのひな形作成（create-integration、package-structure）
• インジェストパイプラインの解析と正規化ロジック（ingest-pipelines）
• パッケージ全体のコマンドオーケストレーションとスタックのライフサイクルに関する判断（elastic-package-cli）
• ダッシュボードに特化したチェック以外のテストスイートの選択（integration-testing → references/system-testing.md）

前提条件

ダッシュボードアセットを作成または更新する前に、次の点を確認してください。

1. 正しいパッケージディレクトリ（packages/<package_name>/）にいること
2. アセットの編集とエクスポートに必要な Kibana／Elastic サービスが利用可能であること
3. サンプルデータがあり、現実的なイベントやメトリクスを使ってダッシュボードを検証できること
4. パッケージの manifest.yml における互換性制約（conditions.kibana.version）を把握していること

ワークフロー：作成、エクスポート、検証

1. Kibana でダッシュボードを作成または更新します。
   • 新しいビジュアライゼーションには Lens を優先してください。
   • 共有ライブラリーの動作が意図的に必要な場合を除き、パネルはダッシュボード自体に（値として）保持します。
2. アセットをパッケージにエクスポートします。

# from package root
elastic-package export

3. エクスポート前に、インストール済みの管理対象ダッシュボードを変更する必要がある場合：

elastic-package edit dashboards
elastic-package export dashboards

4. kibana/ 内のエクスポートされたファイルを確認します。

   • ファイル名がパッケージ仕様に一致している
   • マッピング変更後に古いフィールド名が残っていない
   • ダッシュボードのフィルターがインテグレーションのデータセットに限定されている

5. PR を作成する前に、パッケージの検証コマンドを実行します。

elastic-package check

命名規則

ダッシュボード作成ガイドの命名規則を使用します。

• ビジュアライゼーションのタイトル：
  • <Name>（各パネルのタイトルでパッケージ名を繰り返さないようにします）
• ダッシュボードのタイトル：
  • [<Metrics | Logs> <PACKAGE NAME>] <Name>
  • 例：[Metrics System] Host overview、[Logs Nginx] Access overview
• ダッシュボードアセットのファイル：
  • {PACKAGE_NAME}-{identifier}.json
  • 例：nginx-046212a0-a2a1-11e7-928f-5dbe6f6f5519.json

設計とモデリングのベストプラクティス

• 安定したリリース済みの Kibana バージョンを使用します（SNAPSHOT は避けてください）。
• ダッシュボードの焦点を絞ります。情報を詰め込みすぎたダッシュボードは分割し、ナビゲーションリンクを用意します。
• ダッシュボードが自己完結するよう、値として保持するパネルを優先します。
• 新しいビジュアライゼーションには TSVB より Lens を優先します。
• 非推奨の入力コントロールビジュアライゼーションではなく、ダッシュボード標準の Controls を使ってコントロールを追加します。
• 可能な場合は、広範な logs-*／metrics-* クエリを避けるため、データセットを考慮したフィルタリングを含めます。
  • 基本的な推奨事項：data_stream.dataset でフィルタリングします
• 視覚的な階層を明確に保ちます。
  • 最も重要な概要パネルを上部近くに配置する
  • 関連するチャートをまとめる
  • 読みやすさのために余白を有効にする
• 簡潔で内容が明確に伝わるパネルタイトルと、一貫性のあるアクセシブルな色を使用します。

PR 前の品質チェックリスト

• ダッシュボードアセットが kibana/dashboard/ にあり、想定された命名規則に従っている
• ダッシュボードの内容が現在のフィールド名と型を反映している
• ドキュメント化された例外がない限り、ビジュアライゼーションが値として埋め込まれている
• ダッシュボードまたはパネルのクエリに、インテグレーションに関連するフィルター（該当する場合は data_stream.dataset）が含まれている
• 複数のダッシュボードを含むパッケージで、コントロール／ドリルダウン／ナビゲーションに一貫性がある
• エクスポートされた依存関係（ダッシュボードおよび必要な保存済みオブジェクト）がコミットされている
• パッケージで elastic-package check が成功する

よくある落とし穴

• 不安定な Kibana ビルドからエクスポートし、互換性のない保存オブジェクトデータをコミットする
• 汎用的でフィルタリングされていない logs-*／metrics-* クエリを使用し、パネルがノイズの多い表示になったり、遅くなったりする
• パイプラインやフィールドマッピングの変更後も、古いフィールド参照を残す
• 1 つのダッシュボードに詰め込みすぎず、概要ビューと詳細ビューに分割する
• 意図せずライブラリのビジュアライゼーションに依存し、隠れた依存関係を生じさせる
• ダッシュボードのタイトル、ファイル名、パッケージのコンテキストで命名が一貫していない

他のスキルへの引き継ぎ

ダッシュボードの更新が完了したら、次に進みます。

1. PR またはブランチでダッシュボードの JSON 変更をレビューするには、dashboard-review
2. システムテストの検証には、integration-testing → references/system-testing.md
3. より広範なチェック／lint／テストコマンドを選択するには、elastic-package-cli
4. ダッシュボードの変更にリリースノートの項目が必要な場合は、package-spec

参考資料

• references/kibana-assets-layout.md