Kibana Vega

ES|QL データソースを使用して Kibana ダッシュボードと Vega ビジュアライゼーションを作成および管理します。

概要

Vega は Kibana でカスタム チャートを作成するための宣言型ビジュアライゼーション グラマーです。ES|QL クエリと組み合わせることで、標準の Kibana チャートを超えた高度にカスタマイズされたビジュアライゼーションが可能になります。

重要なバージョン要件: このスキルは ES|QL データソース を厳密にサポートしており、Serverless Kibana またはバージョン 9.4+ (SNAPSHOT) が必要です。古いバージョンまたは古い Lucene/KQL データソース定義では確実に動作しません。

クイック スタート

環境設定

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

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

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

オプション 2: URL と API キーで直接接続

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

オプション 3: Basic 認証

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

オプション 4: start-local を使用したローカル開発

ローカル開発およびテストの場合は、start-local を使用して Docker または Podman で Elasticsearch と Kibana をすばやく起動します:

curl -fsSL https://elastic.co/start-local | sh

インストール完了後、Elasticsearch は http://localhost:9200 で実行され、Kibana は http://localhost:5601 で実行されます。スクリプトは作成された elastic-start-local フォルダ内の .env ファイルに保存される elastic ユーザー用のランダム パスワードを生成します。

このスキルの環境変数を設定するには、.env ファイルをソースして接続設定をエクスポートします:

source elastic-start-local/.env
export KIBANA_URL="$KB_LOCAL_URL"
export KIBANA_USERNAME="elastic"
export KIBANA_PASSWORD="$ES_LOCAL_PASSWORD"

次に node scripts/kibana-vega.js test を実行して接続を確認します。

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

export KIBANA_INSECURE="true"

基本的なワークフロー

# 接続をテスト
node scripts/kibana-vega.js test

# 中間ファイルなしで stdin から直接ビジュアライゼーションを作成
echo '<json-spec>' | node scripts/kibana-vega.js visualizations create "My Chart" -

# レビュー/修正用にビジュアライゼーション仕様を取得
node scripts/kibana-vega.js visualizations get <vis-id>

# stdin からビジュアライゼーションを更新
echo '<json-spec>' | node scripts/kibana-vega.js visualizations update <vis-id> -

# ダッシュボードを作成
node scripts/kibana-vega.js dashboards create "My Dashboard"

# グリッド位置を指定してビジュアライゼーションを追加
node scripts/kibana-vega.js dashboards add-panel <dashboard-id> <vis-id> --x 0 --y 0 --w 24 --h 15

# stdin から完全なレイアウトを適用
echo '<layout-json>' | node scripts/kibana-vega.js dashboards apply-layout <dashboard-id> -

注: ファイル引数として - を使用して stdin から JSON を読み込みます。これにより、中間ファイルなしで直接仕様を作成できます。

ES|QL を使用した最小限の Vega 仕様

重要: パースエラーを回避するため、常に適切な JSON 形式 (トリプルクォートを含む HJSON ではない) を使用してください。

{
  "$schema": "https://vega.github.io/schema/vega-lite/v6.json",
  "title": "My Chart",
  "autosize": { "type": "fit", "contains": "padding" },

  "config": {
    "axis": { "domainColor": "#444", "tickColor": "#444" },
    "view": { "stroke": null }
  },

  "data": {
    "url": {
      "%type%": "esql",
      "query": "FROM logs-* | STATS count = COUNT() BY status | RENAME status AS category"
    }
  },

  "mark": { "type": "bar", "color": "#6092C0" },
  "encoding": {
    "x": { "field": "category", "type": "nominal" },
    "y": { "field": "count", "type": "quantitative" }
  }
}

ES|QL データソース オプション

プロパティ	説明
%type%: "esql"	必須。ES|QL パーサーを使用
%context%: true	ダッシュボード フィルターを適用
%timefield%: "@timestamp"	?_tstart/?_tend で時間範囲を有効化

例

Stdin の例

# JSON から直接ビジュアライゼーションを作成
echo '{"$schema":"https://vega.github.io/schema/vega-lite/v6.json",...}' | \
  node scripts/kibana-vega.js visualizations create "My Chart" -

# ビジュアライゼーションを更新
echo '{"$schema":...}' | node scripts/kibana-vega.js visualizations update <id> -

# レイアウトを直接適用
echo '{"panels":[{"visualization":"<id>","x":0,"y":0,"w":24,"h":10}]}' | \
  node scripts/kibana-vega.js dashboards apply-layout <dash-id> -

ダッシュボード レイアウト設計

グリッド システム

Kibana ダッシュボードは 48 列グリッド を使用します:

幅	列	ユースケース
フル	48	タイムライン、ヒートマップ、広いチャート
半分	24	並べた比較
3 分の 1	16	3 列レイアウト
4 分の 1	12	KPI メトリクス、小さなサマリー

ファビコン (重要)

主な情報はスクロール不要で表示可能である必要があります。

解像度	表示高さ	レイアウト予算
1080p	~30 ユニット	2 行: h:10 + h:12
1440p	~40 ユニット	3 行: h:12 + h:12 + h:12

高さのガイドライン:

• h: 10 — コンパクト棒グラフ (≤7 アイテム)、ファビコン内に収まる
• h: 12-13 — 標準チャート、タイムライン
• h: 15+ — 詳細ビュー、ファビコン下でスクロール可能

レイアウト パターン: 運用ダッシュボード

┌───────────────────────┬───────────────────────┐  y:0
│  Current State A      │  Current State B      │  h:10 (コンパクト)
├───────────────────────┴───────────────────────┤  y:10
│         Primary Timeline                      │  h:12 (メイン トレンド)
├ ─ ─ ─ ─ ─ ─ ─ FOLD ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┤  y:22 (1080p フォルド)
│         Secondary Timeline                    │  h:12 (ファビコン下で OK)
├───────────────────────┬───────────────────────┤  y:34
│  Complementary 1      │  Complementary 2      │  h:10
└───────────────────────┴───────────────────────┘

レイアウトの作成

オプション 1: 位置を指定してパネルを追加

# 行 1: 2 つのコンパクト半幅チャート (ファビコン上)
node scripts/kibana-vega.js dashboards add-panel $DASH $VIS1 --x 0 --y 0 --w 24 --h 10
node scripts/kibana-vega.js dashboards add-panel $DASH $VIS2 --x 24 --y 0 --w 24 --h 10

# 行 2: フル幅タイムライン (ファビコン上)
node scripts/kibana-vega.js dashboards add-panel $DASH $VIS3 --x 0 --y 10 --w 48 --h 12

# 行 3: ファビコン下のコンテンツ
node scripts/kibana-vega.js dashboards add-panel $DASH $VIS4 --x 0 --y 22 --w 48 --h 12

オプション 2: レイアウト ファイルを適用

layout.json を作成:

{
  "title": "My Dashboard",
  "panels": [
    { "visualization": "<vis-id-1>", "x": 0, "y": 0, "w": 24, "h": 10 },
    { "visualization": "<vis-id-2>", "x": 24, "y": 0, "w": 24, "h": 10 },
    { "visualization": "<vis-id-3>", "x": 0, "y": 10, "w": 48, "h": 12 },
    { "visualization": "<vis-id-4>", "x": 0, "y": 22, "w": 48, "h": 12 }
  ]
}

これを適用します:

node scripts/kibana-vega.js dashboards apply-layout <dashboard-id> layout.json

デザイン チェックリスト

1. ファビコン上: 主な情報を上部 ~22 高さユニット内に配置 (1080p)
2. コンパクト高さ: ≤7 アイテムの棒グラフに h:10 を使用
3. 優先順位付け: 最も重要な情報を左上に配置
4. グループ化: 関連チャートを並べて比較するために配置
5. タイムライン: フル幅 (w:48)、コンパクトに h:12
6. ファビコン下: 補足/詳細パネルはスクロール OK

ガイドライン

1. JSON を使用、HJSON トリプルクォートは使用しない — ''' 複数行文字列は Kibana でパースエラーを引き起こします。エスケープされたクォート \" で単一行クエリを使用してください

2. ドット付きフィールドの名前を変更 — room.name は Vega を破損します (ネストされたパスとして解釈されます)。ES|QL の RENAME room.name AS room を使用してください

3. 幅/高さを設定しない — autosize: { type: fit, contains: padding } を使用

4. 軸に labelLimit を設定 — 横棒グラフラベルが切り詰められます。axis: { "labelLimit": 150 } を使用してください

5. 棒を値で並べ替え — ES|QL で SORT field DESC で事前ソートし、エンコードで sort: null を使用 (データ順序を保持します)。レイヤー化された仕様 (棒 + テキスト ラベル) で sort: "-x" を使用しないでください (「競合する並べ替えプロパティ」警告を引き起こします)

6. 時間軸: ラベルを回転させない — axis: { "labelAngle": 0, "tickCount": 8 } を使用し、Vega 自動フォーマット日付を使用します

7. 説明的なタイトルで軸タイトルを置き換える — 良いタイトル/サブタイトルは軸タイトルを不要にします。軸で title: null を使用してください

8. 色を控えめに使用 — 色は貴重なビジュアル属性です。位置がすでに値をエンコードしている棒グラフでは単一のデフォルト色 (#6092C0) を使用します。色エンコードを時系列の複数行など、カテゴリ区別に予約します

9. ダーク テーマの互換性 — 明るい白いボーダーを回避するため、常に設定を含めます:

   "config": {
     "axis": { "domainColor": "#444", "tickColor": "#444" },
     "view": { "stroke": null }
   }
   

CLI コマンド

# ダッシュボード
node scripts/kibana-vega.js dashboards list [search]
node scripts/kibana-vega.js dashboards get <id>
node scripts/kibana-vega.js dashboards create <title>
node scripts/kibana-vega.js dashboards delete <id>
node scripts/kibana-vega.js dashboards add-panel <dash-id> <vis-id> [--x N] [--y N] [--w N] [--h N]
node scripts/kibana-vega.js dashboards apply-layout <dash-id> <file|->

# ビジュアライゼーション (ファイルの代わりに stdin に - を使用)
node scripts/kibana-vega.js visualizations list [vega]
node scripts/kibana-vega.js visualizations get <id>
node scripts/kibana-vega.js visualizations create <title> <file|->
node scripts/kibana-vega.js visualizations update <id> <file|->
node scripts/kibana-vega.js visualizations delete <id>

完全なドキュメント

• ダッシュボード レイアウト リファレンス — グリッド システム、レイアウト パターン、デザイン ベスト プラクティス
• Vega-Lite リファレンス — 完全な Vega-Lite グラマー、チャート パターン、ベスト プラクティス
• Vega の ES|QL リファレンス — ES|QL データソース設定、時間フィルタリング、パラメータ
• 仕様例 — すぐに使用できるチャート テンプレート

一般的な問題

エラー	解決方法
"End of input while parsing an object"	HJSON ''' トリプルクォートを使用しないでください。JSON で単一行クエリを使用してください
ラベルに "undefined" と表示される	ドット付きフィールドの名前を変更: RENAME room.name AS room
棒が見えない/レンダリングされない	複雑な scale.domain を削除し、よりシンプルな配色スキームを使用してください
Y 軸ラベルが切り詰められている	エンコードに axis: { "labelLimit": 150 } を追加
パネルが垂直にスタック	--x --y --w --h オプションまたは apply-layout コマンドを使用
"width/height ignored"	ディメンションを削除し、autosize を使用
ダーク テーム上に明るい白いボーダー	config: { "view": { "stroke": null }, "axis": { "domainColor": "#444", "tickColor": "#444" } } を追加
"401 Unauthorized"	KIBANA_USERNAME/PASSWORD を確認してください
"conflicting sort properties"	レイヤー化された仕様で sort: "-x" を使用しないでください。ES|QL で事前ソートし、sort: null を使用
"404 Not Found"	ダッシュボード/ビジュアライゼーション ID を確認してください