1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | prometheus-cardinality-troubleshooter-grafana-skills |
| 作者/维护者 | Grafana Labs（grafana 官方组织，提交者 Matthew Wimpelberg，GitHub 账号资料标注所属公司为 Grafana Labs） |
| 来源链接 | https://github.com/grafana/skills/tree/main/skills/grafana-cloud/prometheus-cardinality-troubleshooter |
| 许可证 | Apache-2.0（GitHub API 获取，仓库级） |
| GitHub Stars / Forks | 合集仓库整体 203 / 17（GitHub API 获取；该数字属整个 grafana/skills 合集，不代表本技能自身热度，取证方式见第 7 章） |
| 最新版本 | SKILL.md 未单列版本号，随所属 grafana-cloud 插件组（marketplace.json 声明 version 0.1.0）一起发布 |
| 安装方式 | Claude Code 插件市场 / npx skills add（详见第 10 章） |
2. 功能介绍与亮点
prometheus-cardinality-troubleshooter 是一份面向“正在发生”的 Prometheus 基数事故的实时排障指南，核心是一套系统化的诊断流程与安全护栏：
- “唯一铁律”前置警告：开篇即警告——压力下最容易犯的错是对
pod、instance等能让序列变得唯一的标签做labeldrop。这看似止血，实际会让不同序列的 counter reset 相互污染，导致rate()/increase()返回离谱数值，且配置层完全不报错，事后极难追溯 - 症状 → 病因速查表：把“Prometheus OOM”“单条查询超时”“429 采样超限”“Grafana Cloud 账单暴涨”等 7 种典型症状，各自映射到明确的排查步骤
- 五步排障流程：活跃序列体检（
prometheus_tsdb_head_series+/api/v1/status/tsdb接口）→ 逐指标下钻 → 近期变更比对 → 序列churn诊断，每步都附带可直接执行的 PromQL/curl 命令 - 高发病因图鉴：Histogram 爆炸（bucket 放大 14 倍）、kube-state-metrics 标签泛滥、路径/路由参数直接入标签、应用标签与采集目标标签冲突、联邦放大效应等 5 类常见场景各配“识别特征+修复方法”
- 安全的应急处置模式：唯一允许的“立即止血”手段是整体丢弃某个指标（而非删除让序列唯一的标签），并给出 Prometheus/Grafana Alloy 双语法的可复制配置片段
3. 适用场景
所属分类：DevOps 与基础设施
适合正在运维 Prometheus 或已接入 Grafana Cloud 指标的 SRE、平台工程师：当 Prometheus 内存暴涨被 OOMKilled、某条 PromQL 查询变慢或超时、429 Too Many Samples 报错、或 Grafana Cloud 账单突然升高时，用一句“帮我排查一下 Prometheus 基数问题”即可获得从定位病因到安全修复的完整路径，避免在压力下用错误的 labeldrop 操作把数据搞坏。
4. 跨 Agent 兼容性
- Claude Code：原生支持——README 给出具体命令：
claude plugin marketplace add grafana/skills后claude plugin install grafana-cloud@grafana-skills - Codex：官方支持——README “Codex and other Agent Skills tools” 专节说明技能通过仓库根
.agents-plugin/marketplace.json清单自动发现，无需手动配置 - OpenClaw：未验证——抓取材料未点名，仅笼统声明兼容“任何遵循 Agent Skills 开放标准的工具”
- Hermes Agent：未验证，理由同上
5. 推荐理由
高基数问题是 Prometheus 生产环境里最常见的“半夜报警”之一，而压力之下最直觉的处置方式（删掉造成基数暴涨的标签）恰恰是最危险的操作——它不报错，却会悄悄污染历史数据。这个技能把“哪些操作绝对不能做”放在最前面反复强调，再给出从症状到病因、从病因到安全修复的完整路径，且核心排障流程只依赖用户自己已有的 Prometheus /api/v1/status/tsdb 接口，不需要额外购买 Grafana Cloud 订阅或配置任何 MCP 服务，装完即可用。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | Grafana Labs 官方出品，子技能自身 2 次提交（2026-05-27、2026-06-03），作者与同合集仓库姊妹技能 prometheus-label-strategy 同为 Grafana Labs 员工 Matthew Wimpelberg；仓库整体持续活跃（GitHub API 复核 pushed_at 为 2026-07-27），但未见该子技能专属的第三方独立评价 |
| 可用性 | 8 | 单文件 SKILL.md 结构完整（症状速查表、五步排障流程、病因图鉴、决策树、应急代码片段五段式），核心诊断流程只需现有 Prometheus /api/v1/status/tsdb 接口即可使用，不强制要求 Grafana Cloud 订阅或额外 MCP 配置；最近一次提交 2026-06-03，距今约 8 周，仍在近期维护窗口内 |
| 安全性 | 9 | 见下方检查清单 |
| 综合 | 8.0 | 三项均值 |
安全检查清单：
| 检查项 | 结果 |
|---|---|
| ① Shell 命令与权限范围 | 技能本身不自动执行任何操作；文中的 curl/PromQL/YAML 片段是提供给用户参考、按需手动运行或采纳的诊断与修复建议，均为只读查询（/api/v1/status/tsdb、PromQL 查询）或需用户主动应用的配置改动 |
| ② 联网外发 | 无网络请求，不外发任何数据 |
| ③ 凭据存储 | 不索取任何 API Key 或凭据；示例中对 Grafana Cloud 的认证信息由用户自行提供 |
| ④ 可疑指令 | 全文为排障流程、症状对照表与修复模板，反复强调“先测试再上生产”，未发现提示注入或隐蔽指令 |
| ⑤ 作者信誉 | Grafana Labs 为知名开源可观测性厂商，grafana 为其官方 GitHub 组织，提交者实名可查、所属公司字段与仓库定位相符 |
| ⑥ License | Apache-2.0，明确（仓库级） |
| ⑦ 维护时间 | 子目录最近一次提交 2026-06-03，约 8 周前，非弃置项目 |
7. 跟同类 Skills 相比的优势
| 方案 | 定位 | 差异 |
|---|---|---|
| prometheus-cardinality-troubleshooter（本技能） | 实时诊断“正在发生”的基数事故：查询变慢、OOM、账单暴涨，给出安全的应急处置路径 | 强调“先止血再修复”且明确划出唯一安全的应急手段，核心流程零外部依赖 |
| prometheus-label-strategy（同合集仓库姊妹技能） | 标签体系的事前设计与源头预防审计 | 是在问题发生前介入的规划工具，而非事故发生时的排障工具，两者可互补使用 |
原生 promtool tsdb analyze 命令 |
Prometheus 自带 CLI 工具，输出标签基数与 churn 排行原始数据 | 只给数字，不给症状归因、不给安全的应急处置建议，需工程师自行判断下一步 |
Grafana Mimir mimirtool analyze 系列命令 |
基于仪表盘与告警规则判断指标是否被实际使用 | 解决的是“这个指标能否下线”的用量清理问题，不涉及基数事故的实时诊断 |
8. 用户评价
该技能目前在第三方平台尚无具名用户评价；第三方技能目录页面显示了一个笼统的安装量估计，但该数字与合集仓库整体规模高度接近，暂不作为该技能自身热度的独立证据。
9. 其他补充
所属 grafana/skills 仓库工程实践成熟：配备“Validate Marketplace”（清单校验）与“Lint Skills”（代码检查）两条 CI 工作流、Renovate 自动依赖更新机器人、按插件分组的 CODEOWNERS。仓库同时收录 Loki、Tempo、Mimir、Pyroscope、k6 等 LGTM 可观测性全家桶其他组件的同类技能，供后续按需组合安装。
10. 安装使用方式
Claude Code：
claude plugin marketplace add grafana/skills
claude plugin install grafana-cloud@grafana-skills注意：该命令会安装 grafana-cloud 插件组下全部技能（共 18 个），非仅 prometheus-cardinality-troubleshooter 一个。
Codex 及其他遵循 Agent Skills 标准的工具： 自动发现仓库根目录 .agents-plugin/marketplace.json 清单，无需手动配置；也可用统一命令单独拉取：
npx skills add grafana/skillsCursor： 同样使用 npx skills add grafana/skills，技能会写入项目 .cursor/skills/ 目录供其 agent 加载。
安装后无需重启；在对话中描述“我的 Prometheus 查询变慢了/内存在涨/账单突然变高”即可触发；若是“设计阶段”的标签体系规划需求，技能会建议改用 prometheus-label-strategy。
11. 注意事项
- 无法只安装该单个技能——通过 Claude Code 插件市场安装会连带装入 grafana-cloud 插件组下全部 18 个技能
- 文中提供的 PromQL/curl/YAML 均为参考建议，需用户自行判断并在生产环境应用前于预发环境验证
- OpenClaw / Hermes Agent 的兼容性未见官方声明，跨 agent 使用前建议自行验证