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

# 调查入口

> 为 Monitors 告警规则配置调查入口：从告警一跳直达仪表盘或查询工作台的初始查询，含入口字段、模板变量、校验限制与快照语义。

告警规则可以携带一组**调查入口**（Investigation entries）。每个入口是一个预配置的跳转目标：打开某个仪表盘，或用查询工作台打开一份已经写好、并被告警标签渲染过的初始查询。值班人员从一条告警出发就能直接看到该看的图或该查的数据，不必再手写查询。

入口配置在告警规则表单的**第 6 个区块「调查入口」**，随规则一起保存；入口只在**告警事件产生的那一刻**渲染成快照并随事件下发，之后规则再改也不会影响已经接受的告警。

<Warning>
  保存调查入口需要 monit-edge `v0.75.3` 或以上版本。保存时会检查该规则匹配到的数据源所在集群内**所有**活跃实例：只要有实例低于 `v0.75.3`，保存即被拒绝。详见[保存时的 Edge 版本要求](#保存时的-edge-版本要求)。
</Warning>

## 工作方式

一个告警规则可以保存多个调查入口。每条入口包含三部分：入口类型（仪表盘或查询）、该类型的配置、以及一个相对于告警事件时间的时间窗口。

* **入口是弱导航引用。** 保存配置和渲染快照都不会执行查询，也不会读取仪表盘内容；入口不参与告警判定、告警身份、实例身份或生命周期，也不触发任何自动调查任务。
* **入口跟随事件的数据源。** 一条规则可以按数据源类型与名称通配匹配多个数据源，但每个告警事件只来自其中一个。查询入口默认在**事件自己的数据源**上执行，因此跳过去看到的是触发告警的那个数据源，而不是某个固定或默认数据源；也可以显式指定其他数据源（例如用日志数据源做下钻）。
* **渲染发生在告警入库时。** monit-webapi 在接受事件时，用最终事件时间、事件的原始数据标签和事件数据源，把规则上当时配置的入口渲染成一份快照（Investigation Context），随事件一并保存与投递。**活跃告警**详情抽屉里的调查入口区块、**故障**详情综合信息面板里的排查入口区块（见[故障详情](/zh/on-call/incident/search-view-incident#排查入口)）、以及 AI SRE 读的都是这同一份快照。
* **入口名在两边叫法不同**：Monitors 里这一块叫**调查入口**，故障详情里叫**排查入口**，两者都是同一份事件快照。
* **顺序只影响展示。** 入口可以拖动排序，但第一项没有默认、主要或推荐语义；顺序不进入告警执行或生命周期。

## 入口类型

| 入口类型 | 按钮 | 跳转到 | 说明 |
| - | - | - | - |
| **仪表盘入口** | 添加仪表盘入口 | 仪表盘查看器 | 可定位到整个仪表盘、某个标签页、某个分组或某个图表，并为该仪表盘的模板变量指定取值 |
| **查询入口** | 添加查询入口 | 查询工作台 | 保存一份可编辑的初始查询（查询类型 + 查询语句 + 查询参数），并可指定在哪个数据源上执行 |

两类入口都不支持 Runbook、工单或任意 URL。

## 添加与编辑入口

**菜单入口**：配置告警规则的表单 → 区块 6「调查入口」。

1. 点击 **添加仪表盘入口** 或 **添加查询入口**，打开入口编辑弹窗。弹窗标题会区分是新增还是编辑（添加仪表盘入口 / 编辑仪表盘入口 / 添加查询入口 / 编辑查询入口）。
2. 填写**调查用途**和**时间范围**（两类入口通用），再填写该类型的字段（见下文）。
3. 点击 **确认**，入口加入规则表单。**确认只把入口加入表单，要保存规则后才生效**。
4. 规则列表上每条入口右侧有三个操作：**预览跳转**（眼睛图标）、**编辑**（铅笔图标）、**删除**（垃圾桶图标）。查看已保存规则的详情时，编辑按钮变成 **详情**，弹窗底部只有 **关闭**。

已添加的入口以列表展示：拖动最左侧的拖拽手柄可以调整顺序，列表标题取**调查用途**；没有写用途时，仪表盘入口显示仪表盘标题（读不到时显示仪表盘 ID），查询入口显示查询语句。

入口数量上限为 **20 个**：达到 20 个后两个添加按钮变为禁用，并在旁边提示 `最多 20 个调查入口`（详见[校验与限制](#校验与限制)）。

## 通用字段

| 字段 | 必填 | 说明 |
| - | - | - |
| **调查用途** | 否 | 一句话说明这个入口帮助确认什么。单行纯文本，换行符会被替换为空格；控制台把输入框限制为 200 个字符，后端同时按 **≤512 字节** 校验。用途**不渲染模板**，也不参与去重身份（两个入口只有用途不同仍然算重复）。它面向值班人员展示，也供 AI SRE 判断每个入口的意图 |
| **时间范围** | 是 | 「**告警前** N **分钟，至告警后** M **分钟**」，新建入口默认为告警前 60 分钟、告警后 0 分钟。两个方向都必须非负，且至少一个大于 0 |

时间范围的语义：

* 锚点是**告警事件时间**：开始时间 = 事件时间 − 告警前时长，结束时间 = 事件时间 + 告警后时长。
* 窗口完全按您配置的值写进快照，之后无论什么时候打开都不会随当前时间漂移；进入仪表盘或工作台后可以临时调整时间范围，但页面里的调整不会回写规则或已产生的快照。
* 允许结束时间晚于当前时刻（配置了告警后时长的入口会这样），告警一产生就能打开，不等待后续数据。
* 系统不推导、不提示、也不校验告警的计算窗口是否被覆盖。

## 仪表盘入口的字段

| 字段 | 说明 |
| - | - |
| **仪表盘** | 按标题或描述搜索并选择仪表盘；选中后下方会显示它所在的分组路径。**更换仪表盘会清空定位对象与变量取值**（它们都属于旧仪表盘） |
| **定位到** | `整个仪表盘`，或仪表盘内的某个标签页 / 分组 / 图表，选项后跟完整路径面包屑。整个仪表盘的入口打开仪表盘本身 |
| **变量取值** | 该仪表盘的每个模板变量一个输入框；留空表示使用仪表盘自己的默认值 |

**定位到**的失效处理：如果定位对象在仪表盘里已不存在（被删除或改名），字段会提示 `已不存在的对象（<id>）`，下方同时给出警告 `定位对象在仪表盘中已不存在，将打开仪表盘默认页签`——跳过去时打开仪表盘默认页签，不会失败。仪表盘本身加载失败（已删除或您无权查看）时，字段区显示 `仪表盘加载失败，可能已被删除或您无权查看`，此时定位到不可选。

**变量取值**的规则：

* 仪表盘没有变量时显示 `该仪表盘没有变量`。
* 变量取值统一按 **Go template** 渲染，可用变量见[模板变量](#模板变量)。数据源类变量会标注 `（数据源）`，占位提示为 `{{ $datasource.id }}`；普通变量的占位提示为 `留空使用仪表盘默认值，例如 {{ $labels.<变量名> }}`。
* 留空 = 未配置，仪表盘按自己的规则取默认值；配置了但渲染失败或渲染为空 = 保持 unresolved（不会回退默认值），并在入口上显示错误。
* 已配置、但仪表盘里已经不存在（或改名）的变量仍会列出来并标记 `仪表盘中已不存在`，方便您清理；否则它会影响仪表盘的变量解析而您看不到。
* 变量的删除、改名、类型变化或候选失效不会反向更新规则。

## 查询入口的字段

| 字段 | 说明 |
| - | - |
| **数据源** | 默认是 `告警事件的数据源`（查询按规则的数据源类型书写），也可以选择一个具体数据源。当前规则的数据源类型不支持查询工作台时，`告警事件的数据源` 一项被禁用并显示 `当前规则类型不支持`，此时入口必须显式指定数据源。**更换数据源会重置查询**（查询语言变了，旧语句没有意义） |
| **查询类型** | 只有多查询类型的数据源才出现这一行（Prometheus：仅图表 / 仅原始；Loki：Range / Instant；VictoriaLogs：原始日志 / 即时统计 / 趋势统计）。Prometheus 的「图表 + 原始」不会出现在这里，因为它对应两次执行，一份查询存不下。SQL 类数据源与 SLS、腾讯云 CLS 都只有一种查询方式，因此没有这一行 |
| **初始查询** | 查询语句编辑器，写法与查询工作台一致，可按数据源类型使用补全。整个表达式按 Go template 渲染，**原样输出，不自动加引号或转义** |
| **查询参数** | 数据源的命名参数，按数据源类型给出（如返回条数、检索方向、最小 step（秒）、SLS 的项目 / 日志库、腾讯云 CLS 的地域 / 日志主题 / 语法）。参数值**不做模板渲染**——key 或 value 里出现 `{{` 会被拒绝（`query args do not support templates`） |

选择了事件数据源时，规则类型不是工作台支持的类型会显示 `请先在「数据源与查询」中选择数据源类型，或为该入口指定数据源`；指定的数据源已被删除或您无权使用时会显示 `所选数据源不可用`。数据源的真实类型、权限与专属限制由工作台在打开或执行时按当前用户重新校验。

## 模板变量

调查入口的模板上下文**只有两个变量**：

| 变量 | 类型 | 说明 |
| - | - | - |
| `$labels` | `map[string]string` | 告警事件的**原始数据标签**。不含规则上配置的附加标签，也不含外部标签增强返回的标签，且不过滤标签名 |
| `$datasource` | `map[string]string` | 事件来源的数据源，固定键：`id`（十进制数据源 ID）、`name`、`type`、`address` |

* 简单标签直接取值：`{{ $labels.service }}`。标签名含点等特殊字符时用 `{{ index $labels "service.name" }}`。
* **访问缺失的标签或 `$datasource` 不存在的键会明确报错**（`index` 访问同理），不会静默产出空字符串——否则会变成一次没有过滤条件的查询。
* 点号（`.`）只表示 `range` / `with` 等局部数据上下文，不代表完整告警事件；`$values`、`$value`、`$annotations`、`$appendLabels` 等[备注描述](/zh/monitors/alert-rules/description-template)里可用的变量在这里都不可用，也不能通过根对象绕过。
* 支持 Go template 的条件、循环、局部变量与内置函数；只渲染**一次**，模板渲染结果里的 `{{ }}` 不会被再次执行。

仪表盘变量示例：

```gotemplate theme={null}
{{ $labels.service_name }}
{{ $datasource.id }}
```

查询语句示例（VictoriaLogs）：

```text theme={null}
event_name:="webhook.attempt.completed"
service:="{{ $labels.service_name }}"
outcome:="failure"
```

**查询表达式自己负责引号与转义。** 模板只产出值本身，`service:="{{ ... }}"` 里的引号是 LogsQL 语法的一部分，必须由表达式自己写。需要转义时请显式使用有固定语义的函数，例如 `replace`（字面量替换）、`regexQuoteMeta`（正则元字符）、`urlquery` / `html` / `js`；系统不按数据源方言自动判断转义方式。渲染失败或渲染结果不满足查询载荷要求时，该入口保留初始模板与错误，**不生成可执行查询、也不执行**。

## 预览跳转

点击入口右侧的眼睛图标打开 **预览调查入口** 弹窗，它按真实事件的快照渲染这个入口，用来在保存前确认跳转是否符合预期。

* 前置条件：**规则必须已经保存**（否则提示 `请先保存规则，产生告警后再预览`），并且该规则**当前有活跃告警**（否则提示 `该规则暂无活跃告警，产生告警后可预览`）。弹窗顶部从该规则的活跃告警里选一条作样本，超过 20 条时可以翻页。
* 预览用的是所选告警的**事件快照**，**不包含表单里尚未保存的修改**；因此要先保存规则、等它产生告警，才能预览新改的配置。
* 弹窗里点入口再打开目标（新页签）。如果这条告警没有与该入口对应的快照，会提示 `该告警中没有与此入口对应的快照，请选择配置生效后产生的告警`；整条告警都没有快照时提示 `该告警没有调查入口快照，请选择配置生效后产生的告警`。

## 校验与限制

| 限制 | 值 | 说明 |
| - | - | - |
| 入口数量 | 最多 **20 个** | 控制台提示 `调查入口最多 20 个`；接口错误为 `investigation_targets must not contain more than 20 items` |
| 配置总量 | 最多 **32 KiB** | 按整个入口列表序列化后的字节数计算。控制台提示 `调查入口配置总量超过 32 KiB，请精简查询或变量模板`；接口错误为 `investigation_targets must not exceed 32768 bytes` |
| 仪表盘入口 | 必须选择仪表盘 | `第 N 个调查入口未选择仪表盘` |
| 查询入口 | 必须填写查询语句 | `第 N 个调查入口未填写查询语句` |
| 查询入口 | 按规则类型无法在工作台查询时，必须显式指定数据源 | `第 N 个调查入口需要指定数据源：当前规则的数据源类型不支持查询工作台` |
| 时间范围 | 两个方向非负，且长度大于 0 | `第 N 个调查入口的时间范围必须大于 0` |
| 调查用途 | 控制台输入框 200 个字符，后端 **≤512 字节** | `第 N 个调查入口的调查用途过长`。200 个中文字符可能超过 512 字节，此时同样会被拦下 |
| 去重 | 不允许重复 | `第 N 个调查入口与第 first 个重复` |

去重的身份判定：

* **仪表盘入口**：同一仪表盘 + 同一定位对象即为重复，**与变量取值、时间范围无关**。重复项不能用来表达变量 fallback 或多实例。
* **查询入口**：按标准化后的数据源、查询（模式、表达式、参数、最小 step）与时间范围判重；未指定数据源（使用事件数据源）作为独立取值参与比较。同一数据源上可以配置多份**不同**的查询。

这些校验同时在两个地方执行：入口弹窗里（只校验当前这一项，方便逐项修复），以及保存规则时（整组校验，错误文案显示在区块下方）。接口侧还会校验仪表盘 ID 与定位对象必须是规范的 UUIDv7、变量名合法、模板语法可解析，以及未知字段会被拒绝。

## 保存时的 Edge 版本要求

调查入口需要 monit-edge **`v0.75.3` 或以上版本**。为了引导升级，版本门控放在**保存时**，事件处理时不检查版本：

* **触发条件**：保存后的规则带有非空入口，并且本次请求显式提交了非空入口，或者在保留原有入口的同时修改了数据源范围（数据源类型、名称通配或精确绑定）。未配置入口、显式传空数组、以及只改其他字段的请求都不检查。
* **检查范围**：解析该规则当前匹配的全部数据源，取其所在 Edge 集群的**活跃实例**。没有任何活跃实例的数据源会被跳过；规则当前没有匹配到任何数据源时直接允许保存。
* **通过条件**：所有被检查实例的版本 ≥ `v0.75.3`。版本无法识别视为不满足。
* **拒绝行为**：不保存任何字段，返回明确的升级错误并列出最低版本，以及不满足的数据源、Edge 集群、实例 IP 与版本（数量有界）。错误信息形如：`investigation_targets require monit-edge v0.75.3 or later on every active instance serving the rule's datasources; upgrade cluster "<集群名>" <实例 IP>:<端口> (v0.75.2)`。
* 该门控覆盖全部写入口：创建、更新、可修改入口或数据源范围的批量字段更新，以及原生 Bundle 与历史 JSON 导入；外部格式（Prometheus、Nightingale 等）导入的规则入口固定为空数组，不受影响。
* 保存之后再出现低版本实例、或 Edge 降级，都**不会**影响已保存的规则；之后再提交入口或修改数据源范围时才会重新检查。

## 快照语义与失败处理

**入口来自事件快照，不来自规则当前配置。** 告警被接受时渲染一次，之后：

* 规则改了入口，**已经接受的告警**（活跃告警详情、故障详情里的排查入口区块）显示的仍是老快照；
* 重复通知或终态事件沿用同一份快照，只把每个入口的窗口按事件时间差整体平移，不重新读取规则；
* 规则被删除也不会移除历史快照——故障侧会显示 `告警规则已被删除，无法生成排查入口`。

**配置生效前产生的告警没有快照。** 在规则保存入口之前就已经产生的告警，详情里会显示 `该告警没有调查入口快照，请选择配置生效后产生的告警`。请用配置生效后新产生的告警验证。

**整条事件渲染失败时不生成快照**，改为携带一个有界错误码：

| 错误码 | 含义 | 界面文案 |
| - | - | - |
| `rule_missing` | 规则已不存在 | 告警规则已不存在，无法生成调查入口 |
| `edge_upgrade_required` | 事件来自不携带数据源 ID 的旧协议（Alert Rule Event v1 及更早） | 上报该事件的 Edge 版本过低，未生成调查入口，请升级 Edge |
| `invalid_config` | 配置结构非法、事件时间无效，或按事件时间计算后的窗口超出可表示范围 | 调查入口配置或事件时间无效，未生成调查入口 |
| `payload_limit` | 渲染结果超过容量上限（快照本身超过 64 KiB） | 调查入口渲染结果超过容量上限，未生成调查入口 |

**单项渲染失败不丢弃入口**：仪表盘变量渲染失败时，该变量保留为未解析并显示 `变量 <名称> 渲染失败：<原因>`；查询语句渲染失败时，该入口不会生成可执行查询、不会执行，并显示 `查询渲染失败，未执行：<原因>`。这类入口仍然列出来，但带一个红色的 `入口异常` 标记，也不给跳转链接。其余入口照常工作。

**权限在目的端重新校验。** 快照的可见性跟随告警事件本身，生成时不按仪表盘分组或数据源权限过滤；真正打开仪表盘或工作台时按**当前用户**重新校验，无权或已删除的目标沿用目的端的报错，不会回退到其他资源。

**投递到 On-call 的快照另有 8 KiB 上限。** 完整快照随告警事件以 `__alert_rule_investigation_context` 标签投递，标签值超过 8 KiB 时整体降级为 `payload_limit`（故障详情显示提示文案，不截断），此时完整的快照仍可在 Monitors 的活跃告警详情中查看。

## 相关页面

<CardGroup cols={2}>
  <Card title="活跃告警" icon="bell" href="/zh/monitors/alert-rules/active-alerts">
    活跃告警详情抽屉里的调查入口区块，按事件快照展示入口。
  </Card>

  <Card title="故障详情 · 排查入口" icon="file-magnifying-glass" href="/zh/on-call/incident/search-view-incident#排查入口">
    故障综合信息面板里的排查入口区块如何渲染快照。
  </Card>

  <Card title="备注描述" icon="text" href="/zh/monitors/alert-rules/description-template">
    告警事件备注里的 Go Template 变量，与调查入口的上下文不同。
  </Card>

  <Card title="告警规则入门" icon="rocket" href="/zh/monitors/quickstart/quickstart">
    告警规则表单六个区块的整体说明。
  </Card>
</CardGroup>


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