kibana-vega

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Kibana Vega

Create and manage Kibana dashboards and Vega visualizations with ES|QL data sources.

使用ES|QL数据源创建和管理Kibana仪表板与Vega可视化。

Overview

概述

Vega is a declarative visualization grammar for creating custom charts in Kibana. Combined with ES|QL queries, it enables highly customized visualizations beyond standard Kibana charts.

Important Version Requirement: This skill strictly supports ES|QL data sources and requires Serverless Kibana or version 9.4+ (SNAPSHOT). It will not work reliably on older versions or with older Lucene/KQL data source definitions.

Vega是一种声明式可视化语法，用于在Kibana中创建自定义图表。结合ES|QL查询，它能够实现超出Kibana标准图表范围的高度定制化可视化效果。

重要版本要求： 本技能仅支持ES|QL数据源，且需要Serverless Kibana或9.4+版本（SNAPSHOT）。在旧版本或使用旧版Lucene/KQL数据源定义的环境中无法稳定运行。

Quick Start

快速开始

Environment Configuration

环境配置

Kibana connection is configured via environment variables. Run

node scripts/kibana-vega.js test

to verify the connection. If the test fails, suggest these setup options to the user, then stop. Do not try to explore further until a successful connection test.

Kibana连接通过环境变量配置。运行

node scripts/kibana-vega.js test

以验证连接。如果测试失败，请向用户建议以下设置选项，然后停止操作。在连接测试成功前，不要进行进一步操作。

Option 1: Elastic Cloud (recommended for production)

选项1：Elastic Cloud（生产环境推荐）

bash

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

bash

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

Option 2: Direct URL with API Key

选项2：带API Key的直接URL

bash

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

bash

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

Option 3: Basic Authentication

选项3：基础认证

bash

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

bash

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

Option 4: Local Development with start-local

选项4：使用start-local进行本地开发

For local development and testing, use start-local to quickly spin up Elasticsearch and Kibana using Docker or Podman:

bash

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

After installation completes, Elasticsearch runs at

http://localhost:9200

and Kibana at

http://localhost:5601

. The script generates a random password for the

elastic

user, stored in the

.env

file inside the created

elastic-start-local

folder.

To configure the environment variables for this skill, source the

.env

file and export the connection settings:

bash

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

Then run

node scripts/kibana-vega.js test

to verify the connection.

对于本地开发和测试，使用start-local通过Docker或Podman快速启动Elasticsearch和Kibana：

bash

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

安装完成后，Elasticsearch将运行在

http://localhost:9200

，Kibana运行在

http://localhost:5601

。脚本会为

elastic

用户生成随机密码，存储在创建的

elastic-start-local

文件夹内的

.env

文件中。

要为该技能配置环境变量，请加载

.env

文件并导出连接设置：

bash

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

以验证连接。

Optional: Skip TLS verification (development only)

可选：跳过TLS验证（仅开发环境）

bash

export KIBANA_INSECURE="true"

bash

export KIBANA_INSECURE="true"

Basic Workflow

基础工作流

bash

undefined

bash

undefined

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


**Note:** Use `-` as the file argument to read JSON from stdin. This enables direct spec creation without intermediate
files.

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


**注意：** 使用`-`作为文件参数以从标准输入读取JSON。这样无需中间文件即可直接创建规范。

Minimal Vega Spec with ES|QL

带ES|QL的最小Vega规范

IMPORTANT: Always use proper JSON format (not HJSON with triple quotes) to avoid parse errors.

json

{
  "$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" }
  }
}

重要提示：请始终使用标准JSON格式（不要使用带三重引号的HJSON），以避免解析错误。

json

{
  "$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 Data Source Options

ES|QL数据源选项

| Property | Description | | --------------------------- | ------------------------------------------ | --------- | |

%type%: "esql"

| Required. Use ES | QL parser | |

%context%: true

| Apply dashboard filters | |

%timefield%: "@timestamp"

| Enable time range with

?_tstart

?_tend

属性	描述
`%type%: "esql"`	必填项。使用ES
`%context%: true`	应用仪表板过滤器
`%timefield%: "@timestamp"`	启用带 `?_tstart` / `?_tend` 的时间范围筛选

Examples

示例

Stdin Examples

标准输入示例

bash

undefined

bash

undefined

Create visualization directly from JSON

直接从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> -

undefined

echo '{"panels":[{"visualization":"<id>","x":0,"y":0,"w":24,"h":10}]}' |
node scripts/kibana-vega.js dashboards apply-layout <dash-id> -

undefined

Dashboard Layout Design

仪表板布局设计

Grid System

网格系统

Kibana dashboards use a 48-column grid:

Width	Columns	Use Case
Full	48	Timelines, heatmaps, wide charts
Half	24	Side-by-side comparisons
Third	16	Three-column layouts
Quarter	12	KPI metrics, small summaries

Kibana仪表板使用48列网格：

宽度	列数	使用场景
全屏	48	时间线、热力图、宽幅图表
半屏	24	并排对比
三分之一屏	16	三列布局
四分之一屏	12	KPI指标、小型汇总面板

Above the Fold (Critical)

首屏区域（关键内容）

Primary information must be visible without scrolling.

Resolution	Visible Height	Layout Budget
1080p	~30 units	2 rows: h:10 + h:12
1440p	~40 units	3 rows: h:12 + h:12 + h:12

Height guidelines:

```
h: 10
```
— Compact bar charts (≤7 items), fits above fold
```
h: 12-13
```
— Standard charts, timelines
```
h: 15+
```
— Detailed views, use below fold

核心信息必须无需滚动即可查看。

分辨率	可见高度	布局预算
1080p	~30单位	2行：h:10 + h:12
1440p	~40单位	3行：h:12 + h:12 + h:12

高度指南：

```
h: 10
```
— 紧凑条形图（≤7个项目），适合首屏展示
```
h: 12-13
```
— 标准图表、时间线
```
h: 15+
```
— 详细视图，适合首屏下方

Layout Pattern: Operational Dashboard

布局模式：运营仪表板

text

┌───────────────────────┬───────────────────────┐  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
└───────────────────────┴───────────────────────┘

text

┌───────────────────────┬───────────────────────┐  y:0
│  当前状态A            │  当前状态B            │  h:10（紧凑）
├───────────────────────┴───────────────────────┤  y:10
│         主要时间线                          │  h:12（核心趋势）
├ ─ ─ ─ ─ ─ ─ ─ 首屏分割线 ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┤  y:22（1080p首屏底部）
│         次要时间线                          │  h:12（可在首屏下方）
├───────────────────────┬───────────────────────┤  y:34
│  补充内容1            │  补充内容2            │  h:10
└───────────────────────┴───────────────────────┘

Creating Layouts

创建布局

Option 1: Add panels with positions

选项1：添加带位置的面板

bash

undefined

bash

undefined

Row 1: Two compact half-width charts (above fold)

第1行：两个紧凑半宽图表（首屏）

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)

第2行：全屏时间线（首屏）

node scripts/kibana-vega.js dashboards add-panel $DASH $VIS3 --x 0 --y 10 --w 48 --h 12

Row 3: Below fold content

第3行：首屏下方内容

node scripts/kibana-vega.js dashboards add-panel $DASH $VIS4 --x 0 --y 22 --w 48 --h 12

undefined

node scripts/kibana-vega.js dashboards add-panel $DASH $VIS4 --x 0 --y 22 --w 48 --h 12

undefined

Option 2: Apply layout file

选项2：应用布局文件

Create

layout.json

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 }
  ]
}

Apply it:

bash

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

创建

layout.json

：

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 }
  ]
}

应用布局：

bash

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

Design Checklist

设计检查清单

Above the fold: Primary info in top ~22 height units (1080p)
Compact heights: Use h:10 for bar charts with ≤7 items
Prioritize: Most important info top-left
Group: Related charts side-by-side for comparison
Timelines: Full width (w:48), h:12 for compact
Below fold: Complementary/detailed panels OK to scroll

首屏展示：核心信息位于顶部约22高度单位内（1080p分辨率）
紧凑高度：对于项目数≤7的条形图，使用h:10
优先级：最重要的信息放在左上角
分组：相关图表并排摆放以便对比
时间线：全屏宽度（w:48），h:12以保持紧凑
首屏下方：补充/详细面板可放在需要滚动查看的区域

Guidelines

指南

Use JSON, not HJSON triple-quotes —
```
'''
```
multi-line strings cause parse errors in Kibana; use single-line queries with escaped quotes
```
\"
```
Rename dotted fields —
```
room.name
```
breaks Vega (interpreted as nested path); use ES|QL
```
RENAME room.name AS room
```

Don't set width/height — use

autosize: { type: fit, contains: padding }

Set labelLimit on axes — horizontal bar chart labels truncate; use
```
axis: { "labelLimit": 150 }
```
Sort bars by value — pre-sort in ES|QL with
```
SORT field DESC
```
and use
```
sort: null
```
in encoding (preserves data order); avoid
```
sort: "-x"
```
in layered specs (bar + text labels) as it causes "conflicting sort properties" warnings
Time axis: no rotated labels — use
```
axis: { "labelAngle": 0, "tickCount": 8 }
```
, let Vega auto-format dates
Descriptive titles replace axis titles — good title/subtitle makes axis titles redundant; use
```
title: null
```
on axes
Use color sparingly — color is a precious visual attribute; use a single default color (
```
#6092C0
```
) for bar charts where position already encodes value; reserve color encoding for categorical distinction (e.g., multiple lines in a time series)

Dark theme compatibility — always include config to avoid bright white borders:

json

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

使用JSON而非HJSON三重引号 —
```
'''
```
多行字符串会在Kibana中导致解析错误；请使用带转义引号
```
\"
```
的单行查询
重命名带点的字段 —
```
room.name
```
会破坏Vega（被解析为嵌套路径）；使用ES|QL的
```
RENAME room.name AS room
```
命令

不要设置宽高 — 使用

autosize: { type: fit, contains: padding }

在轴上设置labelLimit — 水平条形图标签会被截断；使用
```
axis: { "labelLimit": 150 }
```
按值对条形图排序 — 在ES|QL中使用
```
SORT field DESC
```
预先排序，并在编码中使用
```
sort: null
```
（保留数据顺序）；在分层规范（条形图+文本标签）中避免使用
```
sort: "-x"
```
，否则会出现“冲突的排序属性”警告
时间轴：不要旋转标签 — 使用
```
axis: { "labelAngle": 0, "tickCount": 8 }
```
，让Vega自动格式化日期
用描述性标题替代轴标题 — 好的标题/副标题会让轴标题变得多余；在轴上使用
```
title: null
```
谨慎使用颜色 — 颜色是宝贵的视觉属性；对于位置已能体现数值的条形图，使用单一默认颜色（
```
#6092C0
```
）；仅在需要区分类别时使用颜色编码（例如时间序列中的多条线）

深色主题兼容性 — 始终包含配置以避免亮白色边框：

json

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

CLI Commands

CLI命令

bash

undefined

bash

undefined

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>

undefined

undefined

Full Documentation

完整文档

Dashboard Layout Reference — Grid system, layout patterns, design best practices
Vega-Lite Reference — Complete Vega-Lite grammar, chart patterns, best practices
ES|QL in Vega Reference — ES|QL data source configuration, time filtering, parameters
Example Specs — Ready-to-use chart templates

仪表板布局参考 — 网格系统、布局模式、设计最佳实践
Vega-Lite参考 — 完整Vega-Lite语法、图表模式、最佳实践
Vega中的ES|QL参考 — ES|QL数据源配置、时间筛选、参数
示例规范 — 可直接使用的图表模板

Common Issues

常见问题

Error	Solution
"End of input while parsing an object"	Don't use HJSON `'''` triple-quotes; use JSON with single-line queries
Labels show "undefined"	Rename dotted fields: `RENAME room.name AS room`
Bars invisible / not rendering	Remove complex `scale.domain` , use simpler color schemes
Y-axis labels truncated	Add `axis: { "labelLimit": 150 }` to encoding
Panels stacked vertically	Use `--x --y --w --h` options or `apply-layout` command
"width/height ignored"	Remove dimensions, use `autosize`
Bright white borders on dark theme	Add `config: { "view": { "stroke": null }, "axis": { "domainColor": "#444", "tickColor": "#444" } }`
"401 Unauthorized"	Check KIBANA_USERNAME/PASSWORD
"conflicting sort properties"	Don't use `sort: "-x"` in layered specs; pre-sort in ES\|QL and use `sort: null`
"404 Not Found"	Verify dashboard/visualization ID

错误信息	解决方案
"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
"404 Not Found"	验证仪表板/可视化ID是否正确