在 Elastic integration package…

当需要为 integration package 新建、审查、导出 Kibana dashboards，并确保其命名、结构和 data stream 对齐符合规范时使用。

适用场景

解决思路

1. 创建或更新 dashboard assets 前，确认当前位于正确的 package 目录：`packages/<package_name>/`。
2. 确认 Kibana/Elastic services 可用于编辑和导出 assets。
3. 确认已有 sample data，并且 dashboards 能基于真实 events/metrics 进行验证。
4. 理解 package `manifest.yml` 的兼容性约束（`conditions.kibana.version`）。
5. 在 Kibana 中构建或更新 dashboards。
6. 新可视化优先使用 Lens。
7. 除非明确需要 shared-library 行为，否则将 panels 保留在 dashboard 本身（by value）。
8. 从 package root 运行 `elastic-package export` 将 assets 导出回 package。
9. 如果需要在导出前修改已安装的 managed dashboards，运行 `elastic-package edit dashboards`，然后运行 `elastic-package export dashboards`。
10. 审查 `kibana/` 下导出的文件：文件名符合 package spec。
11. 审查映射变更后没有过期 field names。
12. 审查 dashboard filters 已限定到 integration datasets。
13. 打开 PR 前运行 `elastic-package check`。
14. Visualization title 使用 `<Name>`，避免在每个 panel title 重复 package name。
15. Dashboard title 使用 `[<Metrics | Logs> <PACKAGE NAME>] <Name>`，例如 `[Metrics System] Host overview`、`[Logs Nginx] Access overview`。
16. Dashboard asset file 使用 `{PACKAGE_NAME}-{identifier}.json`，例如 `nginx-046212a0-a2a1-11e7-928f-5dbe6f6f5519.json`。
17. 使用稳定发布的 Kibana 版本，避免 SNAPSHOT。
18. 保持 dashboards 聚焦；拆分过载的看板并提供 navigation links。
19. 优先使用 by-value panels，使 dashboards 保持自包含。
20. 新可视化优先使用 Lens 而不是 TSVB。
21. 使用 dashboard-native **Controls** 添加 controls，而不是已废弃的 input controls visualization。
22. 尽可能包含 dataset-aware filtering，避免宽泛的 `logs-*` / `metrics-*` 查询；基线建议按 `data_stream.dataset` 过滤。
23. 保持清晰 visual hierarchy：最重要的 summary panels 放在顶部附近。
24. 将相关 charts 分组在一起。
25. 启用 margins 以提升可读性。
26. 使用简洁、自解释的 panel titles 和一致的可访问颜色。
27. PR 前检查 dashboard assets 位于 `kibana/dashboard/` 并符合预期命名模式。
28. PR 前检查 dashboard 内容反映当前 field names 和 types。
29. PR 前检查 visualizations 以 by value 方式嵌入，除非有记录在案的例外。
30. PR 前检查 dashboard 或 panel queries 包含 integration-relevant filters（适用时使用 `data_stream.dataset`）。
31. PR 前检查 controls/drilldowns/navigation 对 multi-dashboard packages 是连贯的。
32. PR 前提交导出的 dependencies（dashboards 以及必需的 saved objects）。
33. PR 前确保 `elastic-package check` 通过。
34. 避免从不稳定 Kibana build 导出并提交不兼容的 saved object 数据。
35. 避免使用泛化、未过滤的 `logs-*`/`metrics-*` 查询，以免 panels 噪声大或慢。
36. 避免在 pipeline/field mapping 变更后保留过期 field references。
37. 避免把一个 dashboard 塞得过满；应拆分为 overview 和 deep-dive views。
38. 避免无意依赖 library visualizations，造成隐藏 dependencies。
39. 避免 dashboard title、file name 和 package context 之间命名不一致。
40. Dashboard 更新完成后，继续使用 `dashboard-review` 审查 PR 或 branch 中的 dashboard JSON 变更。
41. 继续使用 `integration-testing` → `references/system-testing.md` 进行 system test validation。
42. 继续使用 `elastic-package-cli` 选择更广泛的 check/lint/test 命令。
43. 当 dashboard 变更需要 release note entry 时，使用 `package-spec`。
44. 参考 `references/kibana-assets-layout.md` 了解 Kibana assets 布局。

适用边界 · 注意事项

• 不要将其作为 package 和 data stream 目录脚手架（`create-integration`、`package-structure`）的主要指南。
• 不要将其作为 ingest pipeline 解析与规范化逻辑（`ingest-pipelines`）的主要指南。
• 不要将其作为 package 级命令编排与 stack 生命周期决策（`elastic-package-cli`）的主要指南；也不要用它做 dashboard 聚焦检查之外的测试套件选择（`integration-testing` → `references/system-testing.md`）。