kibana-vega

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：API Key を使用した直接 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 を使用して、Docker または Podman で Elasticsearch と Kibana をすばやく起動します。

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

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

このスキルの環境変数を設定するには、.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"

基本的なワークフロー

# Test connection
node scripts/kibana-vega.js test

# Create visualization directly from stdin (no intermediate file needed)
echo '<json-spec>' | node scripts/kibana-vega.js visualizations create "My Chart" -

# Get visualization spec for review/modification
node scripts/kibana-vega.js visualizations get <vis-id>

# Update visualization from stdin
echo '<json-spec>' | node scripts/kibana-vega.js visualizations update <vis-id> -

# Create dashboard
node scripts/kibana-vega.js dashboards create "My Dashboard"

# Add visualization with grid position
node scripts/kibana-vega.js dashboards add-panel <dashboard-id> <vis-id> --x 0 --y 0 --w 24 --h 15

# Apply a complete layout from stdin
echo '<layout-json>' | node scripts/kibana-vega.js dashboards apply-layout <dashboard-id> -

注： ファイル引数に - を指定すると、標準入力から 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 で時間範囲を有効化 |

例

標準入力の例

# Create visualization directly from JSON
echo '{"$schema":"https://vega.github.io/schema/vega-lite/v6.json",...}' | \
  node scripts/kibana-vega.js visualizations create "My Chart" -

# Update visualization
echo '{"$schema":...}' | node scripts/kibana-vega.js visualizations update <id> -

# Apply layout directly
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 (compact)
├───────────────────────┴───────────────────────┤  y:10
│         Primary Timeline                      │  h:12 (main trend)
├ ─ ─ ─ ─ ─ ─ ─ FOLD ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┤  y:22 (1080p fold)
│         Secondary Timeline                    │  h:12 (below fold OK)
├───────────────────────┬───────────────────────┤  y:34
│  Complementary 1      │  Complementary 2      │  h:10
└───────────────────────┴───────────────────────┘

レイアウトの作成

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

# Row 1: Two compact half-width charts (above fold)
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

# Row 2: Full-width timeline (above fold)
node scripts/kibana-vega.js dashboards add-panel $DASH $VIS3 --x 0 --y 10 --w 48 --h 12

# Row 3: Below fold content
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. ファーストビューより下：補足情報や詳細パネルはスクロール可能な場所に配置してもかまいません

ガイドライン

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

2. ドット付きフィールド名を変更する — room.name は Vega で問題が発生します（ネストされたパスとして解釈されるため）。ES|QL の RENAME room.name AS room を使用してください

3. width/height を設定しない — autosize: { type: fit, contains: padding } を使用してください

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

5. 値で棒を並べ替える — ES|QL で SORT field DESC を使って事前に並べ替え、エンコーディングで sort: null を指定します（データの順序が維持されます）。レイヤー仕様（棒＋テキストラベル）では sort: "-x" を使用しないでください。「conflicting sort properties」警告が発生します

6. 時間軸：ラベルを回転させない — axis: { "labelAngle": 0, "tickCount": 8 } を使用し、日付の書式設定は Vega に任せてください

7. 軸タイトルの代わりに説明的なタイトルを使う — タイトルやサブタイトルが適切であれば、軸タイトルは不要です。軸には title: null を指定してください

8. 色は控えめに使う — 色は貴重な視覚属性です。位置で値を表現できる棒グラフでは、単一のデフォルト色（#6092C0）を使用してください。色によるエンコーディングは、カテゴリの区別（例：時系列の複数の線）に使います

9. ダークテーマとの互換性 — 明るい白の境界線を避けるため、必ず設定を含めてください：

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

CLI コマンド

# Dashboards
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|->

# Visualizations (use - for stdin instead of file)
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 を確認してください