grafana-dashboards

grafana-dashboards 技能概览

grafana-dashboards 能做什么

grafana-dashboards 技能用于帮助代理为可观测性场景设计并起草偏生产环境风格的 Grafana dashboard。它的重点不是给你一个模糊提示后产出一堆泛泛的图表想法，而是把“展示 API 健康状况”或“跟踪基础设施饱和度”这类监控目标，落成更合理的 dashboard 结构，包括面板组织、指标分组和布局优先级。

谁适合使用 grafana-dashboards

这个技能最适合平台工程师、SRE、DevOps 团队、后端工程师，以及需要为 Prometheus 风格指标构建 Grafana dashboard 的技术负责人。尤其适合这样一种情况：你已经清楚要观测哪个系统，但希望基于成熟的监控模式，得到一套更清晰、更可落地的 dashboard 设计。

它真正解决的工作问题

大多数用户并不需要一个抽象意义上的“dashboard”。他们真正需要的是：在故障处理、复盘和日常健康检查时，能让值班人员快速回答关键问题的 dashboard。grafana-dashboards 最有价值的地方，就在于它会引导代理围绕运维决策来组织指标：哪里坏了、严重到什么程度、下一步该看哪里、情况是否还在恶化。

这个技能和普通提示词有什么不同

grafana-dashboards 最核心的差异，是它把 dashboard 设计建立在可观测性启发式方法上，而不是单纯做 UI 生成。源码重点强调了：

• 信息层级
• 面向服务的 RED 方法
• 面向基础设施与资源的 USE 方法

因此，如果你在意的是可执行的布局逻辑和面板选择，而不只是导出一份 JSON，那么它会比普通的“帮我做一个 Grafana dashboard”提示词更有用。

它看起来不包含什么

这个技能本身比较轻量。根据仓库内容判断，它主要在 SKILL.md 中提供指导，并没有附带 helper scripts、规则文件或其他支持资产。这意味着 grafana-dashboards 更适合被当作提示与设计骨架来使用，而不是完整的 dashboard provisioning 工具包。

如何使用 grafana-dashboards 技能

grafana-dashboards 的安装上下文

如果你的 skills 运行时支持从仓库添加技能，可以从 wshobson/agents 仓库安装，然后在面向可观测性的工作流中调用 grafana-dashboards 技能。常见方式是：

npx skills add https://github.com/wshobson/agents --skill grafana-dashboards

如果你的环境是整仓加载，或通过其他方式同步 skills，关键点是让代理能够访问这个路径下的技能：

plugins/observability-monitoring/skills/grafana-dashboards

先读这个文件

建议先看：

• plugins/observability-monitoring/skills/grafana-dashboards/SKILL.md

从仓库里看不出这个技能还有什么强依赖的配套文件，因此几乎所有有价值的使用指导都在这里。这对快速上手是好事，但也意味着 dashboard schema 规范、datasource 细节，以及导入导出流程，需要你自己补齐。

这个技能需要你提供哪些输入

grafana-dashboards 在你提供运维上下文时效果最好，而不是只给一个 dashboard 标题。建议至少告诉代理：

• 被监控的系统是什么
• dashboard 的目标受众是谁
• datasource 以及指标命名风格
• 最重要的故障模式有哪些
• 需要关注的时间范围和刷新频率
• 你想要的是 service、infrastructure、SLO 还是 business KPI 视角

如果没有这些信息，代理仍然能给出一个结构建议，但面板定义通常会更泛、更像模板。

最适合交给 grafana-dashboards 的 dashboard 需求

适合用 grafana-dashboards 处理的请求包括：

• API 或微服务健康 dashboard
• 基于 Prometheus 的 RED dashboard
• 使用 USE 方法的基础设施 dashboard
• 以 SLO 和延迟为重点的可观测性看板
• 带下钻分区的生产总览 dashboard

它不太适合一次性的临时画图、 heavily customized 的 Grafana 插件场景，或者那种“查询语言细节比 dashboard 结构更重要”的环境。

把模糊需求改成高质量提示词

较弱的提示词：

• “Create a Grafana dashboard for my app.”

更好的提示词：

• “Use the grafana-dashboards skill to design a production Grafana dashboard for a customer-facing API. Datasource is Prometheus. Focus on RED metrics, 30s refresh, last 6h by default, and an on-call audience. Include top-row stat panels for traffic, error rate, p95 latency, and saturation signals. Then propose panel titles, layout order, and example PromQL queries.”

为什么这样更有效：

• 明确了系统对象
• 指定了设计方法
• 说明了受众和时间窗口
• 同时要求结构与查询建议
• 给了代理足够多的约束，避免输出过于泛化

grafana-dashboards 的提示词模板

你可以按这个模板改写：

• “Use the grafana-dashboards skill to design a Grafana dashboard for [service/system].
• Audience: [on-call / engineering managers / platform team]
• Datasource: [Prometheus / other]
• Dashboard goal: [incident response / daily health review / SLO tracking]
• Key metrics: [request rate, error rate, p95 latency, CPU saturation, queue depth]
• Default time range: [1h / 6h / 24h]
• Refresh interval: [15s / 30s / 1m]
• Constraints: [must fit single screen / include variables / separate business KPIs from infra]
• Output wanted: [panel plan / Grafana JSON draft / PromQL suggestions / layout rationale]”

grafana-dashboards 的推荐实战流程

比较稳妥的 grafana-dashboards 使用流程通常是：

1. 先用一句话定义 dashboard 的目的。
2. 再选择分析视角：RED、USE、SLO 或 KPI 导向。
3. 列出 datasource 中真实存在的指标。
4. 先让代理给出面板层级和结构。
5. 再让它补示例查询。
6. 对照你真实的 label 和 metric 名称检查缺口。
7. 最后再要求生成 Grafana JSON 或 provisioning 输出。

这样的顺序能避开一个常见问题：在指标模型都还没确认前，代理先“脑补”出一份看起来很完整、实际上不可用的 dashboard JSON。

这个技能体现出的设计模式

源码材料里突出了几个很值得保留的实用模式：

• 关键指标优先放在前排，使用 big-number 或 stat panel
• 趋势可视化优先使用 time series
• 详细诊断信息放在 dashboard 下半部分
• 服务行为优先用 RED
• 主机、节点、磁盘、队列等资源优先用 USE

对可观测性团队来说，这正是 grafana-dashboards 的主要价值：它优化的是决策流，而不只是增加图表数量。

最终输出大概率会是什么样

结合仓库内容来看，这个技能大概率会帮助你产出：

• dashboard 分区规划
• panel 排序建议
• 指标类别建议
• 类 JSON 的 dashboard 示例
• 基于监控方法论的 panel 选择

但不要默认它会对你环境中的 labels、recording rules、folder 结构、权限设置，或 Grafana provisioning 配置做到开箱即用，除非你明确把这些细节提供给它。

哪些细节会明显影响输出质量

想让 grafana-dashboards 用得更好，建议始终补充这些信息：

• 真实的 metric 名称（如果你已经有）
• 是否有 percentile 指标
• cardinality 约束
• 类似 cluster、namespace、service 这样的环境过滤维度
• 这个 dashboard 是偏总览，还是偏深度排障

这些细节会直接影响代理能否给出有用的顶部面板、合理的变量设计，以及靠谱的查询范围。

grafana-dashboards 技能 FAQ

grafana-dashboards 适合新手吗？

适合，前提是你已经掌握 Grafana 和 metrics 的基础。grafana-dashboards 能帮你理清“什么应该先展示”“面板应该如何分组”。但如果你想把它当作 Prometheus、Grafana provisioning 或查询语言基础的完整入门教程，它就没那么合适了。

grafana-dashboards 会直接生成可用的 Grafana JSON 吗？

它可以指导生成或起草 JSON 形态的输出，但更适合把结果当作起点。你仍然需要在自己的环境里验证 panel 类型、datasource UID、查询语法、变量设置，以及 Grafana 版本兼容性。

它比普通提示词更好吗？

通常是的，尤其在可观测性工作里。grafana-dashboards 的价值在于，它会把代理收束到已经被验证过的 dashboard 设计模式上，例如 RED、USE 和信息层级。普通提示词很容易生成一个“看起来很忙”的 dashboard，但并不利于快速运维阅读。

什么情况下不该使用 grafana-dashboards？

如果你的问题主要是下面这些，就不建议优先用它：

• 修复损坏的 PromQL
• 管理 Grafana provisioning pipeline
• 开发自定义 panel 或插件
• 逆向分析导出的 dashboard
• 处理 datasource 特有的细节问题，而不是标准的可观测性布局问题

这些场景通常更适合更专门的技能，或者直接使用针对仓库/实现细节的提示词。

grafana-dashboards 只能用于 Prometheus 吗？

不是，但它和 Prometheus 风格的可观测性概念天然更契合。如果你使用的是其他 datasource，一定要明确说明查询语言、支持的 panel 类型和字段名，避免代理默认套用 PromQL 的约定。

grafana-dashboards 只适合 Observability 团队吗？

不是。它同样适合需要 business KPI 或 service-health dashboard 的产品团队和工程团队，只要目标是建立结构化的运维可见性即可。只是当 dashboard 需要清晰的监控逻辑，而不只是偏管理汇报风格的美观展示时，这个技能会更强。

如何改进 grafana-dashboards 技能的使用效果

先把你的指标清单交给代理

想提升 grafana-dashboards 的结果质量，最快的方法就是在提 dashboard 需求前，先给一份简短的指标清单。哪怕只有 10 到 15 个真实 metrics，也足以显著减少代理“编造指标名”的情况，让 panel 规划更接近可部署状态。

明确这个 dashboard 必须回答的运维问题

更好的 dashboard 往往来自问题，而不是图表清单。比如：

• “值班人员能否在 30 秒内判断 API 是否异常？”
• “我们能否在延迟升高前发现 CPU 饱和？”
• “产品和运维能否在同一个视图里审查影响收入的错误？”

这样可以更清楚地区分哪些内容该放在顶部摘要，哪些应该放到下方诊断区。

把总览面板和排障面板拆开

grafana-dashboards 的一个常见失败模式，是把第一屏塞得过满。你可以明确要求代理把输出拆成：

• executive 或 on-call 摘要区
• 趋势区
• 下钻或详细诊断区

这样做出来的 dashboard，才是真正能在高压场景下快速扫读的。

明确告诉它该用哪种方法

不要默认代理会自己选对监控模型。最好直接说明：

• 面向请求驱动型服务时使用 RED
• 面向计算资源或基础设施时使用 USE
• 面向客户 API 时，把 SLO panel 和 RED 结合起来

很多时候，这一条指令带来的 panel 相关性提升，比一句“按最佳实践来”更明显。

不只要输出，还要它解释理由

如果第一版看起来合理，但还是偏模板化，可以继续追问：

• 为什么每个顶部 panel 应该放在那个位置
• 如果屏幕空间有限，哪个 panel 可以删
• 哪些指标属于 leading indicators，哪些属于 lagging indicators

这样会迫使 grafana-dashboards 给出更能自圆其说的设计，而不是只追求表面完整。

用具体约束来修正第一版

迭代时，反馈越具体越有效，例如：

• “We do not have histogram buckets.”
• “Use namespace and pod variables.”
• “This dashboard is for mobile backend only.”
• “Remove business KPIs; this is strictly incident response.”
• “Keep it to one screen for a NOC display.”

这类具体约束，通常能让第二版质量明显提升。

留意常见的低质量输出信号

如果草案出现下面这些情况，就要提高警惕：

• 使用了你根本没有的通用 metric 名称
• 在 time series 之前堆了太多 table
• service 和 infrastructure 混在一起，没有分层
• 顶部缺少清晰的摘要区
• 忽略了目标受众和默认时间范围

这些往往说明：调用技能时上下文给得太少，或者请求范围给得太宽。

用结合仓库实际的方式提升 grafana-dashboards 效果

由于这个技能看起来主要依赖 SKILL.md，所以想让结果更实用，最好的办法是把它和你自己的本地规范搭配使用，例如：

• 你们自己的 Grafana JSON schema 示例
• 你们的命名规范
• 你们常用的 PromQL 片段
• 你们的 folder 与 templating 规则

实际使用中，grafana-dashboards 最强的角色更像是设计大脑，而你自己的环境负责补齐实现细节。