基于 Agent 技能库构建生产级 Grafana 仪表盘：observability-monitoring 插件 grafana-dashboards 实战指南

2026-09-09 11:55:51作者：翟萌耘Ralph

本篇指南以 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-implementation（SLO 落地）共同构成一套完整的可观测性技能矩阵（见 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 second）
Errors：错误率（Error rate）
Duration：延迟/响应时间（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/red），fieldConfig.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 rule（instance: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）。
multi：namespace 单选（false），service 支持多选（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: "gt" + params: [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/dashboards

type: 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	磁盘吞吐与 IOPS
Network traffic	网络出入流量
Pod count by namespace	按命名空间统计 Pod 数量
Node status	节点在线状态（可用 `up` 或 kube-state-metrics 指标）

对应查询可参考 USE 方法：利用率类指标在 prometheus-configuration 技能的 recording rules 中已有现成模板（CPU/内存/磁盘利用率），可直接引用或在其上叠加饱和度（队列长度）与错误计数面板。

数据库仪表盘（Database）

Queries per second（每秒查询数）
Connection pool usage（连接池使用率）
Query latency P50 / P95 / P99（查询延迟分位）
Active connections（活跃连接数）
Database size（数据库体积）
Replication lag（复制延迟）
Slow queries（慢查询计数）

应用仪表盘（Application）

Request 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 Code：Terraform 与 Ansible

Terraform 声明式管理

借助官方 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 托管的 Grafana，Ansible 只需把 JSON 拷贝到 options.path 指定目录并重启服务：

- name: Deploy Grafana dashboards
  copy:
    src: "{{ item }}"
    dest: /etc/grafana/dashboards/
  with_fileglob:
    - "dashboards/*.json"
  notify: restart grafana

Terraform 与 Ansible 两种方式与 observability-engineer agent 强调的 "Observability as Code & Automation"（包括 Terraform 模块、Ansible playbook、GitOps 工作流）方向一致，适合将监控配置纳入现有 IaC 管线。

十、与相邻技能的组合：从指标到 SLO 仪表盘

grafana-dashboards 技能文档在末尾标注了两个相关技能，它们在本插件的可观测性链路中形成上下游协作：

prometheus-configuration（SKILL.md）：负责指标采集。它提供 scrape 配置、recording rules 与告警规则模板，并为仪表盘提供数据源。仪表盘中的表达式可大量复用其预定义的 recording rule（如 job:http_requests:rate5m、instance:node_cpu:utilization），降低重复计算成本。
slo-implementation（SKILL.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 路由）。

agents

Multi-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity

项目地址：https://gitcode.com/GitHub_Trending/agents24/agents

登录后查看全文