dashboard-guidelines

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

dashboard-guidelines

仪表板指南

When to use

适用场景

Use this skill when tasks include:

creating new Kibana dashboards for an integration package
reviewing dashboard JSON changes in
```
kibana/
```
folders
exporting dashboard updates from Kibana into package source
verifying dashboard naming and file layout against package spec
checking dashboard/data stream alignment through
```
data_stream.dataset
```
filtering

当您需要完成以下任务时，使用本技能：

为集成包创建新的Kibana仪表板
审查
```
kibana/
```
文件夹中的仪表板JSON变更
将Kibana中的仪表板更新导出到包源码中
根据包规范验证仪表板的命名和文件布局
通过
```
data_stream.dataset
```
过滤检查仪表板与数据流的对齐情况

When not to use

不适用场景

Do not use this skill as the primary guide for:

package and data stream directory scaffolding (
```
create-integration
```
,
```
package-structure
```
)
ingest pipeline parsing and normalization logic (
```
ingest-pipelines
```
)
package-wide command orchestration and stack lifecycle decisions (
```
elastic-package-cli
```
)
test suite selection outside dashboard-focused checks (
```
integration-testing
```
→
```
references/system-testing.md
```
)

请勿将本技能作为以下内容的主要指南：

包和数据流目录的脚手架搭建（
```
create-integration
```
、
```
package-structure
```
）
摄入管道的解析与标准化逻辑（
```
ingest-pipelines
```
）
包级别的命令编排与堆栈生命周期决策（
```
elastic-package-cli
```
）
仪表板专项检查之外的测试套件选择（
```
integration-testing
```
→
```
references/system-testing.md
```
）

Preconditions

前置条件

Before creating or updating dashboard assets, verify:

you are in the correct package directory (
```
packages/<package_name>/
```
)
Kibana/Elastic services are available for editing and exporting assets
sample data exists and dashboards can be validated against realistic events/metrics
package
```
manifest.yml
```
compatibility constraints (
```
conditions.kibana.version
```
) are understood

在创建或更新仪表板资产之前，请确认：

您处于正确的包目录中（
```
packages/<package_name>/
```
）
Kibana/Elastic服务可用，可用于编辑和导出资产
存在样本数据，且仪表板可针对真实事件/指标进行验证
已理解包
```
manifest.yml
```
中的兼容性约束（
```
conditions.kibana.version
```
）

Workflow: create, export, validate

工作流程：创建、导出、验证

Build or update dashboards in Kibana.
- Prefer Lens for new visualizations.
- Keep panels in the dashboard itself (by value) unless shared-library behavior is intentionally required.
Export assets back into the package.

bash

undefined

在Kibana中构建或更新仪表板。
- 新可视化优先使用Lens。
- 除非明确需要共享库行为，否则将面板保留在仪表板内部（按值存储）。
将资产导出回包中。

bash

undefined

from package root

elastic-package export


3. If you need to modify installed managed dashboards before exporting:

```bash
elastic-package edit dashboards
elastic-package export dashboards

Review exported files under
```
kibana/
```
:
- file names match package spec
- no stale field names after mapping changes
- dashboard filters are scoped to integration datasets
Run package validation commands before opening a PR:

bash

elastic-package check

elastic-package export


3. 如果需要在导出前修改已安装的托管仪表板：

```bash
elastic-package edit dashboards
elastic-package export dashboards

审查
```
kibana/
```
下的导出文件：
- 文件名符合包规范
- 映射变更后无过时字段名
- 仪表板过滤器限定在集成数据集范围内
在提交PR前运行包验证命令：

bash

elastic-package check

Naming conventions

命名规范

Use naming conventions from dashboard creation guidance:

Visualization title:
- ```
<Name>
```
  (avoid repeating package name in each panel title)

Dashboard title:

[<Metrics | Logs> <PACKAGE NAME>] <Name>

examples:

[Metrics System] Host overview

[Logs Nginx] Access overview

Dashboard asset file:

```
{PACKAGE_NAME}-{identifier}.json
```

example:

nginx-046212a0-a2a1-11e7-928f-5dbe6f6f5519.json

遵循仪表板创建指南中的命名规范：

可视化标题：
- ```
<名称>
```
  （避免在每个面板标题中重复包名）

仪表板标题：

```
[<指标 | 日志> <包名>] <名称>
```

示例：

[Metrics System] Host overview

、

[Logs Nginx] Access overview

仪表板资产文件：

```
{PACKAGE_NAME}-{identifier}.json
```

示例：

nginx-046212a0-a2a1-11e7-928f-5dbe6f6f5519.json

Design and modeling best practices

设计与建模最佳实践

Use stable released Kibana versions (avoid SNAPSHOT).
Keep dashboards focused; split overloaded boards and provide navigation links.
Prefer by-value panels so dashboards remain self-contained.
Prefer Lens over TSVB for new visualizations.
Add controls using dashboard-native Controls (not deprecated input controls visualization).
Include dataset-aware filtering to prevent broad
```
logs-*
```
/
```
metrics-*
```
queries where possible.
- baseline recommendation: filter by
```
data_stream.dataset
```
Keep visual hierarchy clear:
- most important summary panels near the top
- related charts grouped together
- margins enabled for readability
Use concise, self-explanatory panel titles and consistent accessible colors.

使用稳定发布的Kibana版本（避免SNAPSHOT版本）。
保持仪表板聚焦；拆分过载的仪表板并提供导航链接。
优先使用按值存储的面板，使仪表板保持独立。
新可视化优先使用Lens而非TSVB。
使用仪表板原生的Controls添加控件（而非已弃用的输入控件可视化）。
尽可能添加数据集感知过滤，避免宽泛的
```
logs-*
```
/
```
metrics-*
```
查询。
- 基线建议：按
```
data_stream.dataset
```
  过滤
保持清晰的可视化层级：
- 最重要的摘要面板放在顶部附近
- 相关图表分组展示
- 启用边距以提升可读性
使用简洁、自解释的面板标题和一致的无障碍颜色。

Quality checklist before PR

PR提交前的质量检查清单

dashboard assets are in
```
kibana/dashboard/
```
and follow expected naming pattern
dashboard content reflects current field names and types
visualizations are embedded by value unless there is a documented exception
dashboard or panel queries include integration-relevant filters (
```
data_stream.dataset
```
when applicable)
controls/drilldowns/navigation are coherent for multi-dashboard packages
exported dependencies are committed (dashboards plus required saved objects)
```
elastic-package check
```
passes for the package

仪表板资产位于
```
kibana/dashboard/
```
目录下，且符合预期命名模式
仪表板内容反映当前字段名和字段类型
可视化按值嵌入，除非有文档记录的例外情况
仪表板或面板查询包含与集成相关的过滤器（适用时使用
```
data_stream.dataset
```
）
多仪表板包的控件/钻取/导航逻辑连贯
已提交导出的依赖项（仪表板及所需的已保存对象）
包通过
```
elastic-package check
```
验证

Common pitfalls

常见陷阱

exporting from an unstable Kibana build and committing incompatible saved object data
using generic, unfiltered
```
logs-*
```
/
```
metrics-*
```
queries that cause noisy or slow panels
keeping stale field references after pipeline/field mapping changes
overloading one dashboard instead of splitting into overview and deep-dive views
relying on library visualizations unintentionally, causing hidden dependencies
inconsistent naming between dashboard title, file name, and package context

从不稳定的Kibana构建导出并提交不兼容的已保存对象数据
使用通用、未过滤的
```
logs-*
```
/
```
metrics-*
```
查询，导致面板产生噪音或加载缓慢
在管道/字段映射变更后保留过时的字段引用
将过多内容塞进一个仪表板，而非拆分为概览和深入视图
无意中依赖库可视化，导致隐藏依赖
仪表板标题、文件名与包上下文之间命名不一致

Handoff to other skills

移交至其他技能

After dashboard updates are in place, continue with:

```
dashboard-review
```
for reviewing dashboard JSON changes in a PR or branch

integration-testing

→

references/system-testing.md

for system test validation

```
elastic-package-cli
```
for broader check/lint/test command selection
```
package-spec
```
when dashboard changes require a release note entry

完成仪表板更新后，可继续执行以下操作：

使用
```
dashboard-review
```
审查PR或分支中的仪表板JSON变更

使用

integration-testing

→

references/system-testing.md

进行系统测试验证

使用
```
elastic-package-cli
```
选择更广泛的检查/ lint/测试命令
当仪表板变更需要发布说明条目时，使用
```
package-spec
```

References

参考资料

```
references/kibana-assets-layout.md
```

```
references/kibana-assets-layout.md
```