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

# 引用变量

> 通过引用告警标签、属性，实现对故障的严重程度和标题等信息的定制

## 概述

通过引用告警标签、属性的变量，实现对故障的严重程度、标题和描述等信息的修改与定制。主要应用在两种场景：

<CardGroup cols={2}>
  <Card title="Event API 上报" icon="code">
    通过告警 \[Event API]\(/zh/on-call/integration/alert-integration/alert-sources/standard alert) 上报自定义告警事件时，可以使用 `title_rule` 字段自定义告警的标题。
  </Card>

  <Card title="告警 Pipeline" icon="filter" href="/zh/on-call/integration/alert-integration/alert-pipelines">
    在告警 Pipeline 中引用变量，实现对告警的严重程度、标题和描述等信息的修改。
  </Card>
</CardGroup>

### Event API 示例

```json title_rule theme={null}
{
  "title_rule": "[TPL]${resource} / ${check}"
}
```

<Note>
  指定 `resource` 和 `check` 标签作为告警标题。
</Note>

### 告警 Pipeline 示例

<Frame>
  <img src="https://download.flashcat.cloud/flashduty/doc/zh/fd/bianliang-1.png" alt="在告警 Pipeline 中引用变量" />
</Frame>

## 变量引用方式

### 通过 `${var}` 引用标签

以 `[TPL]` 作为前缀，使用 `${}` 来引用变量，变量内容将从标签中提取，提取不到使用 `<no value>` 替代。

| 规则                            | 标签值                                                  | 生成内容                     |
| ----------------------------- | ---------------------------------------------------- | ------------------------ |
| `[TPL]${resource} / ${check}` | `{"resource": "127.0.0.1", "check": "cpu idle low"}` | 127.0.0.1 / cpu idle low |
| `[TPL]${resource} / ${check}` | `{"resource": "127.0.0.1"}`                          | 127.0.0.1 / `<no value>` |
| `[TPL]${resource} / 主机宕机`     | `{"resource": "127.0.0.1"}`                          | 127.0.0.1 / 主机宕机         |

### 通过 Golang 模版语法引用

以 `[TPL]` 作为前缀，使用 `{{}}` 来引用变量（可以引用标签和属性），标签不存在时返回空字符串。

| 规则                                              | 变量值                                                  | 生成内容                     |
| ----------------------------------------------- | ---------------------------------------------------- | ------------------------ |
| `[TPL]{{.Labels.resource}} / {{.Labels.check}}` | `{"resource": "127.0.0.1", "check": "cpu idle low"}` | 127.0.0.1 / cpu idle low |
| `[TPL]{{.Labels.resource}} / {{.Labels.check}}` | `{"resource": "127.0.0.1"}`                          | 127.0.0.1 /              |
| `[TPL]{{.EventSeverity}} / 主机宕机`                | `{"EventSeverity": "Warning"}`                       | Warning / 主机宕机           |

<Note>
  `${}` 语法和 `{{}}` 语法存在两个关键差异：

  * **取值范围不同**：`${name}` **仅**从 `Labels` 中取值，无法引用属性字段；`{{}}` 以 `*AlertEvent` 整体作为数据源，可访问全部导出属性与 `Labels`。
  * **缺失行为不同**：标签不存在时 `${}` 返回 `<no value>`，`{{}}` 返回空字符串。
</Note>

#### 支持引用的属性列表

使用 `{{}}` 语法时，模板的数据对象即告警事件（`AlertEvent`）本身，可引用的主要字段如下：

| 字段                | 类型     | 说明                                           |
| ----------------- | ------ | -------------------------------------------- |
| `Title`           | string | 告警标题                                         |
| `Description`     | string | 告警描述                                         |
| `EventSeverity`   | string | 严重程度（Critical / Warning / Info）              |
| `EventStatus`     | string | 事件状态（Critical / Warning / Info / Ok，Ok 表示恢复） |
| `AlertKey`        | string | 告警的唯一 Key，用于将同一条曲线的事件合并到同一个告警                |
| `TitleRule`       | string | 上报时指定的标题生成规则                                 |
| `IntegrationType` | string | 集成类型（如 `prometheus`、`zabbix.v5`）             |
| `IntegrationName` | string | 集成名称                                         |
| `Labels`          | map    | 标签键值集合，可通过 `{{.Labels.xxx}}` 访问具体标签          |

<Tip>
  除标题外，**告警描述和任意标签值本身也支持引用变量**：在告警 Pipeline 中使用 `重置描述`（resetDescription）或 `重置标签`（resetLabels）动作时，填入的内容只要以 `[TPL]` 作为前缀，就会按同样的语法执行变量替换。
</Tip>

## 常见问题

<AccordionGroup>
  <Accordion title="使用标签动态生成标题，如果标签不存在怎么办？">
    取决于您使用哪一种变量获取方式，标题可能会保留原始的变量信息或使用 `<no value>` 替代。

    <Tip>
      即使获取不到变量，也不影响告警的生成，您可放心调试。
    </Tip>
  </Accordion>
</AccordionGroup>