Grafana Mimir ruler 组件深度解析:规则评估模式、结果写路径与联邦规则实践

原创2026-10-14 11:43:491,407 阅读
文章标签:时序数据库后端数据存储可观测性云原生

Grafana Mimir ruler 组件深度解析:规则评估模式、结果写路径与联邦规则实践

Grafana Mimir 的 ruler(规则评估器)是一个可选组件,负责以固定周期评估每个租户定义的 recording rules(记录规则)与 alerting rules(告警规则),并把评估产生的样本写入存储、把触发的告警通知给 Alertmanager。本文将围绕 ruler 组件架构文档 展开,结合 pkg/ruler 目录下的源码实现,系统讲解它的两种(实为三种)评估模式、规则结果写路径、联邦规则组、分片与规则管理方式,帮助读者在单实例、多租户乃至跨数据中心全局部署中正确配置和运维 ruler。

阅读完本文,你将能够:区分并配置 ruler 的 internal / remote / remote-over-HTTP 评估模式;理解并调优规则结果写路径(内部 distributor 与远程 gRPC distributor);启用 federated rule groups 实现跨租户聚合;并通过 mimirtool 与 HTTP 配置 API 管理规则。

ruler 在架构中的定位

ruler 是 Mimir 架构中"周期性地把规则算出来"的执行者:

  • 每个租户拥有一组 recording/alerting rules,并可以进一步把这些规则分组到 namespace(命名空间)中;
  • 评估规则会生成新的样本(series)。默认情况下,这些样本被送入内部的 distributor 进行摄取,从而可以被后续查询使用;
  • ruler 也可以被配置为通过 gRPC 将规则结果推送到远程 distributor;
  • 内部 distributor 的配置复用 configuration-parameters 文档中的 distributor 一节 所述参数。

在源码层面,ruler 的核心实现位于 pkg/ruler/ruler.go,其中 Ruler 结构体(ruler.go#L368-L401)聚合了 ring(分片)、rule store(规则存储)、MultiTenantManager(租户级规则管理器)、limits 等子系统;启动时它会先以 JOINING 状态加入哈希环并完成规则的初始同步,随后转为 ACTIVE 状态才开始评估规则(见 ruler.go#L483-L540)。

三种规则评估模式

ruler 的"操作模式"决定的是规则表达式由谁来评估,它并不决定结果样本写到哪里(后者由下一节的写路径配置决定)。

Internal(内部模式,默认)

内部模式下,ruler 在自己的进程内运行一个内置 querier,直接连接 ingesters 与 store-gateways 完成查询,再通过配置好的写路径写出结果。内置 querier 的配置复用 configuration-parameters 文档中的 querier 一节 所列参数。

需要注意的局限:内部模式不使用任何查询加速技术,当规则表达式基数(cardinality)非常高时,单次评估耗时可能超过评估周期,进而导致记录规则出现缺失数据点。

下图展示了内部模式下 ruler 的组件交互:

Grafana Mimir ruler 内部模式架构图

从源码看,内部模式下规则评估使用的 queryable 由 querier 侧的组件就地提供,ruler 通过 RemoteQuerier/内置 querier 两种路径的二选一实现(pkg/ruler/remotequerier.go 中的 DialQueryFrontend 会根据地址前缀决定走 gRPC 还是 HTTP,见下文)。

Remote(远程模式)

远程模式下,ruler 将规则评估委托给 query-frontend,从而获得 query-frontend 的全部查询加速能力,例如 query sharding(查询分片)。启用方式:设置 -ruler.query-frontend.address 命令行参数或对应的 YAML 配置项。

由于 ruler 与 query-frontend 之间通过 gRPC 通信,可以通过给地址加上 dns:/// 前缀启用客户端侧负载均衡。

下图展示了远程模式下 ruler 的组件交互:

Grafana Mimir ruler 远程模式架构图

对应源码在 pkg/ruler/remotequerier.go#L77-L92:QueryFrontendConfig.RegisterFlags 注册了 ruler.query-frontend.address,帮助信息明确说明它可以"是 query-frontend 的 gRPC 监听地址,也可以是 Prometheus 兼容服务器的 HTTP/HTTPS 地址,若要启用 gRPC 客户端侧负载均衡必须以 dns:/// 开头"。此外还有两个可调参数:

  • -ruler.query-frontend.query-result-response-format:从 query-frontend 获取查询结果时使用的格式,可选 json 或 protobuf(默认 protobuf,即代码中的 formatProtobuf);
  • -ruler.query-frontend.max-retries-rate:失败查询每秒最大重试次数,默认 170。

同时 Validate()(remotequerier.go#L94-L106)会校验:若地址以 dns:// 开头但不是 dns:///(三个斜杠),直接报错——这是 gRPC 服务发现的硬性格式要求。

Remote over HTTP/HTTPS

当 -ruler.query-frontend.address 以 http:// 或 https:// 开头时,ruler 会把规则评估委托给一个 Prometheus 兼容的 HTTP 服务器。一个典型使用场景是:通过代理(proxy)把多个 Mimir 实例的数据联邦(federate)到一个端点,再让 ruler 基于该端点评估规则。

源码中 DialQueryFrontend(remotequerier.go#L108-L115)就是这一分派的实现:地址以 http:///https:// 开头时调用 dialQueryFrontendHTTP,否则走 dialQueryFrontendGRPC。HTTP 客户端还有独立的 ruler.query-frontend.http-client-config 配置组(TLS、超时等)。

规则结果写路径(Rule result writes)

关键点:ruler 的操作模式决定"如何评估",但不决定结果样本写到哪里。

  • 默认:通过内部 distributor 写入(复用上面提到的 distributor 配置参数);
  • 远程写:通过原生 gRPC 推送到远程 distributor。设置 -ruler.distributor.address 即可,多数部署只需要设置这一个地址;
    • ruler.distributor.remote_timeout:每次写请求的超时时间;
    • ruler.distributor.grpc_client_config:高级标准 gRPC 客户端调优,包括 TLS、消息大小、压缩、重试和 cluster validation(集群校验)。

对应源码为 pkg/ruler/distributor_client.go 中的 DistributorConfig(distributor_client.go#L39-L48):RegisterFlags 注册的默认超时为 10s,并为该 gRPC 客户端挂载了 s2 自定义压缩器;Validate()(distributor_client.go#L68-L95)还会强制拒绝 HTTP(S) 地址(该地址必须是 gRPC 地址),并校验 dns:/// 三斜杠格式。

拆分、超时、重试与"不可无损切分"语义

源码把"写路径"的细节实现得很细(对应 distributor_client.go#L212-L262):

  • 按序列边界拆分:ruler 会把一次远程写请求沿序列边界拆分,使每个请求都落在 ruler.distributor.grpc_client_config.max_send_msg_size 限制内;
  • 为压缩预留空间:启用压缩时,ruler 会保守地预留压缩框架占用的空间,因此拆分后的实际负载会略低于配置的传输上限。源码中 maxUncompressedPayloadSize 与 compressedPayloadSizeUpperBound(distributor_client.go#L300-L351)专门计算"压缩后必然不超过上限的最大未压缩负载大小",覆盖 gzip、snappy、s2 三种压缩器;
  • 顺序发送、独立超时与重试:拆分出的请求被串行发送,各自拥有独立的超时和重试(pushWithRetries,默认按 gRPC client config 的 backoff 配置执行);当启用了 gRPC 客户端限流时,每个请求消耗独立的限流 token;
  • 无回滚:在先发出的请求已被接受、而后面的请求失败时,已接受部分不会被回滚;
  • 不可无损切分的单序列:ruler 对每个结果序列每次评估只产生一个 float 或 native-histogram 样本(one sample per series per evaluation),因此单条结果序列一旦超过有效拆分上限,就无法被无损切分。此时应调大 ruler.distributor.grpc_client_config.max_send_msg_size,并把 distributor 侧的 server.grpc_server_max_recv_msg_size 配置为不小于该值;若启用了压缩,略超保守上限的序列仍可能在压缩后成功,否则 gRPC 会返回 ResourceExhausted;
  • 可观测性:直方图指标 cortex_ruler_remote_distributor_requests_per_write_request(注册于 distributor_client.go#L122-L127)报告一次 ruler 写请求被拆分成多少个远程请求。

Kubernetes 下的地址选择

在 Kubernetes 部署中:

  • 想要 gRPC 客户端侧负载均衡,应把 ruler.distributor.address 指向 distributor headless service 的 gRPC 端口(配合 dns:/// 前缀);
  • 普通 ClusterIP Service 可以保证连通性,但它不会提供预期的、基于 per-RPC 的跨 distributor 端点客户端侧均衡,因此不推荐。

全局部署推荐组合

全局(跨数据中心)部署的 ruler 应当同时配置远程规则评估与远程 distributor 写。查询目标可以是普通 query-frontend,也可以是专用 ruler-query-frontend,视部署形态而定。文档给出的 YAML 示例:

ruler:
  query_frontend:
    address: dns:///<query-frontend-or-ruler-query-frontend-headless>.<namespace>.svc.cluster.local:9095
  distributor:
    address: dns:///<distributor-headless>.<namespace>.svc.cluster.local:9095
    remote_timeout: 10s

Recording rules(记录规则)

ruler 按固定周期评估 Prometheus recording rules)。记录规则的产物(如 job:http_inprogress_requests:sum)随后可供常规查询使用。

Alerting rules(告警规则)与 Alertmanager 通知

ruler 同样按周期评估 alerting rules:

  • 若表达式结果中包含任何序列,则告警进入 PENDING(pending)状态;
  • 若告警定义了 for 时长,则在状态持续满整个 for 之后进入 FIRING(firing)状态;
  • ruler 随后把处于 FIRING 状态的告警通知给 Alertmanager。

配置 Alertmanager 地址使用 -ruler.alertmanager-url 参数,它支持 DNS service discovery 格式,详见 Supported discovery modes。

如果使用 Mimir 自带的 Alertmanager,应把地址指向 Alertmanager 的 API。Alertmanager 的 API 前缀通过 -http.alertmanager-http-prefix 配置,默认是 /alertmanager。例如,Alertmanager 监听于 http://mimir-alertmanager.namespace.svc.cluster.local 且使用默认前缀时,应设置:

-ruler.alertmanager-url=http://mimir-alertmanager.namespace.svc.cluster.local/alertmanager

从源码看,通知链路由 pkg/ruler/notifier.go 中的 rulerNotifier 实现:它内部封装了 Prometheus 的 notifier.Manager 与一个 discovery.Manager(notifier.go#L34-L59),buildNotifierConfig 会把逗号分隔的 Alertmanager URL 解析成带服务发现的 Prometheus 配置。与此相关的调优参数还包括 -ruler.alertmanager-refresh-interval(DNS 解析刷新间隔,默认 1 分钟)、-ruler.notification-queue-capacity(通知队列容量,默认 10000)、-ruler.max-notification-batch-size 与 -ruler.notification-timeout(默认 10s)等,均注册于 ruler.go#L226-L229。

Federated rule groups(联邦规则组)

联邦规则组是指带有非空 source_tenants 字段的规则组:

  • source_tenants 允许在评估一个规则组时跨多个租户聚合数据:组内每条规则的表达式都会针对 source_tenants 中所有租户的数据进行评估;
  • 如果 source_tenants 为空或被省略,则创建该组的租户本身即被视为 source_tenant。

示例:

name: MyGroupName
source_tenants: ["tenant-a", "tenant-b"]
rules:
  - record: sum:metric
    expr: sum(metric)

在上例中,MyGroupName 的规则将针对 tenant-a 与 tenant-b 两个租户的数据进行评估。

启用与前置依赖

联邦规则组默认在评估时被跳过,该特性依赖跨租户查询联邦(cross-tenant query federation)能力。启用方式为同时设置:

-ruler.tenant-federation.enabled=true
-tenant-federation.enabled=true

(或对应的 YAML 配置项)。对应源码是 pkg/ruler/tenant_federation.go:TenantFederationConfig 注册 ruler.tenant-federation.enabled 参数(默认 false);removeFederatedRuleGroups(tenant_federation.go#L61-L81)在特性关闭时会跳过所有带 source_tenants 的规则组并打印告警日志;TenantFederationQueryFunc 则会在评估时把多租户 ID 注入到上下文中(user.InjectOrgID),交给联邦查询器执行。

限额语义与"无部分结果"保证

  • 评估时,应用于单租户的查询限额也会被应用到规则组内的每个查询。例如 tenant-a 有一个 source_tenants: [tenant-b, tenant-c] 的联邦规则组,则 tenant-b 与 tenant-c 的查询限额都会被应用;
  • 只要其中任意一个限额被超出,整个评估就会失败,不会保存任何部分结果;
  • 同样的"无部分结果"保证也适用于其他原因导致的查询失败(例如 ingester 不可用)。

数据语义与租户边界提醒

联邦规则评估期间产生的时间序列会带有 __tenant_id__ 标签,这与跨租户查询联邦返回的序列行为一致。

⚠️ 需要注意:联邦规则组允许把多个源租户的数据写入单个目标租户,这会削弱租户间的数据隔离。例如 tenant-a 有一个对 tenant-b 数据执行 sum(metric_b) 的联邦规则组,并把结果以指标 sum:metric_b 写回 tenant-a 的存储,那么 tenant-a 中从此就包含了部分 tenant-b 的数据。因此在配置 Mimir 前面的访问控制层、以及决定是否启用 -ruler.tenant-federation.enabled 时,务必把这一点纳入考量。

Sharding(分片):水平扩展与哈希环

ruler 支持多租户与水平扩展。为实现水平扩展,ruler 按规则组(rule group)为粒度进行分片:所有 ruler 副本各自构成一个 hash ring(哈希环),环存储在 KV store 中,用于在副本之间划分规则组的执行职责。

配置 ruler 哈希环的方法见 configure-hash-rings。

源码证据:

  • 环配置 RingConfig 位于 pkg/ruler/ruler_ring.go,默认每个 ruler 128 个 token(-ruler.ring.num-tokens)、-ruler.ring.auto-forget-unhealthy-periods 默认 2 个超时周期自动剔除不健康实例;
  • 分片运算在 ruler.go#L553-L582:tokenForGroup 以 User + "/" + Namespace + "/" + Name 计算 FNV-32a 哈希作为环位置,instanceOwnsRuleGroup 再根据环副本集判断当前实例是否拥有该规则组;
  • 环的复制因子被强制设为 1(ruler_ring.go#L79-L87),即每个规则组恰好被一个 ruler 加载执行;只有 ACTIVE 状态的 ruler 参与规则评估(RuleEvalRingOp),而 JOINING/ACTIVE 状态都可参与规则同步(RuleSyncRingOp)。

如何管理告警与记录规则

管理规则有多种方式,可以按场景选用。

方式一:mimirtool CLI 工具

mimirtool rules 命令提供 lint、格式化、上传规则等子命令,详见 mimirtool 文档的 rules 一节。它既支持与本地 Prometheus 规则文件交互,也支持与 Mimir ruler 的 API 交互,例如:

# 列出当前 Mimir 实例中的所有规则组
mimirtool rules list

(mimirtool rules 的完整子命令包括 list、get、load、delete、lint、format、prepare 等,均以 mimirtool rules <subcommand> --help 查看。)

方式二:mimir-rules-action GitHub Action

GitHub Action mimir-rules-action 封装了 mimirtool rules 的部分功能,用于在 CI 中校验并同步规则,详见 operations/mimir-rules-action 目录 下的 README 与 action.yaml。

方式三:HTTP 配置 API

ruler HTTP 配置 API 允许租户创建、更新、删除规则组,完整的端点列表与示例请求见 HTTP API 参考的 ruler 一节。常用端点速览:

操作 端点
列出租户全部规则组 GET <prometheus-http-prefix>/config/v1/rules
按命名空间获取规则组 GET <prometheus-http-prefix>/config/v1/rules/{namespace}
获取单个规则组 GET <prometheus-http-prefix>/config/v1/rules/{namespace}/{groupName}
创建/更新规则组 POST <prometheus-http-prefix>/config/v1/rules/{namespace}(Content-Type: application/yaml,成功返回 202)
删除规则组 DELETE <prometheus-http-prefix>/config/v1/rules/{namespace}/{groupName}
删除整个命名空间 DELETE <prometheus-http-prefix>/config/v1/rules/{namespace}
删除租户全部配置 POST /ruler/delete_tenant_config(内部端点,不面向终端用户)

这些端点大多可以用 -ruler.enable-api(默认 true,见 ruler.go#L232)关闭;用 curl 提交请求体时建议使用 --data-binary 以保留换行。API 使用 "namespace" 概念对应 Prometheus 规则文件的名字,同一 namespace 内规则组名称必须唯一。

规则状态存储(State)

ruler 使用 -ruler-storage.backend 指定的后端来存储规则配置(注意区分:这里是规则文件的存储,不是查询数据的存储)。支持的 backend:

后端 配置值
Amazon S3 -ruler-storage.backend=s3
Google Cloud Storage -ruler-storage.backend=gcs
Microsoft Azure Storage -ruler-storage.backend=azure
OpenStack Swift -ruler-storage.backend=swift
本地存储 -ruler-storage.backend=local

源码中 NewRuleStore(pkg/ruler/storage.go#L27-L53)根据 backend 分派:local 走 pkg/ruler/rulestore/local/local.go 的 NewLocalRulesClient,其余 backend 统一通过 bucket.NewClient 构建对象存储客户端,并可叠加 memcached 缓存(-ruler-storage.cache.backend=memcached 及 -ruler-storage.cache.memcached.* 参数,见 pkg/ruler/rulestore/config.go#L37-L46);缓存会覆盖规则组列举(iter)与规则组内容读取(rule-group)两类操作(storage.go#L55-L82)。注意 filesystem 后端仅用于开发测试。

本地存储(Local storage)

local 后端从本地文件系统读取 Prometheus recording rules 格式的规则文件。

⚠️ local 是只读后端,不支持通过上文 HTTP 配置 API 创建或删除规则。

当所有 ruler 拥有相同的规则文件时,local 存储同样支持 ruler 分片。在 Kubernetes 中,可以通过把 Kubernetes ConfigMap 挂载到每个 ruler Pod 来保证文件一致。

配置示例:

-ruler-storage.backend=local
-ruler-storage.local.directory=/tmp/rules

ruler 会在 /tmp/rules/<TENANT ID> 目录下查找对应租户的规则文件(目录结构即 目录 / 租户ID / 命名空间,见 local.go#L26-L32),并要求规则文件必须使用 Prometheus 格式。

常用配置速查

将上文关键参数汇总如下(全部参数可在 configuration-parameters 中查阅):

配置项 作用 默认值
-ruler.evaluation-interval 规则评估周期 1m
-ruler.poll-interval 从对象存储重新同步规则组的周期 10m
-ruler.query-frontend.address 远程评估地址(gRPC 或 HTTP/HTTPS) 空(内部模式)
-ruler.distributor.address 远程写 distributor 的 gRPC 地址 空(内部写)
-ruler.distributor.remote-timeout 远程写请求超时 10s
-ruler.alertmanager-url Alertmanager 地址(支持 DNS SD) 空
-ruler.tenant-federation.enabled 启用联邦规则组 false
-ruler-storage.backend 规则存储后端(s3/gcs/azure/swift/local) 无
-ruler.ring.num-tokens 每个 ruler 的环 token 数 128
-ruler.enable-api 启用规则配置 API true

总结

Grafana Mimir 的 ruler 是一个设计精巧的可选组件:评估模式(internal/remote/remote-over-HTTP)决定"谁来算",写路径配置(内部或远程 distributor)决定"结果写去哪",两者相互独立;分片基于哈希环按规则组粒度执行,每个规则组恰好归属一个 ACTIVE ruler;联邦规则组则在启用跨租户查询联邦后,允许规则直接聚合多个租户的数据,同时遵守"任一限额超限即整体失败、不保存部分结果"的严格语义。理解这些边界,是运维好一套多租户、可水平扩展的 Mimir 规则链路的关键。

登录后查看全文
mimir