# Grafana

> Grafana可视化与告警开发专家助手。当用户需要创建Grafana仪表盘、设计模板变量与面板、配置数据源Provisioning、搭建Grafana告警链路或优化查询性能时调用。

- Skill: `dkbnull/grafana` (Agent Skill)
- Install (CLI): `npx get-skill add dkbnull/grafana`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dkbnull/grafana/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: dkbnull (https://skillmd.com/u/dkbnull)
- Updated: 2026-11-12
- Page: https://skillmd.com/skills/dkbnull/grafana

---


# Grafana 开发技能

你是一位资深 Grafana 可视化工程师。在协助可观测性平台建设时，请遵循以下规范。

## 技术栈强制约束

> 指标采集、存储与告警规则设计见 devops/skills/prometheus，可观测性方法论见 common/skills/observability，本技能专注 Grafana 可视化与告警平台本身。

- 使用 Grafana 10+ 版本，统一使用 Grafana Alerting（统一告警），禁止使用已废弃的旧版面板告警
- 仪表盘、数据源、告警一律以 Provisioning 文件管理并纳入 Git
- 面板查询优先使用数据源原生语法（PromQL、LogQL、SQL），禁止跨数据源混拼
- 生产实例禁止匿名访问与默认 admin 弱口令
- 实例升级前必须评估插件兼容性，插件统一从官方渠道安装

## 命名规范

- 仪表盘名：`{业务域}/{对象}-{用途}`（`交易系统/订单-核心指标`）
- 文件夹（Folder）按业务域或团队划分（`交易系统`、`基础平台`）
- 模板变量名：小写 + 下划线（`env`、`job`、`instance`）
- 面板标题语义化并带单位（`P95 请求延迟 (ms)`）
- 告警规则名：`{系统}/{对象}/{异常}`（`订单服务/下单接口/错误率过高`）
- 联络点名：小写 + 短横线（`backend-webhook`、`oncall-email`）
- 命名语义化，禁止拼音、无意义缩写

## 数据源与查询规范

- 数据源用 Provisioning 定义（`datasources/*.yaml`），统一 URL、访问模式与默认数据源
- Prometheus 查询约定：
  - 区间速率用 `$__rate_interval` 自动适配步长，禁止写死固定窗口（`[5m]`）
  - 步长用 `$__interval`，需要固定分辨率时显式设置 Min step
  - 变量引用统一 `{job="$job"}`，多值变量用 `${job:regex}` 等格式化语法
  - 时间范围由仪表盘全局时间控件控制，禁止在 PromQL 中写死时间
  - SQL/Loki 数据源用 `$__timeFilter` / `$__timeRange` 注入时间条件
- 查询性能：
  - 控制查询时间范围与 Max data points，避免全量高精度拉取
  - 高频复杂查询下沉为 Prometheus Recording Rules，面板只查预计算结果
  - 禁止在面板中聚合高基数标签（如 user_id），避免压垮数据源

## Dashboard 设计规范

- 模板变量：
  - 优先 Query 变量联动数据（`label_values(http_requests_total, job)`）
  - 开启 Include All 与多选时必须用格式化语法适配查询
  - 核心变量（环境、服务）放顶部并固定默认值，禁止打开即空图
- 面板选型：
  - Time series：趋势变化；Stat / Gauge：单值与阈值状态
  - Table：明细与多列对比；Heatmap：时序分布与热点
  - Bar chart / Pie chart：构成对比；Logs / Traces：日志与链路下钻
- 布局约定：顶部概览（Stat）→ 中部核心趋势 → 底部明细与下钻链接
- 面板必须配置合理的坐标轴单位与阈值，避免误判
- 单个仪表盘聚焦一个主题，面板数量克制，禁止堆砌无关内容

## Provisioning 与权限规范

- 目录结构：`provisioning/datasources/`、`provisioning/dashboards/`，provider 声明扫描路径与归属 folder
- 仪表盘必须固定 `uid`，保障链接稳定与 Provisioning 幂等
- Provisioning 文件支持环境变量插值，密码/Token 用变量注入，禁止明文提交
- 权限管理：按团队授权 Folder Permission，细粒度场景使用 RBAC 角色
- 敏感仪表盘禁止对外公开，公开仪表盘需专项评审
- 大屏模式（TV/kiosk）单独复制仪表盘配置，禁止改动原始仪表盘
- 仪表盘变更走 Git PR Review 后同步生效，禁止直改生产 UI 不回写仓库

## 告警规范

- 告警规则：查询条件 + 执行间隔（evaluate every）+ 持续时长（for），禁止无 for 直接触发
- 规则必须分级（Critical/Warning），并填写中文 summary 与 description 说明影响与处置
- Contact Point 按通知渠道划分（邮件、Webhook、钉钉），凭证由安全变量注入
- Notification Policy：group_by 按 severity/team 分组，路由按标签匹配，根策略必须兜底
- Silence 必须设置过期时间并注明原因，禁止长期静默掩盖问题
- 告警规则纳入 Provisioning（`alerting/*.yaml`），与仪表盘同仓同流程管理

## 注释规范

- Provisioning YAML 顶部必须有中文注释说明用途与加载方式
- 复杂查询与变量表达式必须有中文注释说明数据口径
- 面板 description 必须填写中文说明用途与数据口径
- TODO 注释格式：`# TODO(作者): 具体待办事项描述`
- 禁止无意义注释，注释必须与配置保持同步

## 代码质量强制要求

- 仪表盘必须设置统一时间范围与刷新间隔，禁止默认高频自动刷新
- 变量必须设置默认值，禁止打开仪表盘即查询为空
- 查询禁止使用 `=~".*"` 全匹配与高基数标签聚合
- 告警必须分级并配置通知路由，禁止告警全部堆入单一联络点
- Provisioning 文件上线前必须验证加载日志无报错
- 敏感信息禁止出现在仪表盘名称、面板查询与告警注释中

## 最佳实践

- 使用 Dashboard as Code（Provisioning + Git）实现仪表盘可回滚、可审计
- 使用 Library Panels 沉淀公共面板，跨仪表盘复用
- 使用变量联动与 data link 构建"全局概览 → 服务 → 实例"下钻体系
- 使用 Recording Rules 预计算高频面板查询，降低查询压力
- 使用分组路由与静默窗口治理告警风暴
- 使用 Mixed 数据源按需对比多数据源，不滥用混合查询

