Grafana 可观测性
以下是来自一个生产级自托管栈的实践经验:约 60 个仪表盘、400+ 条告警规则、50 个抓取任务,以及日志和追踪,全部以代码管理。每条规则的存在都源于一次真实故障。给出了 为什么,以便你判断边界情况。
先选择模式
- 学习(“教我”、“解释”、“什么是”、“测验我”):遵循 references/learning-path.md。一次教一个阶段,并在 assets/lab/ 中运行实验。在继续之前检查理解情况。不要一次性倾倒所有阶段。
- 构建(仪表盘、告警、管道、Terraform 或发布):遵循下面的工作流程,并且只打开任务需要的那个参考文件。
- 在组织中规划发布:references/implementation-plan.md。
一目了然:栈架构
应用 / 主机 / 网络设备 / 云 API
│ 指标(导出器、/metrics) │ 日志(文件、docker、syslog) │ 追踪(OTLP)
▼ ▼ ▼
Prometheus ◄── 抓取 ── Grafana Alloy(采集器:发现、重新标记、编辑、发送)
│ │ │
│ Loki Tempo
└──────────────┬──────────────────┴──────────────────────────────┘
▼
Grafana ── 仪表盘、Explore、告警 ──► 联系人点(聊天、邮件、值班)
▲
Terraform(文件夹、数据源、规则、路由)+ 脚本(仪表盘)+ git
详情:references/architecture.md。
硬性规则
- 代码是唯一的真理源。 通过 Terraform 更改告警,使用生成器脚本或存放在 git 中的 JSON 构建仪表盘。在 UI 中的一个点击会在下次 apply 时丢失,或者更糟,下次 apply 会静默地将其还原。
- 在任何 apply 之前,检查两种类型的漂移。 (a) 线上存在但不在代码中的规则:无目标的 apply 会 删除 它们。 (b) 在代码中但已在线上被更改的规则:apply 会 还原 它们。一个“没有变化”的计划并不能证明 Terraform 从未见过的规则是安全的。参见 references/as-code.md。
- 保护保存的计划。 运行
terraform plan -out,然后拒绝任何你未预期的delete/replace操作,对 任何 资源都要这样。在文件夹上使用prevent_destroy。删除 Grafana 文件夹会删除其中的所有仪表盘和规则。 - 使用服务账户令牌,永远不要用
admin:password。 如果状态是在令牌认证下创建的,那么一个 basic-auth 的 apply 将计划删除并重新创建文件夹、联系人点和策略树。这曾经在一次 apply 中清除了 59 个仪表盘和整个路由树。 - 绝不要将
notification_settings(联系人点)放在规则上。 设置了此选项的规则会完全跳过策略树。它会避开严重性路由、重复间隔和静默时间。在一个环境中,217 条规则中有 196 条这样做了,而没有人注意到。 - 将阈值放在 Grafana 的阈值阶段,而不是 PromQL 内部。 使用
expr > 90,一个健康的主机不会返回任何数据序列,Grafana 将其读作 NoData,而不是 OK。查询原始值;在阶段 C 中比较。 - 根据可操作性路由,并将重复间隔视为真正的杠杆。 使用
severity(critical/warning/info)加上urgency=backlog来处理慢性、已知的问题。大多数告警噪音是针对已知问题的重复通知。每天重复严重告警,每周重复警告,而不是每小时。 - 升级应该是一个延迟,静默就是确认。 分页路由使用大约 15 分钟的
group_wait,因此只有当告警仍在触发且未被静默时才会分页。事件风格的规则需要keep_firing_for≥ 等待时间,否则它们会在升级之前就解除。 - 监控监控本身。 关注评估失败、通知投递失败、被抑制(静默)的告警、过期的导出器以及已停止的备份。一个静默的告警系统看起来就像一个健康的系统。参见 references/meta-monitoring.md。
- 验证,不要信任。 在编写之前 先 对数据源运行每个面板或告警查询。每次 API 写入后,读回对象 并断言你的更改已经生效:POST 响应不会告诉你上传的内容是什么。两个人或两次会话之间的认同并不是验证;一个命令才是。
任何变更的工作流程
- 陈述问题:这个面板或告警回答什么问题,谁会对其采取行动。如果没有人会因为一个告警而采取行动,那它就是一个仪表盘面板,而不是告警。
- 证明查询:在 Explore 或通过数据源代理 API 中验证。检查它是否返回数据,你将要分组或路由的标签是否正确,以及它在健康状态下如何表现(空?零?)。
- 以代码形式编写:一个 Terraform 规则组、仪表盘生成器或 Alloy 配置。遵循 references/alerting.md 或 references/dashboards.md。
- 检查漂移,然后运行
terraform plan -out=tfplan。阅读每个折叠的~块,特别是grafana_notification_policy上的,因为它决定了 每个 告警的去向。 - 应用保存的计划,使用服务账户令牌。如果不确定,使用
-target。 - 从 API 读回,确认规则正在评估(状态不是 Error/NoData),对于告警,端到端向真实联系人点发送一个测试。
- 提交,并附带 原因。在代码中选择看起来错误但经过深思熟虑的地方留下注释。
完成定义
告警规则:在 Terraform 中;设置了 severity 标签;摘要和描述模板包含受影响的主机或服务以及当前值;有意选择了 no_data_state;for 时间足够长以防止抖动;通过树状路由(无规则级联系人点);描述中包含操作手册链接或第一步;经过端到端测试;不与现有规则重复分页。
仪表盘:在 git 中(生成,或导出的 ID/版本已剥离);位于正确的文件夹中;从概览中心链接并可返回;包含环境/主机的变量;每个面板都有一个提问或回答问题的标题;设置了单位和阈值;在链接上设置了 keepTime。
新导出器或数据源:使用稳定标签(env、team、service、role)进行抓取;被集群 up == 0 规则覆盖(不要添加单独的规则);如果它有最后运行时间或新鲜度指标,则需要一个过时规则;已添加到元监控审计;数据源具有 固定的 uid。
参考索引
| 文件 | 何时打开 |
|---|---|
| learning-path.md | 教学或学习,配合实验逐步进行 |
| architecture.md | 选择组件、标签、保留期、认证、高可用 |
| queries.md | 编写 PromQL 或 LogQL,或查询看起来不对 |
| dashboards.md | 构建或审查仪表盘 |
| alerting.md | 规则、路由、联系人点、静默、疲劳度 |
| as-code.md | Terraform、API、备份、漂移、恢复 |
| meta-monitoring.md | 证明监控本身在正常工作 |
| implementation-plan.md | 向团队或公司引入 Grafana |
资源:assets/lab/ 是一个本地 Docker Compose 实验环境。 assets/terraform-starter/ 是一个 Terraform 启动栈,已预设安全默认值。