Kibana 仪表板 API 使用指南：声明式可视化与 GitOps 工作流

kibana-dashboards by elastic/agent-skills

276 周安装量

293 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/elastic/agent-skills --skill kibana-dashboards

数据可视化数据分析开发运维

🇨🇳中文介绍

Kibana 仪表板和可视化

概述

Kibana 仪表板和可视化 API 提供了一种声明式的、对 Git 友好的格式，用于定义仪表板和可视化。定义内容简洁、可差异化比较，并适用于版本控制和 LLM 辅助生成。

主要优势：

最小化负载（不包含实现细节或可推导的属性）
易于在 Git 中进行差异比较
GitOps 工作流的一致模式
专为 LLM 一次性生成设计
通过 OpenAPI 规范进行稳健验证

版本要求： Kibana 9.4+ (SNAPSHOT)

重要注意事项

内联定义与已保存对象引用： 在仪表板中嵌入 Lens 面板时，优先使用内联的 attributes 定义，而不是 savedObjectId 引用。内联定义更可靠且自包含。

快速开始

环境配置

Kibana 连接通过环境变量配置。运行 node scripts/kibana-dashboards.js test 来验证连接。如果测试失败，向用户建议这些设置选项，然后停止。在连接测试成功之前，不要尝试进一步探索。

选项 1: Elastic Cloud (生产环境推荐)

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

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

仪表板定义结构

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? } 并会自动解包。

echo '{
  "title": "Sales Dashboard",
  "panels": [],
  "time_range": { "from": "now-7d", "to": "now" }
}' | node scripts/kibana-dashboards.js dashboard create -

echo '{
  "title": "Updated Dashboard Title",
  "panels": [ ... ]
}' | node scripts/kibana-dashboards.js dashboard update my-dashboard-id -

包含内联 Lens 面板的仪表板（推荐）

使用内联 attributes 来创建自包含、可移植的仪表板：

{
  "title": "My Dashboard",
  "panels": [
    {
      "type": "lens",
      "uid": "metric-panel",
      "grid": { "x": 0, "y": 0, "w": 12, "h": 6 },
      "config": {
        "attributes": {
          "title": "",
          "type": "metric",
          "dataset": { "type": "esql", "query": "FROM logs | STATS total = COUNT(*)" },
          "metrics": [{ "type": "primary", "operation": "value", "column": "total", "label": "Total Count" }]
        }
      }
    },
    {
      "type": "lens",
      "uid": "chart-panel",
      "grid": { "x": 12, "y": 0, "w": 36, "h": 8 },
      "config": {
        "attributes": {
          "title": "Events Over Time",
          "type": "xy",
          "layers": [
            {
              "type": "area",
              "dataset": {
                "type": "esql",
                "query": "FROM logs | STATS count = COUNT(*) BY bucket = BUCKET(@timestamp, 75, ?_tstart, ?_tend)"
              },
              "x": { "operation": "value", "column": "bucket" },
              "y": [{ "operation": "value", "column": "count" }]
            }
          ]
        }
      }
    }
  ],
  "time_range": { "from": "now-24h", "to": "now" }
}

在空间/集群之间复制仪表板

# 1. 从源获取仪表板
node scripts/kibana-dashboards.js dashboard get source-dashboard > dashboard.json

# 2. 编辑 dashboard.json 以更改 id 和/或 spaces

# 3. 在目标上创建
node scripts/kibana-dashboards.js dashboard create dashboard.json

仪表板网格系统

仪表板使用 48 列、无限行网格。在 16:9 屏幕上，大约 20-24 行 无需滚动即可见。为密度而设计——将主要 KPI 和关键趋势放在首屏可见区域。

宽度	列数	高度	行数	使用场景
全宽	48	大	14-16	宽时间序列、表格
半宽	24	标准	10-12	主要图表
四分之一宽	12	紧凑	5-6	KPI 指标
六分之一宽	8	最小	4-5	密集指标行

目标： 首屏显示 8-12 个面板。在图表本身上使用描述性的面板标题，而不是添加 Markdown 标题。

网格填充规则：

消除空白区域： 始终计算每个面板的底边 (y + h)。当开始新的一行或将面板放置在另一个面板下方时，其 y 坐标必须与紧邻其上方面板的 y + h 完全匹配。
对齐行高： 如果多个面板并排放置在一行中（例如，共享相同的 y 坐标），它们通常应具有完全相同的高度 (h)。如果高度不同，则必须在放置下一个全宽面板之前填充由此产生的垂直空白区域。

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

属性	类型	必需	描述
`type`	字符串	是	可嵌入类型（例如，`lens`、`visualization`、`map`）
`uid`	字符串	否	唯一面板 ID（如果省略则自动生成）
`grid`	对象	是	位置和大小 (`x`, `y`, `w`, `h`)
`config`	对象	是	面板特定配置

支持的图表类型

类型 | 描述 | ES|QL 支持
---|---|---
metric | 单一指标值显示 | 是
xy | 折线图、面积图、柱状图 | 是
gauge | 仪表盘可视化 | 是
heatmap | 热力图 | 是
tagcloud | 标签/词云 | 是
datatable | 数据表格 | 是
region_map | 区域/等值区域地图 | 是
pie, donut, treemap, mosaic, waffle | 分区图表 | 是

Lens API 支持三种数据集类型。每种类型使用不同的模式来指定指标和维度。

数据视图数据集

使用带有聚合操作的 dataView。Kibana 会自动执行聚合。

{
  "dataset": {
    "type": "dataView",
    "id": "90943e30-9a47-11e8-b64d-95841ca0b247"
  }
}

可用的聚合操作（用于 dataView）：

操作	描述	需要字段
`count`	文档计数	否
`average`	平均值	是
`sum`	值总和	是
`max`	最大值	是
`min`	最小值	是
`unique_count`	基数	是
`median`	中位数	是
`standard_deviation`	标准差	是
`percentile`	百分位数（带 `percentile` 参数）	是
`percentile_rank`	百分位排名（带 `rank` 参数）	是
`last_value`	最后值（带 `sort_by` 字段）	是
`date_histogram`	时间桶（用于 x 轴）	是
`terms`	最高值（用于 x 轴/细分）	是

使用带有查询字符串的 esql。使用 { operation: 'value', column: 'column_name' } 引用输出列。

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

ES|QL 列引用模式：

{
  "operation": "value",
  "column": "count"
}

关键区别： 使用 ES|QL 时，您在查询本身中编写聚合，然后引用结果列。使用 dataView 时，您指定聚合操作，Kibana 执行它。

使用 index 来处理没有已保存数据视图的临时索引模式：

{
  "dataset": {
    "type": "index",
    "index": "logs-*",
    "time_field": "@timestamp"
  }
}

有关详细模式和所有图表类型选项，请参阅图表类型参考。

指标图表 (dataView)：

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

指标图表 (ES|QL)：

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

XY 柱状图 (dataView)：

{
  "title": "Top Hosts",
  "type": "xy",
  "axis": { "x": { "title": { "visible": false } }, "left": { "title": { "visible": false } } },
  "layers": [
    {
      "type": "bar_horizontal",
      "dataset": { "type": "dataView", "id": "90943e30-9a47-11e8-b64d-95841ca0b247" },
      "x": { "operation": "terms", "fields": ["host.keyword"], "size": 10 },
      "y": [{ "operation": "count" }]
    }
  ]
}

XY 时间序列 (ES|QL)：

{
  "title": "Requests Over Time",
  "type": "xy",
  "axis": { "x": { "title": { "visible": false } }, "left": { "title": { "visible": false } } },
  "layers": [
    {
      "type": "line",
      "dataset": {
        "type": "esql",
        "query": "FROM logs | STATS count = COUNT() BY bucket = BUCKET(@timestamp, 75, ?_tstart, ?_tend)"
      },
      "x": { "operation": "value", "column": "bucket" },
      "y": [{ "operation": "value", "column": "count" }]
    }
  ]
}

提示： 当面板标题具有描述性时，始终隐藏坐标轴标题。对于带有长标签的分类数据，使用 bar_horizontal。

仪表板 API 参考 — 仪表板端点和模式
Lens API 参考 — Lens 可视化端点
图表类型参考 — 每种图表类型的详细模式
示例定义 — 可直接使用的定义

assets/demo-dashboard.json — 包含内联 Lens 面板的完整仪表板（dataView 格式）
assets/dashboard-with-lens.json — 包含 ES|QL 格式的仪表板（供未来参考）
assets/metric-esql.json — 独立的指标可视化
assets/bar-chart-esql.json — 柱状图示例
assets/line-chart-timeseries.json — 时间序列折线图

错误	解决方案
"401 未授权"	检查 KIBANA_USERNAME/PASSWORD 或 KIBANA_API_KEY
"404 未找到"	确认仪表板/可视化 ID 存在
"409 冲突"	具有该 ID 的仪表板/可视化已存在；先删除或使用更新
"PUT 中不允许 id"	从更新请求体中移除 `id` 和 `spaces`
模式验证错误	对于 ES
ES	QL 缺少 `operation`
指标图表使用 `metric` 而非 `metrics`	指标图表需要 `metrics`（复数）数组：`[{ type: 'primary', operation: '...' }]`
词云使用 `tag` 而非 `tag_by`	词云需要 `tag_by`，而不是 `tag`
数据表使用 `columns`	ES
XY 图表失败	将 `dataset` 放在每个图层内部（对于 dataView 和 ES
热力图属性名称	使用 `xAxis`、`yAxis`、`metric`（而不是 `x`、`y`、`value`）
savedObjectId 面板缺失	优先使用内联 `attributes` 定义，而不是 savedObjectId

为密度而设计 — 操作仪表板必须在首屏（前 24 行内）显示 8-12 个面板。使用紧凑的面板高度：指标面板必须是 h=4 到 h=6，图表面板必须是 h=8 到 h=12。
切勿使用 Markdown 作为标题/页眉 — 不要添加 DASHBOARD_MARKDOWN 面板来充当仪表板标题或部分分隔符。这会浪费关键的垂直空间。在图表本身上使用描述性的面板标题。
优先考虑首屏内容 — 主要 KPI 和关键趋势必须放置在 y=0。深度分析和数据表格应放在图表下方。
使用描述性的图表标题 — 编写能解释图表显示内容的标题（例如，“按产品类别的收入”）。使用 axis.x.title.visible: false 隐藏坐标轴标签以减少杂乱
选择正确的数据集类型 — 对于简单聚合，使用 dataView；对于包含连接、转换或自定义逻辑的复杂查询，使用 esql
内联 Lens 定义 — 对于可移植的仪表板，优先使用 config.attributes 而不是 config.savedObjectId
首先测试连接 — 在创建资源之前运行 node scripts/kibana-dashboards.js test
获取现有示例 — 使用 lens get <id> 查看不同图表类型的精确模式
避免冗余的指标标签 — 对于 ES|QL 指标，避免同时使用面板标题和内部指标标签，这会浪费空间。将面板 title 设置为 ""，并通过使用反引号为 ES|QL 列名设置别名来配置人类可读的标签（例如，STATS Total Requests = COUNT() 和 "column": "Total Requests"）。

模式差异：dataView 与 ES|QL

方面 | dataView | ES|QL
---|---|---
数据集 | { type: 'dataView', id: '...' } | { type: 'esql', query: '...' }
指标图表 | metrics: [{ type: 'primary', operation: 'count' }] | metrics: [{ type: 'primary', operation: 'value', column: 'col' }]
XY 列 | { operation: 'terms', fields: ['host'], size: 10 } | { operation: 'value', column: 'host' }
静态值 | { operation: 'static_value', value: 100 } | 在查询中使用 EVAL（见下文）
XY 数据集 | 在每个图层内部 | 在每个图层内部
词云 | tag_by: { operation: 'terms', ... } | tag_by: { operation: 'value', column: '...' }
数据表属性 | metrics、rows 数组 | metrics、rows 数组，包含 { operation: 'value', column: '...' }

关键模式： ES|QL 始终使用 { operation: 'value', column: 'column_name' } 来引用查询结果中的列。聚合发生在 ES|QL 查询本身中。

ES|QL：时间分桶

对于时间序列图表，使用 BUCKET 函数创建“自动”桶，这些桶会根据时间范围自动缩放。始终使用 BUCKET(@timestamp, 75, ?_tstart, ?_tend)，而不是像 DATE_TRUNC(1 hour, @timestamp) 这样的硬编码间隔：

FROM logs | STATS count = COUNT() BY bucket = BUCKET(@timestamp, 75, ?_tstart, ?_tend)

ES|QL：创建静态/常量值

ES|QL 不支持 static_value 操作。相反，使用 EVAL 创建常量列：

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

然后使用 { "operation": "value", "column": "max_value" } 引用。对于动态参考值，在查询中使用像 PERCENTILE() 或 MAX() 这样的聚合函数。

这些 API 遵循以下原则：

最小化定义 — 仅包含必需属性；默认值被注入
不包含实现细节 — 不包含内部状态或机器 ID
扁平结构 — 浅层嵌套，便于差异比较
语义化名称 — 清晰、可读的属性名称
对 Git 友好 — 易于在版本控制中跟踪更改
针对 LLM 优化 — 紧凑的格式，适合一次性生成

🇺🇸English

Kibana Dashboards and Visualizations

Overview

The Kibana dashboards and visualizations APIs provide a declarative, Git-friendly format for defining dashboards and visualizations. Definitions are minimal, diffable, and suitable for version control and LLM-assisted generation.

Key Benefits:

Minimal payloads (no implementation details or derivable properties)
Easy to diff in Git
Consistent patterns for GitOps workflows
Designed for LLM one-shot generation
Robust validation via OpenAPI spec

Version Requirement: Kibana 9.4+ (SNAPSHOT)

Important Caveats

Inline vs Saved Object References: When embedding Lens panels in dashboards, prefer inline attributes definitions over savedObjectId references. Inline definitions are more reliable and self-contained.

Quick Start

Environment Configuration

Kibana connection is configured via environment variables. Run node scripts/kibana-dashboards.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.

Option 1: Elastic Cloud (recommended for production)

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

Option 2: Direct URL with API Key

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

Option 3: Basic Authentication

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

Option 4: Local Development with start-local

Use start-local to spin up Elasticsearch/Kibana locally, then source the generated .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"

Then run node scripts/kibana-dashboards.js test to verify the connection.

Optional: Skip TLS verification (development only)

export KIBANA_INSECURE="true"

Basic Workflow

# Test connection and API availability
node scripts/kibana-dashboards.js test

# Dashboard operations
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>

# Lens visualization operations
node scripts/kibana-dashboards.js lens list
node scripts/kibana-dashboards.js lens get <id>
echo '<json>' | node scripts/kibana-dashboards.js lens create -
echo '<json>' | node scripts/kibana-dashboards.js lens update <id> -
node scripts/kibana-dashboards.js lens delete <id>

Dashboards API

Dashboard Definition Structure

The API expects a flat request body with title and panels at the root level. The response wraps these in a data envelope alongside id, meta, and spaces.

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

Note: Dashboard IDs are auto-generated by the API. The script also accepts the legacy wrapped format { id?, data: { title, panels }, spaces? } and unwraps it automatically.

Create Dashboard

echo '{
  "title": "Sales Dashboard",
  "panels": [],
  "time_range": { "from": "now-7d", "to": "now" }
}' | node scripts/kibana-dashboards.js dashboard create -

Update Dashboard

echo '{
  "title": "Updated Dashboard Title",
  "panels": [ ... ]
}' | node scripts/kibana-dashboards.js dashboard update my-dashboard-id -

Dashboard with Inline Lens Panels (Recommended)

Use inline attributes for self-contained, portable dashboards:

{
  "title": "My Dashboard",
  "panels": [
    {
      "type": "lens",
      "uid": "metric-panel",
      "grid": { "x": 0, "y": 0, "w": 12, "h": 6 },
      "config": {
        "attributes": {
          "title": "",
          "type": "metric",
          "dataset": { "type": "esql", "query": "FROM logs | STATS total = COUNT(*)" },
          "metrics": [{ "type": "primary", "operation": "value", "column": "total", "label": "Total Count" }]
        }
      }
    },
    {
      "type": "lens",
      "uid": "chart-panel",
      "grid": { "x": 12, "y": 0, "w": 36, "h": 8 },
      "config": {
        "attributes": {
          "title": "Events Over Time",
          "type": "xy",
          "layers": [
            {
              "type": "area",
              "dataset": {
                "type": "esql",
                "query": "FROM logs | STATS count = COUNT(*) BY bucket = BUCKET(@timestamp, 75, ?_tstart, ?_tend)"
              },
              "x": { "operation": "value", "column": "bucket" },
              "y": [{ "operation": "value", "column": "count" }]
            }
          ]
        }
      }
    }
  ],
  "time_range": { "from": "now-24h", "to": "now" }
}

Copy Dashboard Between Spaces/Clusters

# 1. Get dashboard from source
node scripts/kibana-dashboards.js dashboard get source-dashboard > dashboard.json

# 2. Edit dashboard.json to change id and/or spaces

# 3. Create on destination
node scripts/kibana-dashboards.js dashboard create dashboard.json

Dashboard Grid System

Dashboards use a 48-column, infinite-row grid. On 16:9 screens, approximately 20-24 rows are visible without scrolling. Design for density—place primary KPIs and key trends above the fold.

Width	Columns	Height	Rows	Use Case
Full	48	Large	14-16	Wide time series, tables
Half	24	Standard	10-12	Primary charts
Quarter	12	Compact	5-6	KPI metrics
Sixth	8	Minimal	4-5	Dense metric rows

Target: 8-12 panels above the fold. Use descriptive panel titles on the charts themselves instead of adding markdown headers.

Grid Packing Rules:

Eliminate Dead Space: Always calculate the bottom edge (y + h) of every panel. When starting a new row or placing a panel below another, its y coordinate must exactly match the y + h of the panel immediately above it.
Align Row Heights: If multiple panels are placed side-by-side in a row (e.g., sharing the same y coordinate), they should generally have the exact same height (h). If they do not, you must fill the resulting empty vertical space before placing the next full-width panel.

Panel Schema

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

Property	Type	Required	Description
`type`	string	Yes	Embeddable type (e.g., `lens`, `visualization`, `map`)
`uid`	string	No	Unique panel ID (auto-generated if omitted)
`grid`	object	Yes

Lens Visualizations API

Supported Chart Types

Type | Description | ES|QL Support
---|---|---
metric | Single metric value display | Yes
xy | Line, area, bar charts | Yes
gauge | Gauge visualizations | Yes
heatmap | Heatmap charts | Yes
tagcloud | Tag/word cloud | Yes
datatable | Data tables | Yes
region_map | Region/choropleth maps | Yes
pie, donut, treemap, mosaic, | Partition charts | Yes

Dataset Types

There are three dataset types supported in the Lens API. Each uses different patterns for specifying metrics and dimensions.

Data View Dataset

Use dataView with aggregation operations. Kibana performs the aggregations automatically.

{
  "dataset": {
    "type": "dataView",
    "id": "90943e30-9a47-11e8-b64d-95841ca0b247"
  }
}

Available Aggregation Operations (for dataView):

Operation	Description	Requires Field
`count`	Document count	No
`average`	Average value	Yes
`sum`	Sum of values	Yes
`max`	Maximum value	Yes
`min`	Minimum value	Yes

ES|QL Dataset

Use esql with a query string. Reference the output columns using { operation: 'value', column: 'column_name' }.

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

ES|QL Column Reference Pattern:

{
  "operation": "value",
  "column": "count"
}

Key Difference: With ES|QL, you write the aggregation in the query itself, then reference the resulting columns. With dataView, you specify the aggregation operation and Kibana performs it.

Index Dataset

Use index for ad-hoc index patterns without a saved data view:

{
  "dataset": {
    "type": "index",
    "index": "logs-*",
    "time_field": "@timestamp"
  }
}

Examples

For detailed schemas and all chart type options, see Chart Types Reference.

Metric (dataView):

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

Metric (ES|QL):

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

XY Bar Chart (dataView):

{
  "title": "Top Hosts",
  "type": "xy",
  "axis": { "x": { "title": { "visible": false } }, "left": { "title": { "visible": false } } },
  "layers": [
    {
      "type": "bar_horizontal",
      "dataset": { "type": "dataView", "id": "90943e30-9a47-11e8-b64d-95841ca0b247" },
      "x": { "operation": "terms", "fields": ["host.keyword"], "size": 10 },
      "y": [{ "operation": "count" }]
    }
  ]
}

XY Time Series (ES|QL):

{
  "title": "Requests Over Time",
  "type": "xy",
  "axis": { "x": { "title": { "visible": false } }, "left": { "title": { "visible": false } } },
  "layers": [
    {
      "type": "line",
      "dataset": {
        "type": "esql",
        "query": "FROM logs | STATS count = COUNT() BY bucket = BUCKET(@timestamp, 75, ?_tstart, ?_tend)"
      },
      "x": { "operation": "value", "column": "bucket" },
      "y": [{ "operation": "value", "column": "count" }]
    }
  ]
}

Tip: Always hide axis titles when the panel title is descriptive. Use bar_horizontal for categorical data with long labels.

Full Documentation

Dashboard API Reference — Dashboard endpoints and schemas
Lens API Reference — Lens visualization endpoints
Chart Types Reference — Detailed schemas for each chart type
Example Definitions — Ready-to-use definitions

Key Example Files

assets/demo-dashboard.json — Complete dashboard with inline Lens panels (dataView format)
assets/dashboard-with-lens.json — Dashboard with ES|QL format (for future reference)
assets/metric-esql.json — Standalone metric visualization
assets/bar-chart-esql.json — Bar chart example
assets/line-chart-timeseries.json — Time series line chart

Common Issues

Error	Solution
"401 Unauthorized"	Check KIBANA_USERNAME/PASSWORD or KIBANA_API_KEY
"404 Not Found"	Verify dashboard/visualization ID exists
"409 Conflict"	Dashboard/viz with that ID already exists; delete first or use update
"id not allowed in PUT"	Remove `id` and `spaces` from update body
Schema validation error	For ES
ES	QL missing `operation`
Metric uses `metric` not `metrics`	Metric chart requires (plural) array:

Guidelines

Design for density — Operational dashboards must show 8-12 panels above the fold (within the first 24 rows). Use compact panel heights: metrics MUST be h=4 to h=6, and charts MUST be h=8 to h=12.
Never use Markdown for titles/headers — Do NOT add DASHBOARD_MARKDOWN panels to act as dashboard titles or section dividers. This wastes critical vertical space. Use descriptive panel titles on the charts themselves.
Prioritize above the fold — Primary KPIs and key trends must be placed at y=0. Deep-dives and data tables should be placed below the charts.
Use descriptive chart titles — Write titles that explain what the chart shows (e.g., "Revenue by Product Category"). Hide axis labels with axis.x.title.visible: false to reduce clutter
Choose the right dataset type — Use dataView for simple aggregations, for complex queries with joins, transformations, or custom logic

Schema Differences: dataView vs ES|QL

Aspect | dataView | ES|QL
---|---|---
Dataset | { type: 'dataView', id: '...' } | { type: 'esql', query: '...' }
Metric chart | metrics: [{ type: 'primary', operation: 'count' }] | metrics: [{ type: 'primary', operation: 'value', column: 'col' }]
XY columns | { operation: 'terms', fields: ['host'], size: 10 } | { operation: 'value', column: 'host' }
Static values | { operation: 'static_value', value: 100 } | Use EVAL in query (see below)
XY dataset | Inside each layer | Inside each layer | | | , arrays | , arrays with

Key Pattern: ES|QL always uses { operation: 'value', column: 'column_name' } to reference columns from the query result. The aggregation happens in the ES|QL query itself.

ES|QL: Time Bucketing

For time series charts, use the BUCKET function to create "auto" buckets that automatically scale with the time range. Always use BUCKET(@timestamp, 75, ?_tstart, ?_tend) instead of hardcoded intervals like DATE_TRUNC(1 hour, @timestamp):

FROM logs | STATS count = COUNT() BY bucket = BUCKET(@timestamp, 75, ?_tstart, ?_tend)

ES|QL: Creating Static/Constant Values

ES|QL does not support static_value operations. Instead, create constant columns using EVAL:

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

Then reference with { "operation": "value", "column": "max_value" }. For dynamic reference values, use aggregation functions like PERCENTILE() or MAX() in the query.

Design Principles

The APIs follow these principles:

Minimal definitions — Only required properties; defaults are injected
No implementation details — No internal state or machine IDs
Flat structure — Shallow nesting for easy diffing
Semantic names — Clear, readable property names
Git-friendly — Easy to track changes in version control
LLM-optimized — Compact format suitable for one-shot generation

Weekly Installs

175

Repository

elastic/agent-skills

GitHub Stars

First Seen

11 days ago

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

cursor153

github-copilot145

gemini-cli144

opencode143

codex143

amp142

Azure 升级评估与自动化工具 - 轻松迁移 Functions 计划、托管层级和 SKU

96,200 周安装

[{ type: 'primary', operation: '...' }]

Inline Lens definitions — Prefer config.attributes over config.savedObjectId for portable dashboards

Test connection first — Run node scripts/kibana-dashboards.js test before creating resources

Get existing examples — Use lens get <id> to see the exact schema for different chart types

Avoid redundant metric labels — For ES|QL metrics, avoid using both a panel title and an inner metric label, as it wastes space. Set the panel title to "" and configure the human-readable label by aliasing the ES|QL column name using backticks (e.g., STATS Total Requests = COUNT() and "column": "Total Requests").

tag_by: { operation: 'terms', ... }

tag_by: { operation: 'value', column: '...' }

{ operation: 'value', column: '...' }