Kibana ダッシュボードと可視化

概要

Kibana ダッシュボードと可視化 API は、ダッシュボードと可視化を定義するための宣言的で Git フレンドリーなフォーマットを提供します。定義は最小限で、diff が取りやすく、バージョン管理と LLM による生成に適しています。

主な利点:

• 最小限のペイロード (実装詳細や派生プロパティなし)
• Git での diff が容易
• GitOps ワークフロー向けの一貫したパターン
• LLM ワンショット生成向けに設計
• OpenAPI スペックによる堅牢な検証

バージョン要件: Kibana 9.4+ (SNAPSHOT)

重要な注意事項

ES|QL 可視化: ES|QL ベースの可視化は /api/visualizations を使用して作成することはできません。Dashboard API を使用してダッシュボード内のインラインパネルとして作成する必要があります。

インライン vs 保存オブジェクト参照: ダッシュボード内に可視化パネルを埋め込む場合、ref_id 参照ではなくインライン定義を使用してください。インライン定義はより信頼性が高く、自己完結しています。

クイックスタート

環境設定

Kibana への接続は環境変数で設定します。node scripts/kibana-dashboards.js test を実行して接続を確認してください。テストが失敗した場合は、次のセットアップオプションをユーザーに提案してから停止してください。接続テストが成功するまで、さらに探索することは試さないでください。

オプション 1: Elastic Cloud (本番環境に推奨)

export KIBANA_CLOUD_ID="deployment-name:base64encodedcloudid"
export KIBANA_API_KEY="base64encodedapikey"

オプション 2: API キーを使用した直接 URL

export KIBANA_URL="https://your-kibana:5601"
export KIBANA_API_KEY="base64encodedapikey"

オプション 3: 基本認証

export KIBANA_URL="https://your-kibana:5601"
export KIBANA_USERNAME="elastic"
export KIBANA_PASSWORD="changeme"

オプション 4: start-local でのローカル開発

start-local を使用して Elasticsearch/Kibana をローカルで起動し、生成された .env をソースします:

curl -fsSL https://elastic.co/start-local | sh
source elastic-start-local/.env
export KIBANA_URL="$KB_LOCAL_URL"
export KIBANA_USERNAME="elastic"
export KIBANA_PASSWORD="$ES_LOCAL_PASSWORD"

その後、node scripts/kibana-dashboards.js test を実行して接続を確認してください。

オプション: TLS 検証をスキップ (開発のみ)

export KIBANA_INSECURE="true"

基本的なワークフロー

# 接続と API の可用性をテスト
node scripts/kibana-dashboards.js test

# ダッシュボード操作
node scripts/kibana-dashboards.js dashboard get <id>
echo '<json>' | node scripts/kibana-dashboards.js dashboard create -
echo '<json>' | node scripts/kibana-dashboards.js dashboard update <id> -
node scripts/kibana-dashboards.js dashboard delete <id>
echo '<json>' | node scripts/kibana-dashboards.js dashboard upsert <id> -

# 可視化操作 (スタンドアロン保存オブジェクト)
node scripts/kibana-dashboards.js vis list
node scripts/kibana-dashboards.js vis get <id>
echo '<json>' | node scripts/kibana-dashboards.js vis create -
echo '<json>' | node scripts/kibana-dashboards.js vis update <id> -
node scripts/kibana-dashboards.js vis delete <id>
echo '<json>' | node scripts/kibana-dashboards.js vis upsert <id> -

ダッシュボード API

ダッシュボード定義の構造

API は title と panels をルートレベルに持つフラットなリクエストボディを期待します。レスポンスはこれらを data エンベロープで id、meta、spaces とともにラップします。

{
  "title": "My Dashboard",
  "panels": [ ... ],
  "time_range": {
    "from": "now-24h",
    "to": "now"
  }
}

注: ダッシュボード ID は API によって自動生成されます。スクリプトはレガシーラップ形式 { id?, data: { title, panels }, spaces? } も受け入れ、自動的にアンラップします。

インライン可視化パネル付きダッシュボード (推奨)

自己完結で移植可能なダッシュボードについては、インライン定義 (config に直接プロパティがある) を使用してください:

{
  "title": "My Dashboard",
  "panels": [
    {
      "type": "vis",
      "id": "metric-panel",
      "grid": { "x": 0, "y": 0, "w": 12, "h": 6 },
      "config": {
        "title": "",
        "type": "metric",
        "data_source": { "type": "esql", "query": "FROM logs | STATS total = COUNT(*)" },
        "metrics": [{ "type": "primary", "column": "total", "label": "Total Count" }]
      }
    },
    {
      "type": "vis",
      "id": "chart-panel",
      "grid": { "x": 12, "y": 0, "w": 36, "h": 8 },
      "config": {
        "title": "Events Over Time",
        "type": "xy",
        "axis": {
          "x": { "scale": "temporal", "domain": { "type": "fit", "rounding": false } }
        },
        "layers": [
          {
            "type": "area",
            "data_source": {
              "type": "esql",
              "query": "FROM logs | WHERE @timestamp <= ?_tend AND @timestamp > ?_tstart | STATS count = COUNT(*) BY BUCKET(@timestamp, 75, ?_tstart, ?_tend)"
            },
            "x": { "column": "BUCKET(@timestamp, 75, ?_tstart, ?_tend)", "label": "@timestamp" },
            "y": [{ "column": "count" }]
          }
        ]
      }
    }
  ],
  "time_range": { "from": "now-24h", "to": "now" }
}

ダッシュボードグリッドシステム

ダッシュボードは 48列、無限行のグリッド を使用します。16:9 スクリーンでは、スクロールなしで約 20〜24 行 が表示されます。密度を考えて設計してください — 主な KPI とキートレンドをビューアブル領域上部に配置します。

幅	列	高さ	行	ユースケース
Full	48	Large	14-16	広い時系列、テーブル
Half	24	Standard	10-12	主要チャート
Quarter	12	Compact	5-6	KPI メトリクス
Sixth	8	Minimal	4-5	密集メトリクス行

目標: ビューアブル領域上部に 8〜12 パネル。マークダウンヘッダーを追加する代わりに、チャート自体に説明的なパネルタイトルを使用してください。

グリッド詰め方ルール:

• 死領域を排除: すべてのパネルの下部エッジ (y + h) を計算してください。新しい行を開始するか別のパネルの下にパネルを配置する場合、その y 座標は直上のパネルの y + h と正確に一致する必要があります。
• 行高さを揃える: 複数のパネルを横並びに配置する場合 (例: 同じ y 座標を共有)、通常は正確に同じ高さ (h) を持つべきです。そうでない場合、次のフルサイズパネルを配置する前に結果として生じる垂直空きスペースを埋める必要があります。

パネルスキーマ

{
  "type": "vis",
  "id": "unique-panel-id",
  "grid": { "x": 0, "y": 0, "w": 24, "h": 15 },
  "config": { ... }
}

プロパティ	型	必須	説明
type	string	Yes	埋め込み可能型 (例: vis, markdown, map)
id	string	No	一意のパネル ID (省略時は自動生成)
grid	object	Yes	位置とサイズ (x, y, w, h)
config	object	Yes	パネル固有の設定

可視化 API

サポートされているチャートタイプ

タイプ	説明	ES|QL サポート
metric	単一メトリクス値表示	Yes
xy	折れ線図、面グラフ、棒グラフ	Yes
gauge	ゲージ可視化	Yes
heatmap	ヒートマップ	Yes
tag_cloud	タグ/ワードクラウド	Yes
data_table	データテーブル	Yes
region_map	地域/コロプレス地図	Yes
pie, treemap, mosaic, waffle	分割チャート	Yes

注: ドーナツチャートを作成するには、pie を donut_hole として "s"、"m"、"l" (小、中、大) で設定してください。ソリッドパイの場合は "none" を使用してください。

データセットタイプ

可視化 API でサポートされている 3 種類のデータセットタイプがあります。各タイプはメトリクスと次元を指定するための異なるパターンを使用します。

データビューデータセット

集計操作で data_view_reference を使用します。Kibana は集計を自動的に実行します。

{
  "data_source": {
    "type": "data_view_reference",
    "ref_id": "90943e30-9a47-11e8-b64d-95841ca0b247"
  }
}

利用可能な操作: count、average、sum、max、min、unique_count、median、standard_deviation、percentile、percentile_rank、last_value、date_histogram、terms。詳細は チャートタイプリファレンス を参照してください。

ES|QL データセット

クエリ文字列で esql を使用します。出力列を { column: 'column_name' } で参照してください。

{
  "data_source": {
    "type": "esql",
    "query": "FROM logs | STATS count = COUNT(), avg_bytes = AVG(bytes) BY host"
  }
}

ES|QL 列参照パターン:

{ "column": "count" }

主な違い: ES|QL では、クエリ自体に集計を書いて、結果として得られた列を参照します。データビューでは、集計操作を指定し、Kibana がそれを実行します。

重要: ES|QL 可視化は /api/visualizations を使用して作成することはできません。Dashboard API を使用してダッシュボード内のインラインパネルとして作成する必要があります。

インデックスデータセット

保存されたデータビューなしでアドホックインデックスパターンに index を使用します:

{
  "data_source": {
    "type": "data_view_spec",
    "index_pattern": "logs-*",
    "time_field": "@timestamp"
  }
}

例

詳細なスキーマと各チャートタイプの全オプションについては、チャートタイプリファレンス を参照してください。

メトリクス (データビュー):

{
  "type": "metric",
  "data_source": { "type": "data_view_reference", "ref_id": "90943e30-9a47-11e8-b64d-95841ca0b247" },
  "metrics": [{ "type": "primary", "operation": "count", "label": "Total Requests" }]
}

メトリクス (ES|QL):

{
  "type": "metric",
  "data_source": { "type": "esql", "query": "FROM logs | STATS count = COUNT()" },
  "metrics": [{ "type": "primary", "column": "count", "label": "Total Requests" }]
}

XY 棒グラフ (データビュー):

{
  "title": "Top Hosts",
  "type": "xy",
  "axis": { "x": { "title": { "visible": false } }, "y": { "anchor": "start", "title": { "visible": false } } },
  "layers": [
    {
      "type": "bar_horizontal",
      "data_source": { "type": "data_view_reference", "ref_id": "90943e30-9a47-11e8-b64d-95841ca0b247" },
      "x": { "operation": "terms", "fields": ["host.keyword"], "limit": 10 },
      "y": [{ "operation": "count" }]
    }
  ]
}

XY 時系列 (ES|QL):

{
  "title": "Requests Over Time",
  "type": "xy",
  "axis": {
    "x": { "title": { "visible": false }, "scale": "temporal", "domain": { "type": "fit", "rounding": false } },
    "y": { "anchor": "start", "title": { "visible": false } }
  },
  "layers": [
    {
      "type": "line",
      "data_source": {
        "type": "esql",
        "query": "FROM logs | WHERE @timestamp <= ?_tend AND @timestamp > ?_tstart | STATS count = COUNT() BY BUCKET(@timestamp, 75, ?_tstart, ?_tend)"
      },
      "x": { "column": "BUCKET(@timestamp, 75, ?_tstart, ?_tend)", "label": "@timestamp" },
      "y": [{ "column": "count" }]
    }
  ]
}

ヒント: パネルタイトルが説明的な場合は、常に軸タイトルを非表示にしてください。長いラベルを持つカテゴリデータの場合は bar_horizontal を使用してください。軸設定には axis を使用してください。

完全なドキュメント

• ダッシュボード API リファレンス — ダッシュボードエンドポイントとスキーマ
• 可視化 API リファレンス — 可視化エンドポイント
• チャートタイプリファレンス — 各チャートタイプの詳細スキーマ
• 定義例 — すぐに使える定義

主要な例ファイル

assets/ から以下の形式で利用可能です: demo-dashboard.json、dashboard-with-visualizations.json、metric-esql.json、bar-chart-esql.json、line-chart-timeseries.json。

よくある問題

エラー	解決方法
"401 Unauthorized"	KIBANA_USERNAME/PASSWORD または KIBANA_API_KEY を確認してください
"404 Not Found"	ダッシュボード/可視化 ID が存在することを確認してください
"409 Conflict"	ダッシュボード/可視化が既に存在します。先に削除するか、更新を使用してください
スキーマ検証エラー	列名がクエリ出力と一致することを確認してください。ES|QL では { column: 'name' } を使用してください
メトリクスチャート構造	metrics 配列が必要: [{ type: 'primary', ... }]
XY チャート失敗	data_source を各レイヤーに入れます。axis (単数形) を使用してください
ref_id パネル欠落	ref_id ではなくインライン定義 (config 内のプロパティ) を使用してください

ガイドライン

1. 密度を設計する — 運用ダッシュボードはビューアブル領域上部 (最初の 24 行以内) に 8〜12 パネルを表示する必要があります。コンパクトなパネル高さを使用してください: メトリクスは h=4 〜 h=6 であり、チャートは h=8 〜 h=12 である必要があります。

2. タイトル/ヘッダーにマークダウンを使用しない — ダッシュボードタイトルまたはセクション区切りとして機能する markdown パネルを追加しないでください。これは重要な垂直スペースを浪費します。チャート自体に説明的なパネルタイトルを使用してください。

3. ビューアブル領域上部を優先 — 主な KPI とキートレンドを y=0 に配置する必要があります。詳細な分析とデータテーブルはチャートの下に配置してください。

4. 説明的なチャートタイトルを使用し、軸タイトルを非表示にしてください — チャートが何を表示しているかを説明するタイトルを記述してください (例: "応答コード別リクエスト")。優れたパネルタイトルは軸タイトルを冗長にします。常に axis.x.title.visible: false と axis.y.title.visible: false を設定してください。

5. 正しいデータセットタイプを選択 — シンプルな集計には data_view_reference を、複雑なクエリには esql を使用してください。

6. インライン定義 — 移植可能なダッシュボードについては、config.ref_id ではなく config 内のインラインプロパティを使用してください。

7. 接続をテストしてから — リソースを作成する前に node scripts/kibana-dashboards.js test を実行してください。

8. 既存の例を取得 — 異なるチャートタイプの正確なスキーマを確認するには vis get <id> を使用してください (CLI サブコマンドは vis です)。

9. 冗長なメトリクスラベルを避ける — ES|QL メトリクスの場合、パネルタイトルと内部メトリクスラベルの両方を使用しないでください。スペースを浪費します。パネル title を "" に設定し、バックティック (例: STATS `Total Requests` = COUNT() と "column": "Total Requests") を使用して ES|QL 列名をエイリアスすることで、人間が読める形式ラベルを設定してください。

10. 単位付きフォーマット番号 — メトリクスと y 軸列の format プロパティを使用して、生の数値の代わりに適切な単位を表示します。タイプ: bytes、bits、number、percent、duration、custom。例: "format": { "type": "bytes", "decimals": 0 }。完全なフォーマットテーブルについては チャートタイプリファレンス を参照してください。

スキーマの違い: データビュー vs ES|QL

側面	データビュー	ES|QL
データセット	{ type: 'data_view_reference', ref_id: '...' }	{ type: 'esql', query: '...' }
メトリクスチャート	metrics: [{ type: 'primary', operation: 'count' }]	metrics: [{ type: 'primary', column: 'col' }]
XY 列	{ operation: 'terms', fields: ['host'], limit: 10 }	{ column: 'host' }
静的値	{ operation: 'static_value', value: 100 }	クエリで EVAL を使用 (下記参照)
XY data_source	各レイヤー内	各レイヤー内
タグクラウド	tag_by: { operation: 'terms', ... }	tag_by: { column: '...' }
データテーブル	metrics、rows 配列	metrics、rows 配列 ({ column: '...' } を使用)

主要パターン: ES|QL では { column: 'column_name' } を使用してクエリ結果から列を参照します。集計はES|QL クエリ自体で行われます。すべてのデータソース設定に data_source を使用してください。

データソースタイプ: 保存されたデータビューには data_view_reference (ref_id を使用)、アドホックインデックスパターンには data_view_spec (index_pattern を使用)、ES|QL クエリには esql を使用してください。

ES|QL: 時間バケット処理

時系列チャートには BUCKET(@timestamp, n, ?_tstart, ?_tend) を使用してください。数値引数はターゲットバケット数です。Kibana は ?_tstart/?_tend を自動的に注入します。結果を再割り当てしないでください — BUCKET(@timestamp, 75, ?_tstart, ?_tend) の完全な式を BY 句と column 参照の両方として使用してください。"label" を設定して親切な表示名を提供してください:

"x": { "column": "BUCKET(@timestamp, 75, ?_tstart, ?_tend)", "label": "@timestamp" }

重要: 生のタイムスタンプラベルではなく適切なマルチレベルタイムアクス (例: "9th / April 2026 / 10th") を取得するには、x 軸で "scale": "temporal" を設定する必要があります:

"axis": {
  "x": { "scale": "temporal", "domain": { "type": "fit", "rounding": false } }
}

"scale": "temporal" がない場合、Kibana はバケット列をカテゴリテキストとして扱い、ソートされていない冗長なタイムスタンプ文字列をレンダリングします。

FROM logs | WHERE @timestamp <= ?_tend AND @timestamp > ?_tstart | STATS count = COUNT(*) BY BUCKET(@timestamp, 75, ?_tstart, ?_tend)

注: BUCKET(@timestamp, n, ?_tstart, ?_tend) には ?_tstart/?_tend 境界を持つ WHERE 句が必要です (Kibana はこれらを注入します)。または、BUCKET(@timestamp, 1 hour) を固定期間で使用してください — これはパラメータを必要としませんが、自動スケーリングされません。

ES|QL: 日付部分の抽出

ES|QL パート名 (SQL キーワードではない) で DATE_EXTRACT(part, date) を使用してください。パート文字列はダブルクォートで囲む必要があります。一般的なパート: "hour_of_day"、"day_of_week"、"day_of_month"、"month_of_year"、"year"、"day_of_year"。

FROM logs | STATS count = COUNT() BY hour = DATE_EXTRACT("hour_of_day", @timestamp), day = DATE_EXTRACT("day_of_week", @timestamp)

ES|QL: 静的/定数値の作成

ES|QL は static_value 操作をサポートしていません。代わりに、EVAL を使用して定数列を作成してください:

FROM logs | STATS count = COUNT() | EVAL max_value = 20000, goal = 15000

次に、{ "column": "max_value" } で参照します。動的参照値については、クエリで PERCENTILE() または MAX() などの集計関数を使用してください。

設計原則

API は次の原則に従います:

1. 最小限の定義 — 必須プロパティのみ。デフォルトは注入されます。
2. 実装詳細なし — 内部状態またはマシン ID なし
3. フラット構造 — diff が容易な浅いネスト
4. セマンティック名 — 明確で読みやすいプロパティ名
5. Git フレンドリー — バージョン管理での変更を追跡しやすい
6. LLM 最適化 — ワンショット生成に適したコンパクトフォーマット