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

注意： 将 - 用作文件参数，可从 stdin 读取 JSON。这样无需中间文件即可直接创建 spec。

最小化的 ES|QL Vega Spec

重要： 始终使用规范的 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 示例

# 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	并排对比
三分之一	16	三列布局
四分之一	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. 使用 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 命令

# 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 数据源配置、时间过滤、参数
• 示例规格 — 可直接使用的图表模板

常见问题

错误	解决方案
"解析对象时遇到输入结束"	不要使用 HJSON ''' 三引号；请使用带单行查询的 JSON
标签显示为 "undefined"	重命名带点的字段：RENAME room.name AS room
柱状图不可见／未渲染	移除复杂的 scale.domain，使用更简单的配色方案
Y 轴标签被截断	在编码中添加 axis: { "labelLimit": 150 }
面板纵向堆叠	使用 --x --y --w --h 选项或 apply-layout 命令
"width/height 被忽略"	移除尺寸设置，使用 autosize
深色主题下出现亮白色边框	添加 config: { "view": { "stroke": null }, "axis": { "domainColor": "#444", "tickColor": "#444" } }
"401 Unauthorized"	检查 KIBANA_USERNAME/PASSWORD
"排序属性冲突"	不要在分层规格中使用 sort: "-x"；在 ES|QL 中预先排序并使用 sort: null
"404 Not Found"	验证仪表板／可视化 ID