需要生成或编写 PromQL 查询、告警规则…

适用于把监控需求转化为 PromQL 查询，覆盖仪表盘、告警、记录规则、SLO/燃烧率与临时分析。

适用场景

解决思路

1. 先理解监控目标：向用户询问要监控或测量什么，包括请求速率、错误率、延迟/时长、资源使用、可用性、队列深度、饱和度、吞吐量或自定义业务指标。
2. 明确用例：确认查询用于仪表盘可视化、告警规则、临时排障分析、Recording Rule、容量规划还是 SLO 跟踪。
3. 收集上下文：获取服务/应用名、团队或项目、优先级、已有指标或命名约定。
4. 用 AskUserQuestion 收集信息；如果用户初始请求已明确目标、用例和上下文，则在回复中确认这些细节而不重复询问；只对缺失或模糊信息提问。
5. 做指标发现：询问可用指标名；不确定时建议常见命名模式；按后缀判断类型：`_total` 为 Counter，`_bucket`/`_sum`/`_count` 为 Histogram，无后缀可能是 Gauge，`_created` 为 Counter 创建时间戳。
6. 确认指标类型并匹配函数：Counter 累积且只增或重置，使用 `rate()`、`irate()`、`increase()`；Gauge 可升可降，直接使用或 `avg_over_time()`、`min_over_time()`、`max_over_time()`；Histogram 是桶累积计数，使用 `histogram_quantile()`、`rate()`；Summary 是预计算分位数，用 `_sum` 和 `_count` 算平均值，不要平均分位数。
7. 发现标签：确认 `job`、`instance`、`environment`、`service`、`endpoint`、`status_code`、`method` 等标签，以及哪些标签用于过滤或分组；用 AskUserQuestion 确认指标名、类型和可用标签。
8. 确定时间范围：区分瞬时值、速率窗口如 `[5m]`、`[1h]`、`[1d]`；实时速率通常用 `[1m]` 到 `[5m]`，趋势用 `[1h]` 到 `[1d]`；速率范围至少是 scrape interval 的 4 倍。
9. 确定标签过滤：支持精确匹配 `job='api-server'`、否定匹配 `status_code!='200'`、正则匹配 `instance=~'prod-.*'`、多条件 `{job='api', environment='production'}`。
10. 确定聚合：可选择不聚合、按标签聚合 `sum by (job, endpoint)` 或 `avg by (instance)`、移除标签聚合 `sum without (instance, pod)` 或 `avg without (job)`；常用聚合有 `sum`、`avg`、`max`、`min`、`count`、`topk`、`bottomk`。
11. 确定阈值或条件：告警阈值如错误率大于 5%；过滤只显示高于或低于某值的序列；用 `offset` 对比历史数据。
12. 用户已提供参数时先确认：在回复中显式确认已给值；在 AskUserQuestion 中把它们作为预填默认项，第一项为“使用指定值”；例如用户说 P95 latency 超过 500ms 时，确认阈值为 500ms 或允许指定不同值。
13. 生成代码前呈现纯文字查询计划：写明目标、查询结构（起始指标、标签过滤、函数、聚合、附加操作）、预期输出（数据类型、结果标签、值含义、典型范围）、示例解释、是否匹配意图。
14. 用 AskUserQuestion 确认计划，选项为“是，生成此查询”“修改某方面”“展示替代方案”；若选修改，只追问一个聚焦问题（metric、labels、function、time range、threshold、output shape），更新计划后再生成；若选替代，提供至少两个有效查询计划及权衡（准确性、成本、基数、可读性），让用户选择后再生成。
15. 生成前先识别查询类别：histogram、RED、USE、function-specific、optimization 等。
16. 只读取相关 reference：直方图读 `references/metric_types.md` 的 Histogram 部分；错误/延迟模式读 `references/promql_patterns.md` 的 RED 部分；资源监控读 `references/promql_patterns.md` 的 USE 部分；优化问题读 `references/best_practices.md`；特定函数读 `references/promql_functions.md`；仅当需求变化或当前线程未查过时重读。
17. 如果所需 reference 无法读取，说明问题，并使用已有最适用文档化模式继续尽力生成。
18. 在回复中引用适用模式或最佳实践，如 `references/promql_patterns.md` Pattern 3: Latency Percentile，并给出 `histogram_quantile(0.95, sum by (le) (rate(...)))`；生成类似查询时引用示例文件，如 `examples/red_method.promql` lines 64-82。
19. 生成查询时始终使用标签过滤以减少基数，例如 `rate(http_requests_total{job='api-server', environment='prod'}[5m])`，避免 `rate(http_requests_total[5m])`。
20. 按指标类型使用函数：Counter 用 `rate()`/`increase()`；Gauge 直接或 `avg_over_time()`；Histogram 用 `histogram_quantile(0.95, sum by (le) (rate(http_request_duration_seconds_bucket[5m])))`。
21. 用 `by()` 或 `without()` 应用聚合：`sum by (job, endpoint) (rate(http_requests_total[5m]))`、`sum without (instance, pod) (rate(http_requests_total[5m]))`。
22. 尽量用精确匹配而非正则：`http_requests_total{status_code='200'}` 优于 `http_requests_total{status_code=~'200'}`。
23. 正确计算比率：错误率用 `sum(rate(http_requests_total{status_code=~'5..'}[5m])) / sum(rate(http_requests_total[5m]))`。
24. 对频繁使用或计算昂贵的查询使用 Recording Rules 预聚合；命名遵循 `level:metric:operations`。
25. 复杂查询用多行格式化提升可读性，例如 `histogram_quantile(0.95,` 换行 `sum by (le, job) (` 等。
26. 使用常见查询模式：请求速率、错误率（0-1 比率和 0-100 百分比）、延迟百分位（histogram）、资源使用、可用性 `(count(up{job='api-server'} == 1) / count(up{job='api-server'})) * 100`、饱和度/队列深度 `avg_over_time`/`max_over_time`。
27. 生成后始终尝试用 `devops-skills:promql-validator` 校验：检查语法、语义逻辑（指标类型对应函数）、反模式与低效、优化建议、解释查询、验证是否符合用户意图。
28. 校验清单：括号平衡、操作符合法；指标类型与函数匹配；标签过滤足够具体；聚合合适；时间范围合理；无已知反模式；查询性能优化；失败则修复并重新校验直到通过。
29. 若 validator 不可用、失败或两轮修复/校验后仍无法完成：简要报告失败原因（工具不可用、超时、解析错误等）；执行手工回退检查（语法形态、指标/函数兼容、标签过滤、聚合、时间范围合理性）；将未检查区域标记为 **UNVERIFIED**，询问用户是否继续尽力输出或提供更多上下文再校验。
30. 向用户展示结构化校验结果：语法检查状态 VALID/WARNING/ERROR/UNVERIFIED 与问题；最佳实践检查状态 OPTIMIZED/CAN BE IMPROVED/HAS ISSUES/UNVERIFIED、问题与建议；校验覆盖（validator 是否成功/失败/不可用、已完成检查、跳过检查）；查询解释（测量什么、输出标签、预期结果结构）。
31. 生成和校验后提供使用说明：最终查询、查询解释（测量什么、如何解读、预期值范围、输出标签）、如何使用（Grafana/Prometheus UI 面板、Alertmanager 规则、Prometheus recording rule 配置、Prometheus expression browser）、自定义说明（时间范围、环境标签、阈值、替代函数）、相关查询建议（互补查询、recording rule 机会、dashboard 面板）。
32. 处理 native histograms（Prometheus 3.x+）：使用稳定特性；通过 `scrape_native_histograms` 配置显式启用抓取；v3.9 起不需 feature flag 但仍需显式设置；查询用简化语法，无 `_bucket` 后缀和 `le` 标签，如 `histogram_quantile(0.95, sum by (job) (rate(http_request_duration_seconds[5m])))`；函数用 `histogram_count()`、`histogram_sum()`、`histogram_fraction()`；用 `histogram_sum(...)/histogram_count(...)` 算平均。
33. 检测 native 与 classic histogram：native 无 `_bucket` 后缀、无 `le` 标签、直接存储 histogram 数据；配置样例为 prometheus.yml 中 `scrape_configs` 的 `scrape_native_histogram: true`。
34. 处理 NHCB（Prometheus 3.4+）：用 `convert_classic_histograms_to_nhcb: true` 将 classic histogram 在 scrape 时转换为 native histogram，保持现有 instrumentation；查询同 native histograms；`histogram_fraction` 也可用；schema -53 表示自定义桶边界，不同自定义桶边界通常不可互相合并。
35. 实现 SLO/错误预算：错误预算剩余用 `1 - (sum(rate(http_requests_total{job='api', status_code=~'5..'}[30d])) / sum(rate(http_requests_total{job='api'}[30d]))) / 0.001`；简化可用性用成功请求数除以总请求数。
36. 计算燃烧率：燃烧率 = 当前错误率 / 允许错误率；例如 1 小时窗口、99.9% SLO 用 `(sum(rate(http_requests_total{job='api', status_code=~'5..'}[1h])) / sum(rate(http_requests_total{job='api'}[1h]))) / 0.001`；燃烧率大于 1 表示超速消耗，14.4 表示 1 小时消耗月度预算 2%。
37. 实现多窗口多燃烧率告警（Google SRE 标准）：页面级告警用 1h 长窗口和 5m 短窗口同时超过 `14.4 * 0.001`；工单级告警用 6h 和 30m 同时超过 `6 * 0.001`；用 `and` 组合两个条件。
38. 配置 SLO Recording Rules：按 job 预计算不同窗口错误率，如 `job:slo_errors_per_request:ratio_rate1h`、`job:slo_errors_per_request:ratio_rate5m`、`job:slo_availability:ratio_rate1h`，interval 设为 30s。
39. 实现延迟 SLO：计算快于目标百分比用 `(sum(rate(http_request_duration_seconds_bucket{le='0.2', job='api'}[5m])) / sum(rate(http_request_duration_seconds_count{job='api'}[5m]))) * 100`；违反延迟 SLO 用 `(sum(rate(http_request_duration_seconds_count{job='api'}[5m])) - sum(rate(http_request_duration_seconds_bucket{le='0.5', job='api'}[5m]))) / sum(rate(http_request_duration_seconds_count{job='api'}[5m]))`。
40. 参考燃烧率表：1 为 None，2 为 Low，6 为 Ticket，14.4 为 Page，36 为 Page urgent；据此设置告警严重级别。
41. 使用高级技术：子查询 `max_over_time(rate(http_requests_total[5m])[30m:1m])`，语法 `<query>[<range>:<resolution>]`；`offset` 对比历史如 `rate(http_requests_total[5m]) - rate(http_requests_total[5m] offset 1w)`；`@` 修饰符如 `rate(http_requests_total[5m] @ end())` 或 `@ 1609459200`。
42. 使用二元运算符和向量匹配：一对一匹配 `metric_a + metric_b`；多对一用 `rate(http_requests_total[5m]) * on (job, instance) group_left (version) app_version_info`；忽略标签用 `metric_a + ignoring(instance) metric_b`；逻辑运算符用 `http_requests_total > 100`、`and`、`unless`。
43. 做文档查找：优先 context7 MCP，用 `mcp__context7__resolve-library-id` 查询 'prometheus'，再用 `mcp__context7__get-library-docs`，参数 `context7CompatibleLibraryID: /prometheus/docs`、`topic`、`page: 1`，需要时取更多页；回退 WebSearch，查询模式为 'Prometheus PromQL [function/operator/feature] documentation [version] examples'。
44. 落地 RED 方法：Rate 用 `sum(rate(http_requests_total{job='api'}[5m])) by (endpoint)`；Errors 用错误率公式；Duration 用 `histogram_quantile(0.95, sum by (le) (rate(http_request_duration_seconds_bucket{job='api'}[5m])))`。
45. 落地 USE 方法：Utilization 用 `(avg(rate(node_cpu_seconds_total{mode!='idle'}[5m])) / count(node_cpu_seconds_total{mode='idle'})) * 100`；Saturation 用 `avg_over_time(node_load1[5m])`；Errors 用 `rate(node_network_receive_errs_total[5m])`。
46. 生成告警查询：包含显式阈值，如错误率大于 0.05；用布尔运算符返回 1 或 0；考虑 `for` 子句，如 `for: 10m`。
47. 生成 Recording Rules：命名遵循 `level:metric:operations`，如 `job:http_requests:rate5m`；预聚合昂贵查询，如 `job_endpoint:http_request_duration_seconds:p95`；在仪表盘使用预记录指标代替昂贵查询。
48. 处理常见错误：空结果时检查 `up{job='your-job'}`、标签过滤、时间范围、抓取状态；序列过多时加具体标签过滤、聚合、Recording Rules、检查动态标签爆炸；值不正确时检查 metric 类型、函数用法（counter 用 rate，不把 rate 用在 gauge）、时间范围、counter resets；性能问题时缩短 range、加标签过滤、用 Recording Rules、避免昂贵正则、考虑查询超时。
49. 遵循沟通指南：生成前解释计划；用 AskUserQuestion 收集需求；最终前确认意图；解释函数或模式原因；提供结果解读上下文；建议优化或替代方案；主动校验并修复；询问是否需要调整。
50. AskUserQuestion 不可用时回退：用一段紧凑纯文本问卷询问 goal、metric names/types、labels、time range、aggregation、use case；若用户部分回答，使用保守默认值并明确标记假设；若核心输入仍模糊，提供 2-3 个具体查询计划选项让用户选择；不要无限阻塞，生成带假设说明的尽力查询。
51. 确定是否读 reference：直方图或摘要分位数、连接/向量匹配/子查询/offset/Recording/Alerting Rules、SLO/燃烧率/错误预算、优化/基数、指标类型未知或争议时读取 references。
52. 仅在单指标、单函数（`rate`、`increase`、`sum`、`avg`、`max`、`min`）、无连接/记录/告警规则/高级函数、且用户明确提供指标类型和标签时跳过 references；跳过时明确说 `Reference read skipped (trivial case)`，但校验仍必须执行。
53. 集成 validator 步骤：生成 PromQL；调用 `devops-skills:promql-validator` 并传入生成的查询；查看校验结果（语法、语义、性能）；修复问题；重新校验直到通过；提供最终已校验查询与使用说明；询问是否需要进一步细化。
54. 按用途读取资源文件：`references/promql_functions.md` 用于具体函数需求或用户询问函数行为；`references/promql_patterns.md` 用于标准监控模式如错误率、延迟、资源使用；`references/best_practices.md` 用于优化、反模式、基数管理；`references/metric_types.md` 用于澄清指标类型和适用函数；示例文件 `examples/common_queries.promql`、`red_method.promql`、`use_method.promql`、`alerting_rules.yaml`、`recording_rules.yaml`、`slo_patterns.promql`、`kubernetes_patterns.promql` 可用于复制定制。
55. 遵守重要注意事项：始终交互式规划，未确认计划不生成；用 AskUserQuestion 收集和确认；始终调用 validator；教育用户；按用例调整；考虑性能；遵循指标类型；复杂查询多行格式化。
56. 按成功标准检查：记录 goal/use-case/metric/time-range/aggregation；计划确认或明确记录假设；记录 reference 决策（consulted 文件名或 skipped trivial 原因）；查询有效性（validator 或手工回退通过）；语义合理性（函数匹配 metric 类型）；基数防护（显式过滤或聚合理由）；交付最终查询、解释和下一步自定义指导。
57. 牢记目标：协作规划并生成精确匹配用户意图的 PromQL；始终优先清晰、正确、性能；交互规划阶段最重要，不要跳过。

适用边界 · 注意事项

• 当目标不是 PromQL/Prometheus 生态，或不需要查询监控指标时，不要使用本技能。
• 用户未提供任何指标名、类型或标签且无法发现时，不要凭空捏造具体指标或标签；应询问、使用保守默认值并明确标记假设。
• validator 不可用且无法完成手工验证时，不要声称查询已生产级验证；应标记 UNVERIFIED 并告知用户。