可观测性告警文档【免费下载链接】awesome-prometheus-alerts Collection of Prometheus alerting rules项目地址https://gitcode.com/gh_mirrors/aw/awesome-prometheus-alerts点击查看免费下载本篇指南面向希望向 awesome-prometheus-alerts 贡献的开发者完整讲解两条主流贡献路径向 _data/rules.yml 新增 Prometheus 告警规则含字段规范、描述撰写要求与 promtool 回归测试流程以及基于 Astro TypeScript 在 site/ 下本地运行与改进规则展示网站。读完本文你将掌握规则数据模型、可复制 YAML 的生成逻辑、站点本地开发环境搭建以及从粘贴告警到 issue到提交规范化 PR的完整工作流。一、贡献概览项目欢迎哪些形式的社区参与项目在 README.md 中明确欢迎社区贡献参与方式包括编写代码、新增告警规则、完善文档、报告 issue、讨论更优的错误追踪方案等。而 CONTRIBUTING.md 将技术贡献收敛为两个核心方向添加告警规则Adding alerting rule面向所有使用者门槛最低——即使没有时间编写 PR也可以直接把告警粘贴到 issue 中由维护者代为格式化。改进网站Improving the website面向有一定前端经验的开发者基于 Astro TypeScript 维护规则展示站。两条路径的产出物在仓库中各自对应规则数据沉淀在 _data/rules.yml网站源码位于 site/。二、新增告警规则数据文件与数据结构所有告警规则都集中存放在仓库根目录的 _data/rules.yml当前仓库约 8000 行这是新增规则时唯一需要修改的文件。注意该文件头部注释明确指出其 YAML 不能直接复制到 Prometheus 配置中使用需访问站点/rules页面获取格式化后的可复制片段——因为仓库保存的是数据真正的 Prometheus 规则 YAML 由构建/生成流程产出。2.1 数据模型groups → services → exporters → rules从数据文件与 site/src/data/rules.ts 中的 TypeScript 接口可以完整还原其四层数据模型groups: - name: Basic resource monitoring # 分组如数据库、消息中间件、CI/CD services: - name: Prometheus self-monitoring # 服务如 Redis、Kubernetes logo: /images/services/prometheus-self-monitoring.svg # 必须存在的 Logo 路径 exporters: - slug: embedded-exporter # Exporter 唯一标识 rules: - name: Prometheus target missing # 规则名称 description: A Prometheus target has disappeared... # 描述 query: up 0 unless on(job) (sum by (job) (up) 0) # PromQL 查询 severity: critical # critical / warning / info for: 1m # 持续时间可选 comments: | # 可选补充说明多行 Only fire if at least one target in the job is still up.对应 rules.ts 中定义的接口如下Groupnameservices[]对应页面路由中的分组slug 化后为basic-resource-monitoring等Servicename、logo、exporters[]一个服务可挂多个 exporter例如 MongoDB 下有 3 个 exporterExporterslug唯一标识可选name、doc_url、commentsrules[]Rulename、description、query、severitycritical | warning | info可选的for与comments。2.2 规则字段逐项说明字段是否必填说明name必填规则显示名最终会经toCamelCase转换为 Prometheus 的alert:名因此建议用空格分隔的自然语言短句如Prometheus target missing→PrometheusTargetMissingdescription必填事实性描述回答 what?并尽量给出根因建议回答 why?详见第三节query必填PromQL 表达式会被原样嵌入生成后的expr:字段severity必填取值critical/warning/info影响页面徽标与告警标签severityfor可选持续时间缺省在生成时补为0m见 formatRuleAsYamlcomments可选多行文本说明适用前提、注意事项或替换提示生成 YAML 时会被转换为#注释行2.3 从数据到可复制 YAML底层生成逻辑新增规则后站点与dist/产物通过 site/src/data/rules.ts 中的formatRuleAsYaml/formatExporterAsYaml完成数据 → Prometheus 规则 YAML的转换这也是理解为什么必须访问 /rules 页面复制的关键// site/src/data/rules.ts export function formatRuleAsYaml(rule: Rule): string { const alertName toCamelCase(rule.name); // Prometheus target missing → PrometheusTargetMissing const forValue rule.for ?? 0m; // 未填写 for 时生成 0m ... return ${commentLines}- alert: ${alertName} expr: ${rule.query} for: ${forValue} labels: severity: ${rule.severity} annotations: summary: ${rule.name} (instance {{ $labels.instance }}) description: ${description}\\n VALUE {{ $value }}\\n LABELS {{ $labels }}; }可见生成逻辑约定俗成地补充了summary、VALUE、LABELS等模板字段并自动处理描述中的双引号转义comments被转成#注释行。toCamelCase实现位于 rules.ts每个单词首字母大写、其余小写后拼接——这与dist下载文件中的capitalize过滤规则保持一致确保页面复制的片段与可下载的规则文件逐字相同。三、贡献指南Guidelines逐条解读CONTRIBUTING.md 为 PR 提出了四条硬性规范每一条都对应着仓库的实际工程实践先搜索历史建议避免重复Search previous suggestions before making a new one新增前先浏览 _data/rules.yml 或站点规则页确认是否已有等价规则。从数据文件看一个服务往往聚合多个 exporter 的规则重复会显著增加维护成本。描述保持简短但足够具描述性Keep descriptions short and simple, but descriptive例如Prometheus target missing的描述A Prometheus target has disappeared. An exporter might be crashed.——一句话交代现象与最可能的原因。描述必须事实化what?并给出根因建议why?以Prometheus target scrape out of order为例描述明确写到Prometheus is dropping samples because their timestamps arrive out of order ({{ $value }} samples in the last 5 minutes), indicating a misbehaving target or clock skew.——既陈述样本乱序被丢弃的事实又给出目标异常或时钟偏移的排查方向这正是社区追求更快定位问题的写法。{{ $value }}等模板变量可直接嵌入描述生成时原样保留。查询必须在最新 exporter 版本上测试Queries must be tested on latest exporter versionPromQL 依赖 exporter 暴露的指标名版本升级可能导致指标变更因此规则查询必须绑定最新版本验证。四、零门槛路径直接粘贴告警到 issue如果时间紧张、不熟悉 PromQL 或 Git 工作流CONTRIBUTING.md 提供了最轻量的参与方式把告警若干条均可直接复制粘贴到 issue 中维护者会负责按规范格式化并合入。这条路径的实质是数据优先理念——只要提供足够准确的name / description / query / severity / for / comments信息后续的 YAML 排版、slug 生成、页面渲染均可自动化完成参见 rules.ts 的格式化函数族。五、规则的验证promtool 回归测试仓库为规则质量提供了严格的回归测试体系相关说明见 test/README.md。在仓库根目录执行# 1. 用发布工作流同款 Liquid 模板渲染规则文件 bash test/generate.sh # 2. 校验全部渲染出的规则文件语法 promtool check rules test/rules/*/*.yml # 3. 执行针对完整规则文件的单元测试含 labels、annotations 与 pending 时长 promtool test rules test/*.test.yml依赖工具Ruby、liquid-cli、mikefarah/yq、jq 与 promtooltest/generate.sh 用yq -I 0将 _data/rules.yml 转为 JSON再经dist/template.yml的 Liquid 模板逐 exporter 渲染到test/rules/——与发布工作流共用同一模板因此生成的测试文件与线上产物严格一致生成的test/rules/文件被 gitignore应修改_data/rules.yml而不是dist/rules/现有的 kubernetes.test.yml、spark.test.yml、azure.test.yml、gitlab.test.yml 是规则级回归测试样例合成样本严格遵循各 producer 的指标契约如 Spark 时长指标单位为秒、Kubernetes 证书直方图边界、GitLab 队列时长桶上限 60 秒不虚构任何指标名或桶边界。这意味着新增或修改规则后理想流程是修改 _data/rules.yml → 补充/更新test/*.test.yml断言 → 运行上述三连命令确保通过 → 提交 PR。六、改进网站Astro TypeScript 本地开发网站源码位于 site/采用 Astro当前版本 ^7.2.8见 site/package.json配合 TypeScript 与 Tailwind CSS 4 构建。6.1 本地运行CONTRIBUTING.md 给出的标准三步cd site npm install npm run dev启动后站点默认服务于http://localhost:4321/awesome-prometheus-alerts。6.2 常用脚本除dev外site/package.json 还提供了以下命令命令作用npm run build生产构建astro build并运行 Pagefind 生成站内全文索引输出到public/pagefindnpm run preview本地预览生产构建产物npm run checkastro check类型与 Astro 语法校验npm run lintESLint 检查基于 eslint.config.jsnpm run pagefind单独重建站内搜索索引6.3 数据如何流向页面理解站点结构对贡献很有帮助关键调用链如下_data/rules.yml 由 Vite YAML 插件在构建期注入 site/src/data/rules.ts统一封装为GroupsData并导出data规则页路由位于 site/src/pages/rules/[group]/[service].astro负责按分组/服务 slug 渲染规则详情页每条规则由 RuleCard.astro 渲染为卡片包含SeverityBadge严重级别徽标、规则编号与锚点链接并通过formatRuleAsYaml生成可复制的 YAML 代码块 CopyButton一键复制全站统计规则总数、服务数、exporter 数由getTotalRuleCount、getTotalServiceCount、getTotalExporterCount等函数计算见 rules.ts。6.4 需要注意的构建期约束rules.ts 中有一段值得新贡献者注意的构建期校验每个 Service 必须配置logo:字段且对应图片文件必须存在于site/public/images/services/否则astro build会直接抛错失败。因此新增一个 Service 时需要同步放置 Logo 文件参见 site/public/images/services/ 下已有的各类服务图标logo路径以/images/services/...形式写在_data/rules.yml中该硬校验保证了新增服务不会出现无图标降级为纯文字卡片的线上缺陷。七、PR 合入前的自检清单综合 CONTRIBUTING.md 与仓库工程实践提交新增告警规则或网站改动前请逐项确认无重复已在 _data/rules.yml 与站点规则页中搜索过既有规则字段完整name / description / query / severity四项齐备for / comments按需补充描述合规事实性what? 根因提示why?简短且可读查询已验证在最新 exporter 版本上实测过 PromQL产出指标名与文档一致回归通过按第五节流程运行bash test/generate.sh与promtool check/test并视需要补充test/*.test.yml断言构建无碍涉及网站改动时新增 Service 必带 Logo本地npm run dev/npm run build与npm run check/npm run lint全部通过。遵循以上流程你的贡献即可顺畅地进入这一 Prometheus 告警规则集合被全球社区检索、复制与复用。赞分享可观测性告警文档【免费下载链接】awesome-prometheus-alerts Collection of Prometheus alerting rules项目地址https://gitcode.com/gh_mirrors/aw/awesome-prometheus-alerts点击查看免费下载相关推荐【实战指南】三步搞定NoteDiscovery云原生知识库容器化部署【实战指南】三步搞定NoteDiscovery云原生知识库容器化部署 NoteDiscovery是一款现代化的自托管知识库应用专为注重数据隐私和完全控制权的用后端前端知识管理MCP 服务Prometheus告警规则监控告警系统集成awesome-prometheus-alerts与CA AlertsPrometheus告警规则监控告警系统集成awesome prometheus alerts与CA Alerts 你是否还在为系统监控告警配置繁琐而烦恼是可观测性告警文档上一篇Building ML Powered Applications进阶指南从基础到高级的模型迭代策略下一篇EchoTrace轻松备份微信聊天记录的本地安全解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考