> ## Documentation Index
> Fetch the complete documentation index at: https://docs.molesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 日志巡检

> 让 Mole Agent 按需或按周期巡检日志数据流，保存每次的报告，并在报告判定有异常时发出通知。

日志巡检让 Mole Agent 阅读一段时间的日志并写出报告：这段时间有没有问题、问题是什么、依据是哪些日志。巡检只读取日志，不修改任何数据或配置。

| 方式 | 用途 |
| - | - |
| **按需巡检** | 在 **日志** 的 **智能巡检** 视图中，对当前查询匹配的日志立即巡检一次，报告在页面上流式写出。这次巡检是一条 Mole Agent 对话，可以在 **Mole Agent** 中继续追问；它不进入定时巡检的历史报告。 |
| **定时巡检** | 保存数据流、查询条件和巡检要求。MoleSignal 按周期巡检，保存每次的报告，并在报告判定有异常时通知。 |

## 开始之前

* 在 **Mole Agent → 设置 → 模型与推理** 中至少启用一个 AI 模型，参见 [Mole Agent](https://docs.molesignal.com/zh-Hans/agent#配置模型服务)。没有启用的模型时，已保存的巡检仍然列出，但无法执行。
* 确认权限：

| 操作 | 权限 |
| - | - |
| 按需巡检；查看定时巡检及其报告 | `agent.use` 和 `streams.query` |
| 新建、编辑、启用或停用、删除、立即执行 | `inspections.manage`，默认授予 owner、admin 和 editor 角色 |
| 在表单中选择通知渠道 | `alerts.read`，用于列出通知连接器 |

Mole Agent 在对话中用 `list_log_inspections`、`list_log_inspection_runs` 和 `get_log_inspection_run` 读取同样的巡检与报告，权限要求相同。`run_log_inspection` 立即执行一次巡检，需要 `inspections.manage`，默认还要在对话中确认。参见 [Tool Catalog 与执行模型](https://docs.molesignal.com/zh-Hans/tools.md)。

## 按需巡检

1. 打开 **日志**，选择数据流和时间范围并执行查询。查询留空则巡检该数据流的全部日志。
2. 打开 **智能巡检** 视图。
3. 选择 **AI 模型**。可以在 **巡检要求** 中说明关注点，例如要关注的服务，或应视为预期结果的情况。
4. 选择 **开始巡检**。

巡检会把这些日志的查询结果发送给所选模型。选择 **在 Mole Agent 中继续**，可以针对报告继续追问。

## 保存定时巡检

打开 **日志 → 智能巡检**，然后选择其中一个入口：

* **保存为定时巡检** 打开表单，并带上当前的数据流、查询条件、巡检要求和模型。当前查询没有匹配结果时也可以保存。
* **定时巡检** 打开列表，在列表中选择 **新建巡检** 打开空白表单。

| 字段 | 说明 |
| - | - |
| **名称** | 组织内唯一，最多 120 个字符。 |
| **数据流** | 一条日志数据流。巡检只读取这条数据流。 |
| **查询条件** | 选填。只巡检符合条件的日志，写法与 **日志** 页相同。 |
| **巡检要求** | 选填，最多 2,000 个字符。说明关注什么、什么算正常。 |
| **周期** | **按间隔**、**每天** 或 **每周** 的某个时刻。最短间隔由实例配置决定，默认为 1 小时。 |
| **覆盖时间** | 每次执行查看执行时刻之前多长时间的日志，表单中可选 15 分钟到 7 天，默认与周期一致。 |
| **AI 模型** | 组织内已启用的一个模型。 |
| **何时通知** | **仅异常时通知**（默认）、**需关注及以上时通知** 或 **每次都通知**。 |
| **通知渠道** | 选填，最多 10 个。每个渠道是通知连接器上的一个固定群组或固定地址。 |
| **保存后按周期自动执行** | 关闭时只保存巡检，仅在选择 **立即执行** 时运行。 |

每天或每周的时刻按新建时界面所用的时区计算：个人偏好中的时区；未设置时为浏览器的时区。表单会写明时区，之后编辑不会改变它。通知和报告使用新建时的界面语言。

默认情况下，每个组织最多保存 20 条定时巡检。

## 执行方式

| 方面 | 行为 |
| - | - |
| 执行身份 | 巡检以最后一次保存它的用户的身份读取日志。每次执行前，MoleSignal 都会核对该用户仍可登录、仍是组织成员，并且仍有 `agent.use` 和 `streams.query`。核对不通过时，本次执行记为失败，原因是执行身份已不可用；由其他有权限的用户重新保存一次，即可改用该用户的身份执行。API Token 不能保存定时巡检。 |
| 工具 | 模型只使用三个只读工具：`query_logs`、`get_stream_schema` 和 `search_field_values`，并且只能读取巡检所选的数据流。组织的 Tool Policy 停用或要求审批的工具不会被使用，因为后台没有人审批。 |
| 时间窗口 | 每次执行覆盖执行时刻之前的一段时间。节点停机期间错过的执行不会补跑：节点恢复后，到期的巡检执行一次，之后按周期继续。 |
| 上限 | 单次执行默认不超过 5 分钟，超过记为超时。超过 64 KiB 的工具结果不会交给模型，而是要求模型收窄查询。失败的执行不重试，等待下一个周期。 |
| 并发 | 同一条巡检同一时刻只有一次执行。默认情况下，一个节点同时最多执行 2 条巡检。 |
| **立即执行** | 本次执行先排队，在 15 秒内开始，身份仍是巡检的执行身份，记录中会写明发起的用户。已停用的巡检也可以这样执行。 |

## 报告与结论等级

在列表中选择一条巡检，打开它的报告。左侧是历次执行，选中的执行显示报告、覆盖的时间范围、用时、调用过的工具、消耗的 token 和发出的通知。**查看这段时间的日志** 会以相同的数据流、查询条件和时间范围打开 **日志**。

定时巡检的报告带有结论等级：

| 等级 | 含义 |
| - | - |
| **正常** | 没有需要处理的问题。 |
| **需关注** | 有值得留意的迹象，暂不构成故障。 |
| **异常** | 发现了需要处理的问题。 |
| **未判定** | 模型的回答中没有可读取的等级。报告照常保存，通知时按异常处理。 |

没有完成的执行没有报告，记录中显示状态和原因：

| 状态 | 原因 |
| - | - |
| **超时** | 执行超过了时间上限。 |
| **失败** | 执行身份已不可用；所选 AI 模型不存在、已停用或没有密钥；模型调用失败；组织今天的 Mole Agent token 预算已用完；节点在执行中途退出；没有节点来执行；或内部错误。 |

报告默认保留 30 天，过期后每小时清理一次。删除一条巡检会同时删除它的全部报告。

## 通知

* 报告的结论等级达到 **何时通知** 的要求时，每个渠道收到一条通知：标题说明等级和巡检名称，正文包含数据流、时间范围、等级、报告摘要和报告链接。链接需要配置 `http.external_url`。
* 执行失败时，只在上一次执行不是失败的情况下通知一次。连续失败只通知第一次，不受 **何时通知** 影响。
* 没有选择渠道时不发送通知，报告仍然保存。
* 每条通知都出现在 **设置 → 通知 → 投递记录** 中，阶段为 **直接发送**。直接发送不经过通知策略，也不能从投递记录中重试。
* 被定时巡检使用的通知连接器不能删除。

## 实例配置

| 配置项 | 默认值 | 用途 |
| - | - | - |
| `[log_inspection].min_interval_secs` | `3600` | 同一条巡检两次执行之间的最短间隔。小于 60 时按 60 处理。 |
| `[log_inspection].max_per_org` | `20` | 每个组织可以保存的定时巡检数量。`0` 表示不允许创建。 |
| `[log_inspection].concurrent_runs` | `2` | 单个节点同时执行的巡检数量。 |
| `[log_inspection].run_timeout_secs` | `300` | 单次执行的时间上限，包含全部模型调用和查询。取值收敛到 30–480。 |
| `[log_inspection].report_retention_days` | `30` | 报告的保留时间。 |

定时巡检由承担 `alert` 角色的节点执行，每 15 秒检查一次是否有到期或排队的执行。部署多个 `alert` 节点时，每次执行只会被一个节点领取。参见[分角色部署](https://docs.molesignal.com/zh-Hans/deployment/role-based.md)。

以下两个指标反映执行情况：

| 指标 | 含义 |
| - | - |
| `log_inspection_runs_total{outcome}` | 按结果统计的已结束执行次数：`succeeded`、`failed` 或 `timed_out`。 |
| `log_inspection_run_duration_seconds` | 单次执行的耗时。 |

## API

接口位于 `/api/v1/logs/inspections` 下：

| 方法与路径 | 用途 |
| - | - |
| `GET /logs/inspections` | 列出组织的定时巡检。 |
| `POST /logs/inspections` | 新建巡检。 |
| `GET /logs/inspections/limits` | 实例设定的限制。 |
| `GET`、`PUT`、`DELETE /logs/inspections/{id}` | 读取、整体更新，或连同报告一起删除一条巡检。 |
| `POST /logs/inspections/{id}/enabled` | 启用或停用巡检。 |
| `POST /logs/inspections/{id}/run` | 立即执行一次。 |
| `GET /logs/inspections/{id}/runs` | 历次执行，新的在前，不含报告正文。`limit` 默认 50，最大 200；`before` 用于翻到更早的执行。 |
| `GET /logs/inspections/{id}/runs/{run_id}` | 一次执行及其报告。 |

> **[日志](https://docs.molesignal.com/zh-Hans/logs)**
>
> 编写巡检所读取的查询。

> **[通知渠道](https://docs.molesignal.com/zh-Hans/notification-channels)**
>
> 接入接收通知的渠道。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.