2. Grafana 基础回顾：数据源配置、面板类型、查询编辑器、仪表板变量、告警规则
在进入跨团队适配工程之前，必须统一团队对 Grafana 核心基础能力的认知。本章聚焦五个基础支柱：数据源、面板、查询、变量与告警。这些要素构成任何仪表板的原子单元，也是后续模板标准化与适配的底层操作对象。
2.1 数据源配置：仪表板的连接层
数据源是 Grafana 与后端存储之间的桥梁。每个面板必须绑定一个数据源才能渲染图表。Grafana 支持超过 40 种数据源类型，跨团队适配中最常遇到的类型如下：
| 数据源类型 | 典型场景 | 连接方式 | 版本兼容要点 |
|---|---|---|---|
| Prometheus | 容器/微服务指标 | HTTP API | PromQL 版本、label 命名规范 |
| InfluxDB | 时序事件流 | Flux / InfluxQL | Bucket 名称、measurement 结构 |
| Elasticsearch | 日志/全文检索 | REST API | 索引模式、时间字段映射 |
| MySQL / PostgreSQL | 业务数据库 | JDBC 连接串 | 时区设置、SQL 安全限制 |
| CloudWatch | AWS 基础设施 | IAM 角色/密钥 | Region、命名空间、维度 |
适配要点： 跨团队模板必须将数据源名称作为变量暴露，而非硬编码。不同团队可能使用不同的 Prometheus 实例或 InfluxDB Bucket，通过变量切换可避免重复创建面板。
2.2 面板类型：可视化原子
Grafana 提供 20+ 原生面板类型。在标准模板中，我们只选用 6 种核心面板 作为构建块，其余面板按需引入。下表列出这 6 种面板及其适配属性：
| 面板类型 | 用途 | 适配时需关注的属性 |
|---|---|---|
| Time series | 时序趋势、多线对比 | 轴线单位、阈值线、图例模式 |
| Stat | 单一数值、KPI 卡片 | 颜色模式、小数位、背景色阈值 |
| Table | 结构化数据、明细列表 | 列宽、排序、单元格链接 |
| Bar gauge | 资源水位、容量视图 | 显示模式、最小值/最大值 |
| Pie chart | 占比分布、分类汇总 | 标签位置、值格式 |
| Logs | 实时日志流、搜索 | 时间戳格式、行包装 |
模板原则： 标准模板只使用上述 6 种面板。如果团队需要特殊面板（如 Heatmap、Geomap），应在模板中预留占位面板并标注“需团队自行替换”。
2.3 查询编辑器：数据提取语言
查询编辑器是面板与数据源之间的翻译层。不同数据源使用不同的查询语言，但 Grafana 提供了统一的编辑器界面。以下是三种最常用查询语言的对比：
| 语言 | 数据源 | 典型查询结构 | 适配变量注入方式 |
|---|---|---|---|
| PromQL | Prometheus | rate(http_requests_total[5m]) |
$namespace 或 {{.namespace}} |
| Flux | InfluxDB | from(bucket: "telegraf") |> range(start: -1h) |
v.bucket 或字符串插值 |
| SQL | MySQL/PostgreSQL | SELECT count(*) FROM orders WHERE time > now() - interval '1h' |
$__timeFilter + $team_id |
// PromQL 示例：带变量的查询
rate(
http_requests_total{
namespace="$namespace",
job=~"$job_regex"
}[5m]
)
常见陷阱： 不同团队对同一指标可能有不同的 label 命名（如
env vs environment）。模板中的查询必须使用变量映射层，而非直接写死 label 名称。
2.4 仪表板变量：模板化的核心
变量是 Grafana 仪表板实现动态化的关键机制。通过变量，一个模板可以适配多个团队、多个环境、多个服务。变量分为以下 6 种类型：
- Query 变量：从数据源动态拉取值列表（如
label_values(namespace)） - Custom 变量：手动定义固定选项（如
prod,staging,dev） - Interval 变量：时间间隔选择（如
1m,5m,15m,1h） - Data source 变量：动态切换数据源实例
- Text box 变量：自由输入文本（如服务名、标签过滤）
- Constant 变量：隐藏的固定值，用于跨面板引用
标准模板必须包含以下 5 个必备变量：
| 变量名 | 类型 | 用途 | 默认值 |
|---|---|---|---|
$datasource |
Data source | 切换数据源实例 | default |
$namespace |
Query | K8s 命名空间或逻辑分组 | default |
$service |
Query | 微服务或应用名称 | all |
$interval |
Interval | 聚合粒度 | 1m |
$env |
Custom | 环境标签 | prod |
2.5 告警规则：从可视化到主动通知
Grafana 告警系统在 v8+ 之后全面重构为统一告警引擎。标准模板中的告警规则必须遵循以下结构：
- 告警规则组：按服务或维度分组，每组包含多条规则
- 表达式：基于面板查询或独立 PromQL/SQL 表达式
- 条件：阈值（IS ABOVE / IS BELOW / IS OUTSIDE_RANGE）
- 评估行为：频率（如每 1m）、挂起时间（Pending 窗口）
- 通知策略：路由到 Slack、PagerDuty、Webhook 等
| 告警属性 | 模板化要求 | 适配差异点 |
|---|---|---|
| 阈值 | 使用变量 $threshold_cpu |
不同团队对 CPU 阈值容忍度不同（80% vs 90%） |
| 评估频率 | 固定为 1m | 高频场景可下调至 30s，但需评估数据源压力 |
| 通知渠道 | 使用 Contact point 变量 | 团队 A 用 Slack，团队 B 用 Teams |
| 标签 | 自动注入 team、env 标签 |
用于告警路由和静默规则 |
// 告警规则示例（Grafana 统一告警格式）
groups:
- name: cpu_alert_group
interval: 1m
rules:
- alert: HighCPUUsage
expr: |
avg by (namespace, service) (
rate(container_cpu_usage_seconds_total[5m])
) * 100 > $threshold_cpu
for: 5m
labels:
severity: critical
team: "{{ $team_name }}"
annotations:
summary: "CPU 使用率超过 {{ $threshold_cpu }}%"
模板化告警的优势： 通过变量控制阈值、标签和通知渠道，一个告警规则模板可以同时适配开发、测试、生产环境，无需为每个环境复制规则。