mcpField
D
dashboard-guidelines

dashboard-guidelines

github.com/elastic数据与数据库16509 次安装5 周前更新
代码仓库

关于 dashboard-guidelines

dashboard-guidelines 是面向 Elastic 集成包的 Kibana 仪表板制作与校验技能，适合创建、更新或导出仪表板的开发者。它涵盖命名、布局、数据集过滤和发布前检查。

主要功能

  1. 01指导创建、更新和导出仪表板
  2. 02提供仪表板命名与文件布局规范
  3. 03建议使用 Lens 和仪表板原生控件
  4. 04检查数据集过滤及字段引用
  5. 05提供 PR 前质量检查清单

适用场景

  1. 01为集成包创建 Kibana 仪表板
  2. 02将 Kibana 中的仪表板更新导出到包内
  3. 03检查仪表板命名与文件布局
  4. 04验证仪表板过滤和字段是否匹配数据流

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/elastic/integration-skills --skill dashboard-guidelines

安装后在 Claude Code 中输入/dashboard-guidelines确认已加载。

附带文件references/kibana-assets-layout.md

详细介绍

dashboard-guidelines

适用场景

在以下任务中使用此技能：

  • 为集成包创建新的 Kibana 仪表板
  • 审查 kibana/ 文件夹中的仪表板 JSON 变更
  • 将 Kibana 中的仪表板更新导出到包源文件
  • 根据包规范验证仪表板命名和文件布局
  • 通过 data_stream.dataset 筛选检查仪表板与数据流是否匹配

不适用场景

请勿将此技能作为以下任务的主要指南：

  • 搭建包和数据流目录结构（create-integration、package-structure）
  • 采集管道的解析和规范化逻辑（ingest-pipelines）
  • 整个包的命令编排和堆栈生命周期决策（elastic-package-cli）
  • 仪表板专项检查以外的测试套件选择（integration-testing → references/system-testing.md）

前提条件

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

  1. 你位于正确的包目录中（packages/<package_name>/）
  2. Kibana/Elastic 服务可用，可以编辑和导出资源
  3. 存在示例数据，且可以使用真实事件/指标验证仪表板
  4. 已了解包 manifest.yml 中的兼容性约束（conditions.kibana.version）

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

  1. 在 Kibana 中构建或更新仪表板。
    • 创建新的可视化时优先使用 Lens。
    • 除非确实需要共享库行为，否则请将面板保留在仪表板中（按值嵌入）。
  2. 将资源导出回包中。
# from package root
elastic-package export
  1. 如需在导出前修改已安装的受管仪表板：
elastic-package edit dashboards
elastic-package export dashboards

  1. 检查 kibana/ 下导出的文件：

    • 文件名符合包规范
    • 映射变更后不存在过时的字段名
    • 仪表板筛选条件限定在集成数据集范围内

  2. 创建 PR 前运行包验证命令：

elastic-package check

命名约定

采用仪表板创建指南中的命名约定：

  • 可视化标题：
    • <Name>（避免在每个面板标题中重复包名）
  • 仪表板标题：
    • [<Metrics | Logs> <PACKAGE NAME>] <Name>
    • 示例：[Metrics System] Host overview、[Logs Nginx] Access overview
  • 仪表板资源文件：
    • {PACKAGE_NAME}-{identifier}.json
    • 示例：nginx-046212a0-a2a1-11e7-928f-5dbe6f6f5519.json

设计与建模最佳实践

  • 使用稳定发布的 Kibana 版本（避免使用 SNAPSHOT）。
  • 保持仪表板聚焦；拆分内容过多的仪表板，并提供导航链接。
  • 优先使用按值嵌入的面板，让仪表板保持自包含。
  • 创建新的可视化时优先使用 Lens，而非 TSVB。
  • 使用仪表板原生的 Controls 添加控件（不要使用已弃用的输入控件可视化）。
  • 尽可能添加数据集感知筛选，避免使用宽泛的 logs-* / metrics-* 查询。
    • 基本建议：按 data_stream.dataset 筛选
  • 保持清晰的视觉层次：
    • 将最重要的摘要面板放在靠上位置
    • 将相关图表归组展示
    • 启用边距以提高可读性
  • 使用简洁、易懂的面板标题，并保持无障碍配色的一致性。

PR 前质量检查清单

  • 仪表板资源位于 kibana/dashboard/，并符合预期的命名模式
  • 仪表板内容反映当前字段名和字段类型
  • 除有文档记录的例外情况外，可视化均按值嵌入
  • 仪表板或面板查询包含与集成相关的筛选条件（适用时使用 data_stream.dataset）
  • 多仪表板包中的控件/下钻/导航逻辑清晰一致
  • 已提交导出的依赖项（仪表板及所需的已保存对象）
  • 包的 elastic-package check 检查通过

常见陷阱

  • 从不稳定的 Kibana 构建版本导出并提交不兼容的已保存对象数据
  • 使用通用且未经筛选的 logs-*/metrics-* 查询，导致面板内容嘈杂或运行缓慢
  • 管道或字段映射发生变化后，仍保留过时的字段引用
  • 将所有内容塞进一个仪表板，而不是拆分为概览视图和深入分析视图
  • 无意中依赖库可视化，导致产生隐性依赖
  • 仪表板标题、文件名和包上下文之间的命名不一致

移交给其他技能

完成仪表板更新后，继续执行：

  1. 使用 dashboard-review 审查 PR 或分支中的仪表板 JSON 更改
  2. 使用 integration-testing → references/system-testing.md 验证系统测试
  3. 使用 elastic-package-cli 选择更全面的检查、Lint 和测试命令
  4. 当仪表板更改需要添加发行说明时，使用 package-spec

参考资料

  • references/kibana-assets-layout.md

评论

支持 Markdown