dashboard-review

dashboard-review

适用场景

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

• 审查修改 Kibana 仪表板 JSON 文件的 PR
• 比较不同分支之间的仪表板变更
• 总结仪表板导出文件中的变更
• 检查仪表板变更是否符合官方仪表板指南

不适用场景

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

• 创建新仪表板或从 Kibana 导出仪表板（dashboard-guidelines）
• 仪表板命名约定和文件布局（dashboard-guidelines → references/kibana-assets-layout.md）
• 整个软件包的命令编排（elastic-package-cli）
• 测试套件选择（integration-testing）

前提条件

必须安装 kbdash：

go install github.com/efd6/kbdash@latest

输出中以 [!] 开头的行是关于仪表板 JSON 潜在问题的警告（一致性不匹配、提取不完整、解析错误）。运行 kbdash -h 可查看各类警告的说明。

审查流程

请阅读 references/review-procedure.md，了解完整的分步工作流。高级流程如下：

1. 识别变更的仪表板文件（新增、删除、修改）。
2. 使用 kbdash 提取变更前后的描述。
3. 比较描述，并将变更归类为实质性或外观性变更。
4. 在报告前，根据原始 JSON 核实疑似问题。
5. 将输出整理为每个仪表板一个章节，并以项目符号列出变更。
6. 检查新增或修改的仪表板是否符合指南。

指南合规性检查

总结变更后，根据官方仪表板指南检查每个新增或修改的仪表板的最终状态。对于每个仪表板，在变更摘要后添加“指南备注”小节，报告违规项。

检查以下问题：

• **TSVB 面板：**标记任何使用 TSVB 的 visualization 面板。指南要求所有新可视化都使用 Lens。建议将现有 TSVB 迁移到 Lens。
• **缺少数据集筛选器：**每个可视化都应筛选 data_stream.dataset 或范围同样明确的字段。标记查询宽泛索引模式（metrics-*、logs-*）但未限定范围的面板。
• **按引用嵌入的可视化：**可视化面板和 Lens 面板应按值嵌入。kbdash 会标记按引用嵌入的 lens、visualization 和 map 面板，并显示 [!] <type> ref: … (definition not inlined)。请标记这些面板。已保存的搜索本身就是按引用嵌入的，并带有单独的 [!] saved search ref 警告——不要标记这些搜索。
• 已弃用的输入控件：input-control-vis 类型已弃用。应改用仪表板原生控件。
• **标题带软件包名称前缀：**匹配 [<Package Name> ...] 的面板标题会造成不必要的重复。请标记这些标题。
• **宽泛通配符筛选器：**未限定范围且没有进一步限定的 -* 模式筛选器会带来性能问题。
• **面板数量过多：**kbdash 会在面板部分的标题中显示数量，即 Panels (N total, …)。如果 N 超过约 20，请予以说明。指南建议将面板拆分到多个仪表板，并通过下钻链接关联。
• **查询使用 event.dataset 而非 data_stream.dataset：**已保存对象中的查询（仪表板、已保存的搜索、打包的 ML 作业数据馈送）必须筛选 data_stream.dataset。有些输入源（例如 packetbeat）不会设置 event.dataset，因此 event.dataset 筛选器会静默匹配不到任何内容。对于差异中重命名或重新映射字段的每个已保存对象查询，都应予以标记。
• **YAML 仪表板源文件未同步：**如果软件包将 YAML 仪表板源文件保存在 _dev/shared/kibana/*.yaml（通过 kb-dashboard 编译为 kibana/dashboard/*.json），则必须同时提交两者并确保同步。如果某个仪表板存在 YAML 源文件，请标记仅修改 JSON 的变更。
• **重新生成产生的差异：**预期重新编译 PR 只会修改 state.adHocDataViews、state.internalReferences 和每层的 index 键（Kibana 9.3+ 中针对 ES|QL/Discover 的修复）。对于“重新生成”PR，请检查超出这些键范围的差异。
• **缺少 Kibana 资源标签：**kbdash 会为每个仪表板显示 Tags: 部分（在软件包目录上运行时，从 kibana/tag/ 解析）。新的内容包仪表板应带有 Kibana 资源标签——请说明缺少标签的情况（低优先级）。
• **导航链接完整性：**如果仪表板有链接面板，请验证软件包中的每个仪表板都有对应条目。运行 kbdash <package-dir>，查看所有仪表板标题（=== … === 标题）以及每个链接面板的 Link: 行。请说明标题没有对应链接的仪表板。

只报告实际存在的问题——通过的检查无需提及。对于未修改面板中原本就存在的违规项，只需简要说明一次（例如：“另有 N 个现有面板使用 TSVB”），无需逐一列出。重点审查新增或修改的面板。

移交给其他技能

审查完成后：

1. 如果审查发现结构性问题，使用 dashboard-guidelines 获取创建或导出指南
2. 如果仪表板变更需要添加发行说明条目，使用 package-spec
3. 使用 elastic-package-cli 获取验证命令

参考资料

• references/review-procedure.md — 完整的提取、比较和输出格式工作流程