基于 Agent 技能库构建生产级 Grafana 仪表盘observability-monitoring 插件 grafana-dashboards 实战指南【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents本篇指南以 plugins/observability-monitoring/skills/grafana-dashboards/SKILL.md 为核心骨架完整讲解如何在 AI 编程助手如 Claude Code中借助该技能为应用、基础设施与业务指标设计并落地生产级 Grafana 仪表盘。你将掌握信息层级设计、RED/USE 方法论、四种核心面板、模板变量、仪表盘告警、文件 Provisioning 以及 Terraform/Ansible 的 Dashboard as Code 落地方式并看到它与 Prometheus 配置、SLO 实现技能在同一观测体系中的协作关系。技能定位它是谁、何时被激活grafana-dashboards是observability-monitoring插件下的四个技能之一与prometheus-configuration指标采集、distributed-tracing链路追踪、slo-implementationSLO 落地共同构成一套完整的可观测性技能矩阵见 docs/agent-skills.md 的 Observability Monitoring (4 skills) 小节。技能的 YAML 前置元数据frontmatter给出了它的激活条件名称grafana-dashboards描述创建并管理生产级 Grafana 仪表盘用于系统和应用指标的实时可视化当需要构建监控仪表盘、可视化指标或搭建运维可观测性界面时使用。这意味着当你在对话中提出给这个服务做一个监控大盘把 Prometheus 指标画出来做一个 SLO 仪表盘时助手会依据该描述自动激活此技能自动发现机制见 docs/usage.md 与 docs/agent-skills.md。技能采用渐进式披露progressive disclosure结构元数据常驻上下文核心指导内容在激活后加载从而节省 token。该技能面向四类典型场景可视化 Prometheus 指标、创建自定义仪表盘、实现 SLO 仪表盘、监控基础设施、跟踪业务 KPI。在插件内它与 observability-engineer agent 协同工作——agent 负责高层推理与编排如设计监控架构、选择面板、制定告警策略技能提供具体的仪表盘结构与查询模式。实际使用时也可通过/observability-monitoring:monitor-setup命令获得端到端的监控搭建引导见 docs/usage.md 的命令参考表。一、仪表盘设计三原则1. 信息层级Hierarchy of Information一个可读性强的仪表盘应当遵循从上到下、从粗到细的视觉漏斗┌─────────────────────────────────────┐ │ Critical Metrics (Big Numbers) │ ├─────────────────────────────────────┤ │ Key Trends (Time Series) │ ├─────────────────────────────────────┤ │ Detailed Metrics (Tables/Heatmaps) │ └─────────────────────────────────────┘顶部放最重要的关键指标大数字中部放核心趋势时间序列底部放需要深入排查时才关注的明细表格/热力图。这与可观测性领域一眼可判断系统是否健康再逐层下钻的 SRE 实践一致。2. RED 方法面向服务适用于 HTTP API、gRPC 等服务型工作负载的三个黄金指标Rate每秒请求数Request per secondErrors错误率Error rateDuration延迟/响应时间Latency/response time对应到 PromQL即为rate(http_requests_total[5m])、5xx 占比、histogram_quantile分位数延迟。这也是监控生态中经典的 Golden Signals黄金信号。3. USE 方法面向资源适用于主机、数据库、网络设备等资源型组件的三个维度Utilization资源忙碌的时间百分比Saturation队列长度/等待时间Errors错误计数CPU、内存、磁盘、网络接口均可用 USE 方法拆解为利用率-饱和度-错误三类面板。在下面的基础设施仪表盘模式中你会看到它的具体落法。补充佐证同一插件下的 monitor-setup 命令 在Grafana Dashboard Setup一节中把 RED 指标具体化为请求速率、错误率、P50/P95/P99 延迟三块面板golden signals并给出了按 service 过滤的模板函数createServiceDashboard(serviceName)可作为黄金信号落地的工程化参考。二、Dashboard 结构API 监控仪表盘完整示例技能给出了一个可直接导入 Grafana 的 API 监控仪表盘 JSON包含请求速率 错误率(带告警) P95 延迟三个面板横跨两行。以下为完整结构已在原文档基础上补充字段说明{ dashboard: { title: API Monitoring, tags: [api, production], timezone: browser, refresh: 30s, panels: [ { title: Request Rate, type: graph, targets: [ { expr: sum(rate(http_requests_total[5m])) by (service), legendFormat: {{service}} } ], gridPos: { x: 0, y: 0, w: 12, h: 8 } }, { title: Error Rate %, type: graph, targets: [ { expr: (sum(rate(http_requests_total{status~\5..\}[5m])) / sum(rate(http_requests_total[5m]))) * 100, legendFormat: Error Rate } ], alert: { conditions: [ { evaluator: { params: [5], type: gt }, operator: { type: and }, query: { params: [A, 5m, now] }, type: query } ] }, gridPos: { x: 12, y: 0, w: 12, h: 8 } }, { title: P95 Latency, type: graph, targets: [ { expr: histogram_quantile(0.95, sum(rate(http_request_duration_seconds_bucket[5m])) by (le, service)), legendFormat: {{service}} } ], gridPos: { x: 0, y: 8, w: 24, h: 8 } } ] } }字段解读timezone: browser按查看者本地时区展示时间适合跨地域团队。refresh: 30s仪表盘默认每 30 秒自动刷新技能的最佳实践建议默认时间范围为 Last 6 hours。gridPos面板的网格坐标与尺寸x、y为起始坐标w、h为宽高宽度按 24 列栅格划分。第一行两块面板各占 12 列第二行 P95 延迟占满 24 列。legendFormat{{service}}通过 Go 模板语法将 Prometheus 的service标签渲染为图例名称。错误率面板内嵌了alert条件当错误率查询结果gt大于超过 5% 且持续 5 分钟A, 5m, now时触发告警。关于告警的完整字段说明见下文五、仪表盘告警。该查询族依赖的标准指标http_requests_total、http_request_duration_seconds由应用侧通过 Prometheus 客户端埋点产生——在 monitor-setup 命令 中可以看到配套的prom-client指标埋点实现Counter Histogram二者构成采集-展示闭环。三、四种核心面板类型1. Stat 面板单值大数字适合展示总请求数当前错误预算等单个关键值{ type: stat, title: Total Requests, targets: [ { expr: sum(http_requests_total) } ], options: { reduceOptions: { values: false, calcs: [lastNotNull] }, orientation: auto, textMode: auto, colorMode: value }, fieldConfig: { defaults: { thresholds: { mode: absolute, steps: [ { value: 0, color: green }, { value: 80, color: yellow }, { value: 90, color: red } ] } } } }关键点reduceOptions.calcs: [lastNotNull]将时间序列收敛为最后一个非空值values: false表示不显示所有原始值。thresholds绝对阈值三步着色green/yellow/redfieldConfig.defaults中配置后作用于该面板全部序列是设定有意义的颜色阈值这一最佳实践的载体。2. Time Series 时序图{ type: graph, title: CPU Usage, targets: [ { expr: 100 - (avg by (instance) (rate(node_cpu_seconds_total{mode\idle\}[5m])) * 100) } ], yaxes: [ { format: percent, max: 100, min: 0 }, { format: short } ] }yaxes显式指定左轴格式为百分比并固定 0–100 区间避免 CPU 使用率出现负值或越界。同一 CPU 使用率表达式在 prometheus-configuration 技能 中被定义为 recording ruleinstance:node_cpu:utilization可在查询中直接复用。3. Table 表格面板{ type: table, title: Service Status, targets: [ { expr: up, format: table, instant: true } ], transformations: [ { id: organize, options: { excludeByName: { Time: true }, indexByName: {}, renameByName: { instance: Instance, job: Service, Value: Status } } } ] }要点instant: true使查询只取当前时刻的瞬时值配合up指标可得到每个采集目标当前是否在线的状态表。transformations中的organize变换用于重命名列job→Service并隐藏时间列是一致的命名约定与面板说明两项最佳实践在 JSON 中的体现。4. Heatmap 热力图{ type: heatmap, title: Latency Heatmap, targets: [ { expr: sum(rate(http_request_duration_seconds_bucket[5m])) by (le), format: heatmap } ], dataFormat: tsbuckets, yAxis: { format: s } }dataFormat: tsbuckets表示数据来源是直方图桶bucket计数sum(...) by (le)按桶上界聚合y 轴单位设为秒format: s。热力图能直观展示延迟分布随时间的演变弥补只看 P95 分位线时丢失的分布形态信息。四、模板变量Variables查询变量定义变量让同一份仪表盘在不同 namespace / service 间复用。技能给出的 Prometheus 查询变量示例如下{ templating: { list: [ { name: namespace, type: query, datasource: Prometheus, query: label_values(kube_pod_info, namespace), refresh: 1, multi: false }, { name: service, type: query, datasource: Prometheus, query: label_values(kube_service_info{namespace\$namespace\}, service), refresh: 1, multi: true } ] } }type: query变量值由 Prometheus 的label_values()查询动态生成。refresh: 1进入仪表盘时刷新变量选项不同取值对应不同刷新策略。第二个变量通过{namespace$namespace}引用第一个变量形成级联过滤cascading。multinamespace单选falseservice支持多选true。在查询中使用变量sum(rate(http_requests_total{namespace$namespace, service~$service}[5m]))$namespace直接匹配精确值service~$service使用正则匹配以支持多选。这是使用变量提高灵活性最佳实践的标准写法。五、仪表盘告警Alerts in Dashboards技能给出了完整的面板内告警结构{ alert: { name: High Error Rate, conditions: [ { evaluator: { params: [5], type: gt }, operator: { type: and }, query: { params: [A, 5m, now] }, reducer: { type: avg }, type: query } ], executionErrorState: alerting, for: 5m, frequency: 1m, message: Error rate is above 5%, noDataState: no_data, notifications: [{ uid: slack-channel }] } }字段说明evaluator判定规则。type: gtparams: [5]表示大于 5其他常见类型还有lt小于、within_range等。query.params: [A, 5m, now]对面板中字母A对应的查询评估最近 5 分钟到现在的数据。reducer: { type: avg }将区间内的多点数据归约为平均值后与阈值比较可选min/max/sum/last等。for: 5m条件需持续满足 5 分钟才真正触发用于过滤瞬时抖动避免误报。frequency: 1m每 1 分钟评估一次告警条件。noDataState: no_data查询无数据时进入 no_data 状态executionErrorState: alerting查询执行出错时直接置为 alerting。notifications关联通知渠道uid指向 Grafana 中已配置的联络点如 Slack 频道。值得强调的是这种面板内置告警适合简单场景对于 SLO 级别的可靠性告警技能体系的推荐做法是在 Prometheus 侧编写基于多窗口 burn rate 的告警规则见 slo-implementation 技能 的 SLO Alerting Rules其中包含 14.4x fast burn / 6x slow burn 等成熟阈值模式。六、Dashboard Provisioning文件方式批量加载将仪表盘 JSON 落盘并由 Grafana 自动加载是最简单直接的仪表盘即代码起步方式# dashboards.yml apiVersion: 1 providers: - name: default orgId: 1 folder: General type: file disableDeletion: false updateIntervalSeconds: 10 allowUiUpdates: true options: path: /etc/grafana/dashboardstype: file从本地文件系统读取仪表盘定义。options.path存放*.json仪表盘文件的目录对应 Grafana 容器内的挂载目录。updateIntervalSeconds: 10每 10 秒扫描一次目录实现改文件即热更新。allowUiUpdates: true允许在 UI 中保存修改若希望完全以文件为准可设为false防止漂移。disableDeletion: false允许在 UI 中删除由该 provider 管理的仪表盘。将仪表盘 JSON 放入该目录后Grafana 会在一个刷新周期内自动识别并展示无需手工 import。七、常见仪表盘模式技能为三类高频场景给出了面板清单可直接作为建盘时的检查清单。基础设施仪表盘Infrastructure面板说明CPU utilization per node按节点展示 CPU 利用率Memory usage per node按节点展示内存用量Disk I/O磁盘吞吐与 IOPSNetwork traffic网络出入流量Pod count by namespace按命名空间统计 Pod 数量Node status节点在线状态可用up或 kube-state-metrics 指标对应查询可参考 USE 方法利用率类指标在 prometheus-configuration 技能 的 recording rules 中已有现成模板CPU/内存/磁盘利用率可直接引用或在其上叠加饱和度队列长度与错误计数面板。数据库仪表盘DatabaseQueries per second每秒查询数Connection pool usage连接池使用率Query latency P50 / P95 / P99查询延迟分位Active connections活跃连接数Database size数据库体积Replication lag复制延迟Slow queries慢查询计数应用仪表盘ApplicationRequest rate请求速率Error rate错误率Response time percentiles响应时间分位Active users/sessions活跃用户/会话Cache hit rate缓存命中率Queue length队列长度注技能文档中为 API、基础设施、数据库仪表盘标注了assets/*.json参考资产在当前仓库快照中这些资产文件并未随技能一同提交实际使用时可将上文二、Dashboard 结构的 JSON 作为 API 仪表盘的起点再按本节清单扩充面板。八、Best Practices十条可执行清单技能给出的十条最佳实践浓缩了生产级仪表盘的普遍经验从模板起步优先基于 Grafana 社区仪表盘模板community dashboards改造而非从零手写。命名一致面板与变量采用统一的命名约定。按行分组将相关指标分组到同一 row行中提升浏览效率。设置合适的时间范围默认展示最近 6 小时。善用变量用模板变量提升复用性与交互性。为面板添加说明description 字段说明指标含义与解读方式降低接手成本。正确配置单位y 轴单位percent/s/bytes 等要语义正确。设定有意义的阈值颜色阈值对齐业务可容忍边界而非随意取值。跨仪表盘统一配色保持颜色语义如红色异常全站一致。用不同时间范围测试检查面板在 5m/6h/30d 等不同窗口下的表现避免采样导致的空窗或锯齿。九、Dashboard as CodeTerraform 与 AnsibleTerraform 声明式管理借助官方 Grafana Provider可将仪表盘纳入 Terraform 资源树实现版本化、可评审、可回滚resource grafana_dashboard api_monitoring { config_json file(${path.module}/dashboards/api-monitoring.json) folder grafana_folder.monitoring.id } resource grafana_folder monitoring { title Production Monitoring }grafana_folder创建Production Monitoring目录grafana_dashboard通过folder字段挂入该目录。config_json直接读取仪表盘 JSON 文件与前文的 Provisioning 文件共用同一份 JSON 资产。Ansible 批量分发对于已由文件 Provisioning 托管的 GrafanaAnsible 只需把 JSON 拷贝到options.path指定目录并重启服务- name: Deploy Grafana dashboards copy: src: {{ item }} dest: /etc/grafana/dashboards/ with_fileglob: - dashboards/*.json notify: restart grafanaTerraform 与 Ansible 两种方式与 observability-engineer agent 强调的 Observability as Code Automation包括 Terraform 模块、Ansible playbook、GitOps 工作流方向一致适合将监控配置纳入现有 IaC 管线。十、与相邻技能的组合从指标到 SLO 仪表盘grafana-dashboards技能文档在末尾标注了两个相关技能它们在本插件的可观测性链路中形成上下游协作prometheus-configurationSKILL.md负责指标采集。它提供 scrape 配置、recording rules 与告警规则模板并为仪表盘提供数据源。仪表盘中的表达式可大量复用其预定义的 recording rule如job:http_requests:rate5m、instance:node_cpu:utilization降低重复计算成本。slo-implementationSKILL.md负责 SLO 落地。它在 Prometheus 侧产出 SLI/SLO recording rules如sli:http_availability:ratio、slo:http_availability:error_budget_remaining与 burn rate 告警并在 SLO Dashboard 一节给出了 Grafana 侧的四段式面板结构┌────────────────────────────────────┐ │ SLO Compliance (Current) │ │ ✓ 99.95% (Target: 99.9%) │ ├────────────────────────────────────┤ │ Error Budget Remaining: 65% │ │ ████████░░ 65% │ ├────────────────────────────────────┤ │ SLI Trend (28 days) │ │ [Time series graph] │ ├────────────────────────────────────┤ │ Burn Rate Analysis │ │ [Burn rate by time window] │ └────────────────────────────────────┘对应的面板查询示例可直接作为 Stat / 时序面板的 expr# 当前 SLO 合规度百分比 sli:http_availability:ratio * 100 # 剩余错误预算百分比 slo:http_availability:error_budget_remaining # 按当前 burn rate 估算的剩余天数 (slo:http_availability:error_budget_remaining / 100) * 28 / (1 - sli:http_availability:ratio) * (1 - 0.999)这些表达式与Stat 面板 阈值着色结合即可快速构建出技能中描述的 SLO 大盘。此外slo-implementation 的详细模式文档 还提供了多窗口 burn rate 告警组合与 SLO 周/月/季度评审流程可作为构建 SLO 仪表盘后的配套运营机制。十一、如何安装与使用该技能技能是插件的组成单元可通过插件级或技能级两种方式获取机制详见 docs/usage.md插件级安装安装整个observability-monitoring插件后其 agents、commands/observability-monitoring:monitor-setup、/observability-monitoring:slo-implement与四个技能会一同进入上下文技能在任务匹配其描述时自动激活。技能级安装若只想单独使用本技能可借助 Agent Skills 安装器将其安装到任意支持的 agent 环境gh skill install wshobson/agents grafana-dashboards # GitHub CLI 2.90 npx skills add wshobson/agents --skill grafana-dashboards安装后你可以在对话中直接提出类似为支付服务创建一个包含 RED 指标和错误率告警的 Grafana 仪表盘的需求技能会自动提供本文所述的 JSON 结构、PromQL 与 Provisioning 方案再由你导入 Grafana 或纳入 Terraform/Ansible 管线。结语从设计原则、面板类型、模板变量、告警、Provisioning 到 IaC 落地grafana-dashboards技能覆盖了生产级仪表盘的完整生命周期。将其与插件内的prometheus-configuration数据采集和slo-implementation可靠性目标技能组合使用即可在 observability-monitoring 插件 内构建采集 → 可视化 → 告警 → SLO闭环的可观测性体系。如需端到端落地可进一步参考 monitor-setup 命令 中的完整监控栈示例Prometheus 配置、指标埋点、Tracing、日志聚合与 Alertmanager 路由。【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考