Cortex集群中Prometheus自定义记录规则未创建的排查求助

问题背景 #

我们在Cortex集群中配置了自定义Prometheus记录规则，相关源数据已存在数月。除最后一条规则job:database_default:rate5m_prediction外，其余规则生成的指标均能在Prometheus/Grafana中正常检索。将该规则的expr复制为查询语句在Grafana中执行可得到正常结果，但日志中未发现任何相关报错（其余规则也无日志记录），怀疑规则存在未被捕获的错误，需要定位问题原因。

已尝试的排查动作 #

• 将规则的expr改为单行（怀疑YAML的|块处理存在格式问题）
• 将记录规则重命名为与其他规则格式一致的job:database_default:rate5m:prediction
  以上操作均未解决问题。

配置的记录规则 #

- record: job:database_default:rate5m
  expr: sum without(container, endpoint, namespace, pod, prometheus, prometheus_replica, service) (rate(database_default{_account="ah",_source="cluster"}[5m]))

  # Long-term average value for the series
- record: job:database_default:rate5m:avg_over_time_1w
  expr: avg_over_time(job:database_default:rate5m[1w])

  # Long-term standard deviation for the series
- record: job:database_default:rate5m:stddev_over_time_1w
  expr: stddev_over_time(job:database_default:rate5m[1w])

- record: job:database_default:rate5m_prediction
  expr: |
   quantile(0.5,
     label_replace(
       avg_over_time(job:database_default:rate5m[4h] offset 166h)
       + job:database_default:rate5m:avg_over_time_1w - job:database_default:rate5m:avg_over_time_1w offset 1w
       , "offset", "1w", "", "")
     or
     label_replace(
       avg_over_time(job:database_default:rate5m[4h] offset 334h)
       + job:database_default:rate5m:avg_over_time_1w - job:database_default:rate5m:avg_over_time_1w offset 2w
       , "offset", "2w", "", "")
     or
     label_replace(
       avg_over_time(job:database_default:rate5m[4h] offset 502h)
       + job:database_default:rate5m:avg_over_time_1w - job:database_default:rate5m:avg_over_time_1w offset 3w
       , "offset", "3w", "", "")
   )
   without (offset)

进一步排查方法 #

1. 检查标签冲突或维度异常
   记录规则生成的指标若存在重复标签键值对，或包含Cortex不允许的标签字符，可能被静默丢弃。在Grafana中执行规则expr后，查看结果的标签是否有重复，或是否存在特殊字符。

2. 验证规则执行周期与数据时间范围匹配
   检查Cortex记录规则的评估周期（默认1分钟），若规则中offset或时间范围超出Cortex存储的保留期，可能导致规则执行时无数据输出。可临时缩短offset值（如改为10h）测试是否能生成指标。

3. 开启Ruler组件Debug日志
   默认日志级别可能无法捕获细节，将Cortex Ruler组件的日志级别调整为debug，重启后观察规则加载、评估阶段的日志，重点关注规则解析、标签处理、查询执行的细节。

4. 通过Ruler API检查规则加载状态
   调用Cortex的Ruler API（如GET /api/v1/rules）查看已加载的规则列表，确认目标规则是否被成功加载。若未出现在列表中，说明YAML配置存在语法问题（如缩进错误、注释位置不当），可用YAML校验工具检查配置文件。

5. 逐步简化规则表达式
   先保留规则的核心子表达式（如第一个label_replace块，去掉quantile和without），测试是否能生成指标。若简化后正常，再逐步添加其他部分，定位到具体导致失败的子表达式。

6. 检查Cortex规则配额限制
   确认Cortex是否配置了记录规则数量或指标系列数的配额，若目标规则生成的系列数超出限制，会被静默丢弃。可查看Cortex配置中ruler相关的配额参数，或通过监控指标cortex_ruler_rules_loaded查看规则加载情况。

内容的提问来源于stack exchange，提问作者Glen Solsberry