Loki Alerting 与 Recording Rules 完整指南基于 Ruler 的日志告警体系构建【免费下载链接】lokiLike Prometheus, but for logs.项目地址: https://gitcode.com/GitHub_Trending/lok/lokiLoki 内置的Ruler组件能够持续评估一组可配置的 LogQL 查询并根据结果触发告警或产出指标从而把日志与指标/告警两大可观测性支柱打通。本文以 Loki 官方告警文档为主体结合仓库内 ruler 相关源码pkg/ruler与 CLI 工具实现系统讲解 alerting rules告警规则与 recording rules录制规则的定义、配置、存储、横向扩展sharding、远程写入remote-write与远程评估remote evaluation等实战要点。读完本文你将能够独立编写、管理并规模化部署基于日志的告警与录制规则。从两条规则类型说起Grafana 告警与 Loki 托管规则在 Grafana 生态中存在两类告警规则Grafana 托管告警Grafana-managed alerts这是 Grafana Alerting 中推荐使用的告警类型可查询多种后端数据源单条规则甚至可跨多个数据源支持表达式转换、复杂告警条件、通知内嵌图片以及 error/no data 状态处理等高级能力。数据源托管告警Data-source-managed alerts仅能查询 Prometheus 系数据源如 Mimir、Loki、Prometheus规则本身存储在数据源内部。本文聚焦于第二种类型中 Loki 的部分Loki 托管规则Loki managed rules它又分为两种告警规则Alerting rules由一条或多条查询与表达式构成用于选定要测量的数据并包含一个condition条件——即规则触发告警所需达到或超过的阈值。录制规则Recording rules与告警规则类似周期性评估但它会把频繁使用或计算昂贵的查询结果预计算为一条新的时序指标。驱动这两种规则的核心组件是Ruler它负责持续评估一组可配置的查询并根据结果执行相应动作。一个从本地磁盘加载规则的最简 Ruler 配置如下来自官方文档ruler: storage: type: local local: directory: /tmp/rules rule_path: /tmp/scratch alertmanager_url: http://localhost ring: kvstore: store: inmemory enable_api: true其中storage.type: local表示从本地文件系统读取规则文件alertmanager_url指定告警通知的 Alertmanager 端点enable_api: true开启 Ruler 管理 APIring.kvstore配置 Ruler 自身用于横向分片的哈希环下文详解。为什么要用日志做告警三个典型使用场景Ruler 对 Prometheus 规则的兼容性进一步放大了指标 日志融合的价值。官方文档给出了三个极具代表性的场景黑盒监控Black box monitoring我们并不总能控制所运行应用的源码。负载均衡器以及大量开源或闭源的第三方组件并不暴露我们想要的指标有些甚至完全不暴露任何指标。借助 Loki 告警与录制规则可以从日志中产出指标并对系统状态发出告警从而把这类组件纳入可观测性体系——这是把高级可观测能力引入遗留架构的一种非常强大的方式。事件告警Event alerting有时你只想知道是否发生过任何一次某类事件。基于日志的告警非常适合这类场景例如发现泄漏的认证凭据- name: credentials_leak rules: - alert: http-credentials-leaked annotations: message: {{ $labels.job }} is leaking http basic auth credentials. expr: sum by (cluster, job, pod) (count_over_time({namespaceprod} |~ http(s?)://(\\w):(\\w) [5m]) 0) for: 10m labels: severity: critical这条规则用 LogQL 的正则过滤器|~ http(s?)://(\\w):(\\w)在namespaceprod的日志流中匹配疑似泄漏的 Basic Auth 凭据一旦最近 5 分钟内命中次数大于 0且持续for: 10m即触发http-credentials-leaked告警并带上severity: critical标签。高基数源告警Alerting on high-cardinality sources日志非常适合告警高基数数据源——即潜在标签集巨大、难以或昂贵地作为指标记录的事物。一个典型例子是多租户系统如 Loki 本身中的按租户告警为每个租户建立指标是一种常见的权衡但会引发基数爆炸给现有 Prometheus 指标追加一个tenant标签基数会随租户数量成倍增长。而用 LogQL 创建这类告警之所以有吸引力是因为这些指标可以在**查询时at query time**才被提取出来从而避免指标存储中的基数爆炸。官方文档还给出了一个用 LogQL 让 Loki 监控它自己的例子当特定租户的查询耗时超过 10 秒时发出告警查询如下sum by (org_id) (rate({jobloki-prod/query-frontend} | metrics.go | logfmt | duration 10s [1m]))告警规则Alerting RulesLoki 支持Prometheus 兼容的告警规则。按 Prometheus 官方文档的定义告警规则允许你基于 Prometheus 表达式语言定义告警条件并把触发中的告警通知发送给外部服务。Loki 的告警规则与之完全相同唯一区别是表达式使用LogQL而非 PromQL。完整告警规则文件示例groups: - name: should_fire rules: - alert: HighPercentageError expr: | sum(rate({appfoo, envproduction} | error [5m])) by (job) / sum(rate({appfoo, envproduction}[5m])) by (job) 0.05 for: 10m labels: severity: page annotations: summary: High request latency - name: credentials_leak rules: - alert: http-credentials-leaked annotations: message: {{ $labels.job }} is leaking http basic auth credentials. expr: sum by (cluster, job, pod) (count_over_time({namespaceprod} |~ http(s?)://(\\w):(\\w) [5m]) 0) for: 10m labels: severity: critical规则文件结构与 Prometheus 完全一致groups下可包含多个组每个组内可有多条规则。alert指定告警名称expr是 LogQL 表达式for表示条件持续满足多久才触发10mlabels为告警附加标签annotations为告警附加说明信息支持{{ $labels.xxx }}模板引用标签。录制规则Recording Rules同样地Loki 支持Prometheus 兼容的录制规则。按 Prometheus 官方定义录制规则允许你预计算频繁使用或计算昂贵的表达式并把结果保存为一组新的时间序列。查询预计算结果通常比每次执行原始表达式快得多这对每次刷新都要重复查询同一表达式的仪表盘尤其有用。由于 Loki 允许对日志执行指标查询你完全可以从日志中推导出数值聚合——例如从 NGINX 访问日志计算单位时间内的请求数。录制规则示例name: NginxRules interval: 1m rules: - record: nginx:requests:rate1m expr: | sum( rate({containernginx}[1m]) ) labels: cluster: us-central1这条规则的含义每1minterval执行一次expr查询结果以record指定的指标名nginx:requests:rate1m存储。该指标随后可以被发送到 Prometheus像其他任何指标一样被存储与查询——也就是说录制规则把日志条目转化成了 Prometheus 指标。限制告警与录制样本数量Limiting Alerts and Recording Rule Samples与 Prometheus 类似你可以为告警规则产生的告警数量、录制规则产生的样本数量配置每规则组per-group限制。使用限制可以防止有缺陷的规则生成海量告警或录制样本。当超出限制时录制规则产生的所有样本都会被丢弃告警规则的所有告警active、pending 或 inactive 状态都会被清除该事件会被记录为一次评估错误规则健康状态rule health被置为err。limit的默认值为0表示无限制。带 limit 的规则组示例groups: - name: production_rules limit: 10 interval: 1m rules: - alert: HighPercentageError expr: | sum(rate({appfoo, envproduction} | error [5m])) by (job) / sum(rate({appfoo, envproduction}[5m])) by (job) 0.05 for: 10m labels: severity: page annotations: summary: High request latency - record: nginx:requests:rate1m expr: | sum( rate({containernginx}[1m]) ) labels: cluster: us-central1注意limit: 10位于组级别production_rules组对组内所有规则生效interval: 1m同样定义在组级别控制该组规则的评估周期。Remote-Write把录制指标写入 Prometheus 兼容后端录制规则可以按固定间隔持续运行这些指标查询并把结果指标写入Prometheus 兼容的 remote-write 端点从而从日志条目中生产 Prometheus 指标。官方文档列举的当前兼容后端包括Prometheus v2.25.0Prometheus 通常是拉取式系统但自 v2.25.0 起也支持直接写入指标。Grafana Mimir通过其 remote-write HTTP API 接收数据。ThanosReceiver 组件。写入本地 Prometheusruler: ... other settings ... remote_write: enabled: true clients: prometheus: url: http://localhost:9090/api/v1/write写入 Grafana Mimirruler: remote_write: enabled: true clients: mimir: url: http://mimir:9009/api/v1/push为 Mimir 端点配置认证ruler: remote_write: enabled: true clients: mimir: url: https://mimir.example.com/api/v1/push basic_auth: username: USERNAME password: PASSWORD关于 X-Scope-OrgID 头的重要说明默认情况下Loki 会使用产生样本的录制规则所属的tenant ID为 remote-write 请求添加X-Scope-OrgID头。因此不要在headers下手动设置X-Scope-OrgID——Loki 会在运行时发送 remote-write 请求前将其剥离。从源码上看这一行为由 pkg/ruler/config.go 中的RemoteWriteConfig定义其字段包括clientsremote-write 客户端映射key 为客户端 ID、enabled是否启用、config_refresh_period刷新 remote-write 配置的最小间隔对应 flag-ruler.remote-write.config-refresh-period默认 10 秒且应不小于-runtime-config.reload-period、以及add_org_id_header对应 flag-ruler.remote-write.add-org-id-header默认true即默认自动添加X-Scope-OrgID头。同时该配置的注释明确指出在headers中指定X-Scope-OrgID是不被允许的若被指定会在配置解析时被丢弃。RemoteWriteConfig.Validate()pkg/ruler/config.go还会校验启用 remote-write 但未配置任何客户端时会直接报错remote-write enabled but no clients are configured客户端 URL 缺失或非法也会被拒绝。与 Ruler 交互的三种方式由于 Loki 的规则文件与 Prometheus 规则文件完全一致你可以通过多种工具管理远端 Loki 的规则。Lokitool可以通过lokitool与 Loki Ruler 交互旧版 Loki 3.1 之前使用cortextool。它位于仓库的 cmd/lokitool/main.go是一个基于 kingpin 的命令行工具注册了rules与audit两个命令族。注意lokitool 面向多租户 Loki 运行。命令需要设置--id标志为 Loki 实例 ID或设置环境变量LOKI_TENANT_ID。如果 Loki 以单租户模式运行所需 ID 为fake。一个完整的工作流示例如下# format the rules.yaml file, reordering keys and reformatting PromQL expressions lokitool rules format ./output/rules.yaml # diff rules against the currently managed ruleset in Loki lokitool rules diff --rule-dirs./output # diff only specific namespaces using comma-separated list lokitool rules diff --rule-dirs./output --namespacesnamespace1,namespace2 # diff using regex to match namespaces lokitool rules diff --rule-dirs./output --namespaces-regex^prod-.* # diff while ignoring specific namespaces lokitool rules diff --rule-dirs./output --ignored-namespacestest,dev # diff while ignoring namespaces matching regex lokitool rules diff --rule-dirs./output --ignored-namespaces-regex^test-.* # ensure the remote ruleset matches your local ruleset, creating/updating/deleting remote rules which differ from your local specification. lokitool rules sync --rule-dirs./output # sync only specific namespaces (supports --namespaces, --namespaces-regex, --ignored-namespaces, --ignored-namespaces-regex) lokitool rules sync --rule-dirs./output --namespaces-regex^prod-.* # print the remote ruleset lokitool rules printdiff与sync命令支持命名空间过滤以下四个标志一次只能使用一个--namespaces要检查的命名空间逗号分隔列表--namespaces-regex匹配命名空间的正则--ignored-namespaces要忽略的命名空间逗号分隔列表--ignored-namespaces-regex匹配要忽略的命名空间的正则Terraform借助 Loki 的 Terraform provider可以用 HCL 格式管理告警与录制规则terraform { required_providers { loki { source fgouteroux/loki } } } # Provider config provider loki { uri http://127.0.0.1:3100 org_id mytenant } # Create an alert rule resource loki_rule_group_alerting test { name test1 namespace namespace1 rule { alert HighPercentageError expr EOT sum(rate({appfoo, envproduction} | error [5m])) by (job) / sum(rate({appfoo, envproduction}[5m])) by (job) 0.05 EOT for 10m labels { severity warning } annotations { summary High request latency } } } # Create a recording rule resource loki_rule_group_recording test { name test1 namespace namespace1 rule { expr sum by (job) (http_inprogress_requests) record job:http_inprogress_requests:sum } }loki_rule_group_alerting资源用于创建告警规则组loki_rule_group_recording用于创建录制规则组namespace对应 Loki 规则 API 中的命名空间概念。Cortex rules actionCI/CD 集成Cortex rules action把 Loki 作为后端引入非常适合在 CI/CD 流水线中管理规则可对本地目录与远端 Loki 实例之间的规则执行 lint、diff 和 sync- name: Lint Loki rules uses: grafana/cortex-rules-actionmaster env: ACTION: check RULES_DIR: SOURCE_DIR_OF_RULES # Example: logs/recording_rules/,logs/alerts/ BACKEND: loki - name: Deploy rules to Loki staging uses: grafana/cortex-rules-actionmaster env: CORTEX_ADDRESS: LOKI_INGRESS_ADDR CORTEX_TENANT_ID: fake ACTION: sync RULES_DIR: SOURCE_DIR_OF_RULES # Example: logs/recording_rules/,logs/alerts/ BACKEND: loki其中ACTION: check用于 lint 校验ACTION: sync用于把本地规则同步部署到远端 Loki。调度与最佳实践Ruler 的横向扩展Sharding扩展 Ruler 的一种方式是横向扩容。但多个 Ruler 实例共存时它们需要协调确定哪个实例评估哪条规则。与 ingester 类似Ruler 通过建立一个hash ring哈希环来划分评估规则的责任。完整配置见配置文档但要把规则分片到多个 Ruler 上必须满足两个前提通过 flag-ruler.enable-api或配置文件参数开启规则 API为 Ruler 配置它自己的 ring。之后 Ruler 会自动分片并处理规则划分。与 ingester 不同的是Ruler 之间不做责任交接每当有 Ruler 加入或离开 ring所有规则都会被随机重新分片。从源码结构看这一逻辑位于 pkg/ruler/base/ruler.goConfig中定义了EnableSharding对应 flag-ruler.enable-sharding默认false、ShardingStrategy支持默认与 shuffle 两种策略以及ShardingAlgo支持by-group与by-rule两种分片算法默认按规则组by-group分片。Ruler 的 ring 以rulers为 key 存储在 KVStore 中见 pkg/ruler/base/ruler.goring 配置含kvstore部分定义在 pkg/ruler/base/ruler_ring.go。一个完整的、启用分片的 Ruler 配置示例ruler: alertmanager_url: ALERTMANAGER_ENDPOINT enable_alertmanager_v2: true # true by default since Loki 3.2.0 enable_api: true enable_sharding: true ring: kvstore: consul: host: consul.loki-dev.svc.cluster.local:8500 store: consul rule_path: /tmp/rules storage: gcs: bucket_name: LOKI_RULES_BUCKET要点解读enable_sharding: true开启分片ring.kvstore.store: consul使用 Consul 作为 ring 的 KV 存储ring.kvstore.consul.host指向 Consul 地址规则存储storage.gcs使用对象存储确保所有 Ruler 读到同一份规则。Ruler 存储规则文件放在哪里Ruler 支持以下存储类型azure、gcs、s3、swift、cos与local。大多数存储类型以显而易见的方式适配分片式 Ruler 配置——即让所有 Ruler 使用同一个后端。此外从 pkg/ruler/base/storage.go 的RuleStoreConfig看还额外支持alibabacloud阿里云 OSS与bos百度 BOS两种对象存储存储类型通过 flag-ruler.storage.type指定pkg/ruler/base/storage.go。本地local存储local 实现从本地文件系统读取规则文件。这是一个只读后端不支持通过 Ruler API 创建和删除规则。即便如此只要运维方保证把相同的规则加载到每个 Ruler例如通过把 Kubernetes ConfigMap 挂载到每个 Ruler Pod它仍然可以用于分片式 Ruler 配置。典型本地配置-ruler.storage.typelocal -ruler.storage.local.directory/tmp/loki/rules在上述配置下Ruler 期望的目录布局如下/tmp/loki/rules/tenant id/rules1.yaml /rules2.yaml即本地目录/租户 ID/规则文件.yaml。YAML 文件需为 Prometheus 兼容格式但表达式使用本文前述的 LogQL。远程规则评估Remote rule evaluation对于规模较大、规则复杂的部署Ruler 的本地评估模式会产生与 Grafana 中看到的结果不一致或不完整的问题。为解决这一问题可以使用远程评估模式让规则针对query-frontend执行查询。该能力在源码中的实现是 pkg/ruler/evaluator_remote.go 中的RemoteEvaluator它以 gRPC 方式连接 query-frontend向/loki/api/v1/query端点pkg/ruler/evaluator_remote.goPOST 查询参数query、directionforward、time请求头携带租户 ID 与sourceruler的查询标签并支持按租户配置超时ruler_remote_evaluation_timeout与响应大小上限ruler_remote_evaluation_max_response_size超出限制的评估会被标记为失败对应failedEvals指标。query-frontend 的连接地址通过 flag-ruler.evaluation.query-frontend.address配置。更详细的扩展性说明可参考可扩展性文档。指标后端与内存存储Metrics backends vs in-memory目前 Loki Ruler 与后端的 Prometheus 存储是解耦的。通常规则评估的结果以及告警状态的历史会作为时间序列存储但 Loki 自身无法存储/检索这些序列以便它能够独立于 Prometheus 运行。作为变通方案Loki 维护了一个小型内存存储对应仓库中的 pkg/ruler/memstore.go其用途是在重新调度或重新分片 Ruler 时惰性加载lazy load过去的评估结果从而恢复告警for状态的连续性避免因实例迁移导致告警状态丢失。小结围绕 Loki Ruler本文完整覆盖了告警规则与录制规则的定义与写法、组级limit样本限制、remote-write 写入 Prometheus/Mimir 的配置与X-Scope-OrgID处理、lokitool / Terraform / Cortex rules action 三种管理方式、基于 hash ring 的横向分片扩展、六种规则存储后端与本地目录布局以及远程评估与内存存储的工作原理。从仓库源码pkg/ruler/config.go、pkg/ruler/base/ruler.go、pkg/ruler/evaluator_remote.go可以看出Ruler 的设计目标始终是与 Prometheus 规则生态完全兼容同时用 LogQL 把日志转化为指标与告警。掌握了上述配置与原理你就可以在生产环境安全地让 Loki 基于日志持续产出告警与指标把可观测性覆盖到那些只有日志的系统与组件上。【免费下载链接】lokiLike Prometheus, but for logs.项目地址: https://gitcode.com/GitHub_Trending/lok/loki创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
