Community生产力与协作github.com

grafana-observability

学习、设计、构建和运行以代码管理的 Grafana 可观测性栈(Prometheus 指标、Loki 日志、Tempo 追踪、Alloy 采集、Grafana 仪表盘和告警)。适用于被要求学习或教授 Grafana、PromQL 或 LogQL;设置监控;编写或审查仪表盘、告警规则、通知策略、联系人点、Alloy 管道或 Grafana Terraform;或调试告警(嘈杂、静默、卡在 NoData 状态或无法通知到人)的场景。

grafana-observability 是什么?

这是一个生产级自托管 Grafana 可观测性栈的实战技能,包含约 60 个仪表盘、400 多条告警规则、50 个抓取任务,以及日志和追踪,全部以代码管理。每条规则的存在都源于真实故障案例,并解释了“为什么”以帮助你判断边界情况。 该技能支持学习和构建两种模式:学习模式会按阶段引导你逐步学习(配合本地 Docker Compose 实验室),构建模式则提供从仪表盘、告警、管道到 Terraform 的完整工作流程。其硬性规则涵盖了作为单一真理源的代码管理、Terraform 漂移检查、联系人点配置陷阱、阈值设置误区、告警路由设计以及监控自身的监控等多个方面。 适用于 Grafana、Prometheus、Loki、Tempo 和 Alloy 等主流可观测性平台,技能中还提供了详细的参考文件索引和 Terraform 启动模板。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/louij2/grafana-observability-skill/tree/HEAD/.github/skills/grafana-observability

Installed? Explore more 生产力与协作 skills: steipete/gemini, steipete/gh-issues, steipete/skill-creator · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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。

硬性规则

  1. 代码是唯一的真理源。 通过 Terraform 更改告警,使用生成器脚本或存放在 git 中的 JSON 构建仪表盘。在 UI 中的一个点击会在下次 apply 时丢失,或者更糟,下次 apply 会静默地将其还原。
  2. 在任何 apply 之前,检查两种类型的漂移。 (a) 线上存在但不在代码中的规则:无目标的 apply 会 删除 它们。 (b) 在代码中但已在线上被更改的规则:apply 会 还原 它们。一个“没有变化”的计划并不能证明 Terraform 从未见过的规则是安全的。参见 references/as-code.md。
  3. 保护保存的计划。 运行 terraform plan -out,然后拒绝任何你未预期的 delete/replace 操作,对 任何 资源都要这样。在文件夹上使用 prevent_destroy。删除 Grafana 文件夹会删除其中的所有仪表盘和规则。
  4. 使用服务账户令牌,永远不要用 admin:password。 如果状态是在令牌认证下创建的,那么一个 basic-auth 的 apply 将计划删除并重新创建文件夹、联系人点和策略树。这曾经在一次 apply 中清除了 59 个仪表盘和整个路由树。
  5. 绝不要将 notification_settings(联系人点)放在规则上。 设置了此选项的规则会完全跳过策略树。它会避开严重性路由、重复间隔和静默时间。在一个环境中,217 条规则中有 196 条这样做了,而没有人注意到。
  6. 将阈值放在 Grafana 的阈值阶段,而不是 PromQL 内部。 使用 expr > 90,一个健康的主机不会返回任何数据序列,Grafana 将其读作 NoData,而不是 OK。查询原始值;在阶段 C 中比较。
  7. 根据可操作性路由,并将重复间隔视为真正的杠杆。 使用 severity(critical/warning/info)加上 urgency=backlog 来处理慢性、已知的问题。大多数告警噪音是针对已知问题的重复通知。每天重复严重告警,每周重复警告,而不是每小时。
  8. 升级应该是一个延迟,静默就是确认。 分页路由使用大约 15 分钟的 group_wait,因此只有当告警仍在触发且未被静默时才会分页。事件风格的规则需要 keep_firing_for ≥ 等待时间,否则它们会在升级之前就解除。
  9. 监控监控本身。 关注评估失败、通知投递失败、被抑制(静默)的告警、过期的导出器以及已停止的备份。一个静默的告警系统看起来就像一个健康的系统。参见 references/meta-monitoring.md。
  10. 验证,不要信任。 在编写之前 先 对数据源运行每个面板或告警查询。每次 API 写入后,读回对象 并断言你的更改已经生效:POST 响应不会告诉你上传的内容是什么。两个人或两次会话之间的认同并不是验证;一个命令才是。

任何变更的工作流程

  1. 陈述问题:这个面板或告警回答什么问题,谁会对其采取行动。如果没有人会因为一个告警而采取行动,那它就是一个仪表盘面板,而不是告警。
  2. 证明查询:在 Explore 或通过数据源代理 API 中验证。检查它是否返回数据,你将要分组或路由的标签是否正确,以及它在健康状态下如何表现(空?零?)。
  3. 以代码形式编写:一个 Terraform 规则组、仪表盘生成器或 Alloy 配置。遵循 references/alerting.md 或 references/dashboards.md。
  4. 检查漂移,然后运行 terraform plan -out=tfplan。阅读每个折叠的 ~ 块,特别是 grafana_notification_policy 上的,因为它决定了 每个 告警的去向。
  5. 应用保存的计划,使用服务账户令牌。如果不确定,使用 -target。
  6. 从 API 读回,确认规则正在评估(状态不是 Error/NoData),对于告警,端到端向真实联系人点发送一个测试。
  7. 提交,并附带 原因。在代码中选择看起来错误但经过深思熟虑的地方留下注释。

完成定义

告警规则:在 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.mdTerraform、API、备份、漂移、恢复
meta-monitoring.md证明监控本身在正常工作
implementation-plan.md向团队或公司引入 Grafana

资源:assets/lab/ 是一个本地 Docker Compose 实验环境。 assets/terraform-starter/ 是一个 Terraform 启动栈,已预设安全默认值。

相关技能