Loki Helm Chart 监控与告警部署指南：内置 Prometheus Operator 资源与 Grafana 仪表盘

Loki Helm Chart 监控与告警部署指南：内置 Prometheus Operator 资源与 Grafana 仪表盘

【免费下载链接】lokiLike Prometheus, but for logs.项目地址: https://gitcode.com/GitHub_Trending/lok/loki

本文聚焦于通过 Loki 官方 Helm Chart 为部署在 Kubernetes 上的 Loki 集群配置监控与告警：如何一次性渲染出 ServiceMonitor、Recording Rules、Alert Rules 与 Grafana 仪表盘，以及如何改用 Grafana Operator 自动导入仪表盘。读完本文，你将掌握monitoring配置块的完整用法、告警规则的参数调优方式，以及官方推荐的替代监控方案（Kubernetes monitoring Helm chart），从而为 Loki 建立开箱即用的可观测性体系。

概述：Helm Chart 内置监控能力

Loki Helm Chart 提供了一组内置监控资源渲染能力，可以直接从上游的 loki-mixin（一个用 Jsonnet 编写的、基于 Grafana Cloud 运维 Loki 经验沉淀出的仪表盘/告警/规则集合）生成以下四类 Kubernetes 资源：

• ServiceMonitor：供 Prometheus Operator 抓取 Loki 各组件/metrics端点的指标；
• PrometheusRule（Recording Rules）：为仪表盘提供预聚合的录制规则；
• PrometheusRule（Alert Rules）：内置的 Loki 告警规则；
• Grafana 仪表盘：以 ConfigMap 或 Grafana Operator 自定义资源形式提供开箱即用的 Loki 监控面板。

这些资源全部统一收拢在 Helm values 的monitoring配置块下（见 values.yaml），并且在默认情况下全部处于关闭状态——所有enabled字段默认值均为false，需要显式开启。

最小启用示例

monitoring: serviceMonitor: enabled: true rules: enabled: true # recording rules only alerts: enabled: true # alert rules (separate since chart 18.0.0) dashboards: enabled: true

版本行为说明（chart 18.0.0 起）

从 chart 18.0.0 开始，告警规则被拆分到独立的monitoring.alerts键下管理，monitoring.rules仅负责录制规则（recording rules）。同时，用于标识发布实例的指标标签默认名为app_instance，由monitoring.appInstanceLabelName控制。

⚠️ 注意版本差异：当前仓库检出的 Helm Chart 版本为 7.3.0（见 Chart.yaml），该版本中告警仍由monitoring.rules.alerting开关控制（默认true），monitoring.alerts是文档所描述的新版（18.0.0+）行为。升级到新版 Chart 时需将配置迁移到monitoring.alerts下。完整的monitoring.*键值说明可查阅 Helm Chart Reference（其中monitoring.alerts.*、monitoring.appInstanceLabelName等条目即为新版字段的权威参考）。

一、ServiceMonitor：让 Prometheus 抓取 Loki 指标

Loki 各组件都会在/metrics端点暴露 Prometheus 格式指标，ServiceMonitor 是 Prometheus Operator 发现并抓取这些指标的标准方式。

monitoring: serviceMonitor: enabled: true namespaceSelector: {} annotations: {} labels: {} interval: 15s scrapeTimeout: null relabelings: [] metricRelabelings: [] scheme: http tlsConfig: null

从模板实现 servicemonitor.yaml 可以看到几个值得注意的细节：

• 抓取端点：固定为port: http-metrics、path: /metrics；
• 默认抓取间隔 15s：values.yaml 注释明确说明，内置录制规则基于 1m 的 rate 窗口计算，抓取间隔至少要达到 rate 窗口的 1/4（即 ≤ 15s），否则录制规则会失真；
• relabel 逻辑：模板内置了两条 relabel 规则——将job标签替换为namespace/job格式（便于区分不同命名空间下的同名服务），以及写入cluster标签；relabelings与metricRelabelings可用于追加自定义 relabel；
• 标签排除：selector中通过prometheus.io/service-monitor标签的NotIn "false"表达式，允许用户手动为某个 Service 打上prometheus.io/service-monitor: "false"以跳过抓取；
• 条件渲染：模板会检测集群是否安装monitoring.coreos.com/v1/ServiceMonitorAPI，未安装时不会渲染该资源。

此外，在旧版 Chart 中还提供metricsInstance（为 Grafana Agent Operator 创建 MetricsInstance 资源做 remote write）选项，但它已被标记为 DEPRECATED。

二、Recording Rules：仪表盘的数据基础

monitoring.rules负责渲染名为<release>-loki-rules的 PrometheusRule 资源，其中包含录制规则（recording rules），这些规则是多个内置仪表盘的查询基础，模板见 loki-rules.yaml，规则本体定义在 src/rules.yaml.tpl。

monitoring: rules: enabled: true namespace: null # 可选，将 PrometheusRule 放到其他命名空间 annotations: {} labels: {} additionalRuleAnnotations: {} additionalRuleLabels: {} additionalGroups: []

录制规则覆盖了请求延迟的百分位、均值与速率等典型指标，例如：

- expr: histogram_quantile(0.99, sum(rate(loki_request_duration_seconds_bucket[1m])) by (le, job)) record: job:loki_request_duration_seconds:99quantile

每条规则都会被打上cluster标签（与 ServiceMonitor 的 relabel 相呼应），保证多集群场景下指标可区分。

additionalGroups允许追加自定义规则组，模板中会将其与内置规则一并渲染进同一个 PrometheusRule：

additionalGroups: - name: additional-loki-rules rules: - record: job:loki_request_duration_seconds_bucket:sum_rate expr: sum(rate(loki_request_duration_seconds_bucket[1m])) by (le, job)

三、Alert Rules：内置告警与参数调优

新版：monitoring.alerts（chart 18.0.0+）

告警规则渲染为名为<release>-loki-alerts的 PrometheusRule，对应模板 loki-alerts.yaml，规则本体在 src/alerts.yaml.tpl。新版 Chart 的完整配置项包括：

当前仓库版本：monitoring.rules.alerting（chart 7.3.0）

当前仓库 Chart（7.3.0）中，告警与录制规则共用monitoring.rules块，由alerting开关（默认true）控制是否同时渲染告警，disabled用于逐个关闭告警。values.yaml 中为每个内置告警提供了参数化的configs，包括：

例如LokiRequestErrors的表达式为：

100 * sum(rate(loki_request_duration_seconds_count{status_code=~"5.."}[2m])) by (namespace, job, route) / sum(rate(loki_request_duration_seconds_count[2m])) by (namespace, job, route) > 10

这些告警规则最初源自 alerts.libsonnet，Chart 将其参数化后供用户直接调整阈值、持续时间与严重级别。若把所有告警都 disable 却仍保留alerting: true，Chart 渲染会失败——此时应直接设置alerting: false。

四、Dashboards：开箱即用的 Loki 监控面板

方式一：ConfigMap（默认渲染方式）

monitoring: dashboards: enabled: true namespace: null annotations: {} labels: grafana_dashboard: "1"

启用后，Chart 会生成携带grafana_dashboard: "1"标签的 ConfigMap（模板见 configmap-1.yaml 与 configmap-2.yaml），配合 Grafana 的 ConfigMap sidecar（如 grafana-sidecar 自动发现机制）即可自动导入仪表盘。面板 JSON 同样来自 loki-mixin 项目（production/loki-mixin/dashboards 目录包含 loki-operational、loki-reads、loki-writes、loki-logs、loki-chunks、loki-retention、loki-canary 等一系列面板）。这些面板需要上文提到的录制规则才能完整工作，因此通常建议rules.enabled与dashboards.enabled同时开启。

方式二：Grafana Operator（推荐用于 Operator 管理的 Grafana）

当你的 Grafana 由 Grafana Operator 管理时，Chart 可以改为渲染GrafanaDashboard自定义资源，让 Operator 直接把面板导入 Grafana，无需再依赖 sidecar 监听 ConfigMap：

monitoring: dashboards: enabled: true grafanaOperator: enabled: true instanceSelector: matchLabels: dashboards: "grafana" folder: Loki

关键字段说明：

• instanceSelector：标签选择器，Grafana Operator 用它匹配 Grafana 自定义资源上的标签来决定把面板导入到哪个实例；默认空选择器（{}）会匹配所有 Grafana 实例；
• folder/folderUID/folderRef：三者都用于把面板放入 Grafana 的某个文件夹，只能设置其中一个。folder会在根层级创建同名文件夹（默认"General"），folderUID与folderRef则引用已存在的文件夹以支持子目录层级；
• resyncPeriod：Operator 重新同步资源的频率（默认10m）；
• annotations/labels：为 GrafanaDashboard 资源附加的注解与标签。

完整的monitoring.dashboards.grafanaOperator键列表（含默认值）见 Helm Chart Reference（monitoring.dashboards.grafanaOperator.*条目）。

五、release 标识标签：app_instance

为了让同一集群中不同发布（release）的 Loki 实例在指标与录制规则中可区分，新版 Chart 引入了一个 release 标识标签，默认名为app_instance：

• monitoring.appInstanceLabelName：注入到抓取指标与录制规则中的标签名，默认"app_instance"；
• monitoring.appInstanceLabelValue：该标签的取值，支持 Helm 模板，默认{{ include "loki.fullname" . }}（即当前 release 的完整名称）。

这取代了旧版 Chart 中的clusterLabelOverride/monitoring.serviceMonitor.clusterLabel方案（升级到社区版时的迁移对照可参考 upgrade-to-community 文档）。

六、推荐替代方案：Kubernetes monitoring Helm chart

{{< admonition type="warning" >}} Grafana Labs 已不再推荐使用 meta-monitoring Helm chart（即此前的monitoring.selfMonitoring/ Grafana Agent 集成，该集成在 chart 9.0.0 中被移除）来监控 Loki。为了把监控能力收敛到单一 Helm chart，官方推荐使用 Kubernetes monitoring Helm chart 中的 Manage 章节。 {{< /admonition >}}

这一变化在仓库代码中也有迹可循：当前 values.yaml 中monitoring.selfMonitoring整段被标记为 DEPRECATED，其下grafanaAgent、podLogs、logsInstance等配置全部标注为依赖已废弃的 Grafana Agent Operator；grafana-agent.yaml 等模板也仅在selfMonitoring.enabled时才渲染。因此新部署建议直接采用 Kubernetes monitoring Helm chart，而不是重新开启这些废弃配置。

关于 Kubernetes monitoring Helm chart 的具体部署方式、如何把 Loki 指标发送到独立的 Prometheus/Loki 实例，以及 Loki 暴露的全部监控指标清单，请继续阅读 meta-monitoring 系列文档。

七、验证与排障

在应用配置前，可以用 Helm 的模板渲染功能先行检查生成的资源是否符合预期：

helm template loki grafana/loki \ --set monitoring.serviceMonitor.enabled=true \ --set monitoring.rules.enabled=true \ --set monitoring.alerts.enabled=true \ --set monitoring.dashboards.enabled=true

观察输出的ServiceMonitor、PrometheusRule（loki-rules与loki-alerts）以及 ConfigMap/GrafanaDashboard 资源是否存在、标签是否正确。

仓库中 ci/legacy-monitoring-values.yaml 提供了完整的 CI 验证样例（开启 selfMonitoring、安装 Grafana Agent Operator、并为 ServiceMonitor 打上release: prometheus标签以匹配 Prometheus 实例的标签选择器），可作为排查“指标抓不到/告警不生效”问题的对照：例如 ServiceMonitor 的labels必须与 Prometheus 配置的serviceMonitorSelector匹配，monitoring.rules.enabled与仪表盘需成对开启，抓取间隔不应大于录制规则 rate 窗口的 1/4 等。

总结

Loki Helm Chart 将上游 loki-mixin 沉淀的运维经验直接编译为标准的 Prometheus Operator 资源与 Grafana 面板，让“部署 Loki 即获得完整可观测性”成为可能。配置时只需记住四个开关（serviceMonitor、rules、alerts、dashboards），并按版本差异选用monitoring.alerts（18.0.0+）或monitoring.rules.alerting（旧版）；若使用 Operator 管理的 Grafana，则通过grafanaOperator以自定义资源方式自动导入面板。对于新的生产部署，官方推荐改用 Kubernetes monitoring Helm chart 统一纳管监控，并将 Loki 自身的监控数据发送到独立的 LGTM 实例，以便在故障时仍能从外部观察集群状态。

【免费下载链接】lokiLike Prometheus, but for logs.项目地址: https://gitcode.com/GitHub_Trending/lok/loki