> ## Documentation Index
> Fetch the complete documentation index at: https://test-8ad8522e-feat-ai-sre.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Loki

> 配置 Loki 数据源的告警规则，支持 LogQL 查询语法

Monitors 支持 Loki 的 LogQL 查询语法，能够对日志数据进行聚合分析并触发告警。

## 核心概念

Loki 的查询语言 LogQL 分为两类：

| 类型                        | 说明                                          |
| ------------------------- | ------------------------------------------- |
| **日志查询 (Log Queries)**    | 返回日志行内容（Stream）                             |
| **指标查询 (Metric Queries)** | 对日志进行计数或聚合，如 `count_over_time` 返回数值（Vector） |

<Tip>
  编写 LogQL 时，查询输入框会根据数据源自动补全标签名和标签值，帮助你快速定位日志流。
</Tip>

## 1. 阈值判定模式 (Threshold)

此模式适用于需要对日志聚合值进行多级阈值判定（如 Info/Warning/Critical）的场景。

### 配置方式

* **查询语句 (LogQL)**：编写返回数值向量的 LogQL（查询模式选择"做统计"）

**示例**：统计最近 5 分钟内，`mysql` 任务中包含 `error` 关键字的日志条数：

```text theme={null}
count_over_time({job="mysql"} |= "error" [5m])
```

* **阈值条件**：
  * **Critical**: `$A > 50` (5分钟内错误日志超过 50 条)
  * **Warning**: `$A > 10` (5分钟内错误日志超过 10 条)

### 工作原理

引擎执行 LogQL 查询，获取带有标签的时间序列数据（Vector）。引擎遍历每个序列，提取数值与配置的阈值表达式进行比对。

### 恢复逻辑

| 策略         | 说明                      |
| ---------- | ----------------------- |
| **自动恢复**   | 当查询结果数值回落到阈值以下时，自动恢复    |
| **特定恢复条件** | 可配置如 `$A < 5`，避免在阈值附近震荡 |
| **恢复查询**   | 支持独立 LogQL 用于恢复判定       |
| **手工关闭**   | 告警保持活动，直到用户手工关闭         |

## 2. 数据存在模式 (Data Exists)

此模式适用于习惯在 LogQL 中直接写过滤条件，或者只关心"是否有异常数据"的场景。推荐使用此模式做日志异常检测告警。

### 配置方式

* **查询语句 (LogQL)**：编写包含比较操作符的 LogQL，仅返回满足条件的数据

**示例**：直接筛选出错误率超过 5% 的服务：

```text theme={null}
count_over_time({job="ingress"} |= "error-code-500" [5m]) / count_over_time({job="ingress"} [5m]) * 100 > 5
```

* **判定规则**：只要 LogQL 查询返回了数据，即触发告警

### 优缺点分析

| 类型     | 说明                      |
| ------ | ----------------------- |
| **优点** | 计算逻辑下推至 Loki 服务端，减少数据传输 |
| **缺点** | 无法区分告警级别，只能触发单一级别的告警    |

### 恢复逻辑

* **数据消失即恢复**：当 LogQL 查询结果为空时，判定恢复
* **恢复查询**：支持配置额外的查询语句用于辅助判断恢复状态
* **手工关闭**：告警保持活动，直到用户手工关闭

## 3. 数据缺失模式 (No Data)

此模式用于监控日志上报链路是否中断，或者预期应该持续产生的日志是否停止了。

### 配置方式

* **查询语句 (LogQL)**：编写预期应该一直有数据的查询

**示例**：统计所有主机的日志上报速率：

```text theme={null}
rate({job="node-logs"} [1m])
```

* **判定规则**：如果某个 Series（由标签唯一标识，如 `instance="host-1"`）在之前的周期中存在，但在当前及连续 N 个周期中查不到数据，则触发"数据缺失"告警

### 恢复逻辑

无数据告警支持配置**告警结束方式**，决定告警如何结束：

| 结束方式             | 说明                                                                |
| ---------------- | ----------------------------------------------------------------- |
| **数据重新出现后自动结束**  | 默认方式。数据重新出现后，告警自动结束                                               |
| **数据恢复或超时后自动结束** | 数据重新出现或达到自动关闭时间后，告警自动结束。自动关闭时间单位为秒，最小为 1；仅开启「之前查到过数据，现在查不到了」模式时可选 |
| **仅允许手工关闭**      | 告警保持活动，直到用户手工关闭                                                   |

### 典型应用

* 监控 Promtail/Fluentd 等采集 Agent 是否停止工作
* 监控关键业务日志（如订单创建日志）是否异常中断

## 4. 使用查原文模式作为主查询

当你希望“查到符合条件的日志就告警”时，可以选择**查原文**模式，并使用**数据存在**判定。假设查询返回 `job`、`service`、`__time__`、`__log__` 等字段：

* **标签字段**：选择 `job`、`service` 等稳定维度，用于标识告警对象。
* **值字段**：数据存在模式下可以留空。如果使用阈值判定，请选择能转换为数字的字段。
* **附加信息**：`__time__`、`__log__` 和其他未选中的非值字段会自动随告警携带。

<Warning>
  不要把 `__time__`、`__log__`、Trace ID 等频繁变化的字段配置为标签。否则每条日志都可能形成一个新的告警对象。
</Warning>

详细的默认行为、阈值引用方式和多查询对齐要求，请参见[查询结果字段映射](/zh/monitors/alert-rules/query-result-fields)。

## 5. 通过关联查询获取日志原文

告警时可以通过关联查询获取日志原文。但通常不建议获取太多，只获取 1 条作为日志样例放置到告警消息中。

![](https://docs-cdn.flashcat.cloud/imges/mon/ca5ea15fcfca066f260e09d0f8d91cf2.png)

关联查询的结果可以渲染在"备注描述"中，示例：

```text theme={null}
{{- if eq $status "firing" }}
error log count: {{ $value | printf "%.3f" }}
{{- range $x := $relates.R1}}
Loki log time: {{(nanoTime $x.Fields.__time__ 8).Format "2006-01-02T15:04:05Z07:00"}}
Loki Log line: {{$x.Fields.__log__}}
{{- end}}
{{- end}}
```