> ## 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.

# 标签增强

> 标签增强可在告警接入时自动生成新标签，弥补源数据不足。例如：从描述中提取 IP、将资源 ID 映射为可读名称、组合多个字段生成跳转链接、通过 API 查询外部系统获取动态数据

<Tip>**版本要求**：基础标签增强需要 On-call 标准版及以上订阅，高级标签增强（如 API 映射）需要专业版及以上。[了解更多](https://flashcat.cloud/flashduty/price/)</Tip>

## 核心用途

标签贯穿 Flashduty On-call 的告警处理全流程：

| 场景        | 用途               |
| :-------- | :--------------- |
| **故障筛选**  | 在故障列表按标签快速过滤     |
| **路由分发**  | 根据标签将告警路由到不同协作空间 |
| **分派通知**  | 按标签匹配不同的分派策略     |
| **告警聚合**  | 按标签维度聚合相似告警      |
| **静默/抑制** | 按标签匹配需要静默或抑制的告警  |

## 配置标签增强

进入 集成详情 → **标签增强** → **添加规则**。

### 增强类型

| 类型     | 说明                | 示例                |
| :----- | :---------------- | :---------------- |
| **提取** | 用正则从标题/描述/标签中提取内容 | 从描述中提取 IP 地址      |
| **组合** | 用模板语法拼接新标签        | 组合域名+事件 ID 生成日志链接 |
| **映射** | 通过映射表将值转换为可读名称    | 将资源 ID 映射为资源类型    |
| **删除** | 移除指定标签            | 删除敏感信息标签          |

<Frame>
  <img src="https://docs-cdn.flashcat.cloud/images/png/c833e4ac159c9abaea755bad701d95ac.png" alt="标签增强类型" />
</Frame>

### 配置选项

| 选项       | 说明                                                                  |
| :------- | :------------------------------------------------------------------ |
| **限制条件** | 仅对匹配条件的告警生效，详见[配置过滤条件](/zh/on-call/configuration/filter-conditions) |
| **覆盖**   | 开启后覆盖同名标签，默认关闭                                                      |
| **预览**   | 使用真实告警预览规则效果                                                        |

<Tip>
  多条规则从上到下依次执行。规则不匹配时跳过，不会生成对应标签。
</Tip>

## 配置示例

<Tabs>
  <Tab title="标签提取">
    **场景**：告警事件来自邮件集成，需要从描述信息中提取关键信息作为标签应用到其他场景，比如将描述信息中的 IP 和触发值提取为独立的标签。

    <Steps>
      <Step title="查看告警原文">
        <Frame>
          <img src="https://docs-cdn.flashcat.cloud/images/png/4a335b5d80a1b5a8ea9460668f2a25d7.png" alt="告警原文" />
        </Frame>
      </Step>

      <Step title="配置提取规则">
        <Frame>
          <img src="https://docs-cdn.flashcat.cloud/images/png/eaebc7f494e5b0e955fb381813bace74.png" alt="提取规则配置" />
        </Frame>
      </Step>

      <Step title="验证提取效果">
        <Frame>
          <img src="https://docs-cdn.flashcat.cloud/images/png/33b3f01f2cc7f8b323765b0ed3ee7578.png" alt="提取效果" />
        </Frame>
      </Step>
    </Steps>
  </Tab>

  <Tab title="标签组合">
    **场景**：公司的日志平台可以通过域名+事件ID+时间戳的方式直接访问到日志详情，但告警信息中只有事件ID和时间戳标签，所以需要根据这些信息组合成一个访问地址。

    <Steps>
      <Step title="查看告警原文">
        <Frame>
          <img src="https://docs-cdn.flashcat.cloud/images/png/7b8eccb938993d2867bf3f7860b0788f.png" alt="告警原文" />
        </Frame>
      </Step>

      <Step title="配置组合规则">
        <Frame>
          <img src="https://docs-cdn.flashcat.cloud/images/png/ea29da12647637b5f46667d8205f65b2.png" alt="组合规则配置" />
        </Frame>
      </Step>

      <Step title="验证组合效果">
        <Frame>
          <img src="https://docs-cdn.flashcat.cloud/images/png/7f6cf27203660cbd11ae737ed58a52a4.png" alt="组合效果" />
        </Frame>
      </Step>
    </Steps>
  </Tab>

  <Tab title="标签映射">
    **场景**：当源告警信息中的标签值不固定且不能直观定位其含义时，可以通过映射的方式将源标签映射为新定义的标签和值。

    标签映射支持两种映射方式，在添加映射规则时通过内联单选切换选择 **元数据表** 或 **API**：

    | 映射类型             | 说明                   | 适用场景                          |
    | :--------------- | :------------------- | :---------------------------- |
    | **元数据表（Schema）** | 通过预定义的 CSV 映射表进行静态映射 | 映射关系相对固定，数据量有限                |
    | **API（接口映射）**    | 通过调用外部 API 服务进行动态映射  | 需要查询外部系统（如 mapping api）获取实时数据 |

    <Tabs>
      <Tab title="Schema 映射">
        **示例**：源告警中只有资源类型 ID 信息，希望将每个 ID 对应的资源类型名称也体现出来。

        <Steps>
          <Step title="准备映射表文件">
            准备 CSV 格式的映射表文件，目的是将告警中的资源类型 ID 与实际的资源类型名称进行映射。

            |  ID |   Type   |
            | :-: | :------: |
            |  A  |  server  |
            |  B  |  router  |
            |  C  |  gateway |
            |  D  | database |
            |  E  |    MQ    |
          </Step>

          <Step title="创建映射表">
            1. 进入 `配置中心` → `映射数据` → `元数据表` → `创建映射表`
            2. 填写基本信息，如名称、描述、管理团队等
            3. 在 `映射表数据` 处，上传准备好的 CSV 文件（如果数量较少，创建完成后可以在映射详情页面中编辑添加）
            4. 选择 `源标签`（如 `ID`），选择 `目标标签`（如 `Type`）
            5. 点击 `创建`，完成映射表创建

            <Frame>
              <img src="https://docs-cdn.flashcat.cloud/images/png/95bc8cdf3d3dcb60a52d11cdad4c386b.png" alt="创建映射表" />
            </Frame>
          </Step>

          <Step title="配置映射关系">
            <Frame>
              <img src="https://docs-cdn.flashcat.cloud/images/png/d25e632242d1a37ce9f159cd3b3086d4.png" alt="配置映射关系" />
            </Frame>
          </Step>

          <Step title="验证映射效果">
            **告警原文**：上报的告警信息中只有资源 ID，没有资源类型名称。

            <Frame>
              <img src="https://docs-cdn.flashcat.cloud/images/png/c5e636c149f7125c0bde7e479414e130.png" alt="告警原文" />
            </Frame>

            **映射效果**：通过配置的映射关系，将资源 ID 映射出新的资源类型名称标签。

            <Frame>
              <img src="https://docs-cdn.flashcat.cloud/images/png/8f93f6ae82e76e79196b5bf488663fe8.png" alt="映射效果" />
            </Frame>
          </Step>
        </Steps>
      </Tab>

      <Tab title="API 映射">
        **示例**：需要根据告警中的主机信息从 mapping api 系统查询负责团队、服务等级等动态数据。

        <Steps>
          <Step title="创建映射服务">
            1. 进入 `配置中心` → `映射数据` → `API` → `创建API`
            2. 填写服务配置信息：

            | 配置项    | 说明                      | 示例                                                |
            | :----- | :---------------------- | :------------------------------------------------ |
            | 服务名称   | 服务的可读名称                 | Mapping api 资产查询服务                                |
            | 描述     | 服务用途说明                  | 根据主机 IP 查询资产信息                                    |
            | 请求 URL | API 的请求地址               | `https://mapping-api.example.com/v1/enrich-event` |
            | 请求头    | HTTP 请求头配置              | `X-Auth-Token: your-token`                        |
            | 超时时间   | 请求超时时间，1-3 秒，默认 2 秒     | 1                                                 |
            | 重试次数   | 请求失败后的重试次数，0-1 次，默认 0 次 | 1                                                 |

            <Tip>
              如果 API 使用 HTTPS 且证书不受信任，可开启 `跳过证书验证` 选项。
            </Tip>
          </Step>

          <Step title="配置映射规则">
            在标签增强中添加映射规则，通过单选切换选择映射类型为 `API`：

            1. 选择已创建的映射服务
            2. 配置 `生成标签列表`：指定希望从 API 返回的标签名称，如 `owner_team`、`service_tier`、`host_ip`
            3. 根据需要开启 `覆盖` 选项
          </Step>

          <Step title="验证映射效果">
            当告警触发时，Flashduty 会自动调用配置的 API 服务，将告警事件数据发送给外部系统，并将返回的标签添加到告警中。
          </Step>
        </Steps>
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

## 映射数据管理

### 映射表数据管理

在映射表详情页面中，可以对映射表数据进行管理：

| 功能   | 说明                |
| :--- | :---------------- |
| 数据搜索 | 按照源标签的值进行搜索       |
| 数据添加 | 手动添加映射数据          |
| 数据上传 | 上传新的数据映射表，会覆盖已有数据 |
| 数据下载 | 下载当前映射表数据到本地      |
| 数据展示 | 展示当前映射表数据，可以编辑或删除 |

<Frame>
  <img src="https://docs-cdn.flashcat.cloud/images/png/477563cfc4e3759e8584edd34fa5bf9a.png" alt="映射表数据管理" />
</Frame>

<Tip>
  对于频繁变更的映射关系（如 Mapping api 数据同步），建议使用 API 映射方式，或通过 [Flashduty API](/zh/api-reference/on-call/alert-enrichment/mapping-data-write-upsert) 自动化更新映射表数据。
</Tip>

### 映射服务 API 规范

当使用 API 映射时，您的外部 API 服务需要遵循以下规范：

#### 请求规范

Flashduty 将通过 `POST` 方法调用您的 API，请求体包含以下内容：

```json theme={null}
{
  "result_label_keys": ["owner_team", "service_tier", "host_ip"],
  "event": {
    "account_id": 1,
    "channel_id": 20,
    "data_source_id": 15,
    "data_source_type": "prometheus",
    "description": "CPU usage for instance '10.0.1.1:9100' is over 95%",
    "title": "High CPU Usage on instance 10.0.1.1:9100",
    "alert_key": "d41d8cd98f00b204e9800998ecf8427e",
    "event_severity": "Critical",
    "event_status": "Critical",
    "event_time": 1678886400,
    "labels": {
      "region": "us-east-1",
      "service": "service-A",
      "env": "production",
      "instance": "10.0.1.1:9100"
    }
  }
}
```

| 字段                  | 类型             | 说明                    |
| :------------------ | :------------- | :-------------------- |
| `result_label_keys` | array\[string] | 期望返回的标签名称列表，由用户在规则中配置 |
| `event`             | object         | 当前告警事件的完整信息           |

#### 响应规范

API 需要返回以下格式的 JSON 响应：

**成功响应** (HTTP 200)：

```json theme={null}
{
  "result_labels": {
    "owner_team": "team-database",
    "service_tier": "tier-1",
    "host_ip": "10.0.1.1"
  }
}
```

| 响应码               | 说明                       |
| :---------------- | :----------------------- |
| `200 OK`          | 成功，返回 `result_labels` 对象 |
| `404 Not Found`   | 未找到匹配数据                  |
| `400 Bad Request` | 请求格式错误                   |
| `5xx`             | 服务器内部错误                  |

<Note>
  如果某个请求的标签无法找到对应的值，API **不应**在 `result_labels` 中包含该 key。
</Note>

#### 安全约束

为确保安全性，以下 HTTP Header 被禁止在映射服务中使用：

| 分类    | 禁用 Header                                                                       |
| :---- | :------------------------------------------------------------------------------ |
| 认证与授权 | `authorization`, `proxy-authorization`, `cookie`, `x-api-key`, `x-access-token` |
| IP 伪造 | `x-forwarded-for`, `x-real-ip`, `true-client-ip`, `x-client-ip`                 |
| 主机与路由 | `host`, `x-forwarded-host`, `x-forwarded-proto`, `x-internal-id`, `x-user-id`   |
| 协议相关  | `transfer-encoding`, `upgrade`, `connection`                                    |

<Tip>
  建议使用 `X-Custom-` 或 `X-Enrich-` 前缀的自定义 Header 进行认证。
</Tip>

#### 最佳实践

1. **性能优先**：API 位于告警处理的关键路径，必须保证低延迟（建议 \< 1s）
2. **实现缓存**：对于相同的查询条件，建议实现缓存以提高性能
3. **幂等设计**：对于同一个事件，多次调用应返回相同的结果
4. **安全认证**：API 必须通过认证机制保护，防止未授权访问

## 延伸阅读

<CardGroup cols={2}>
  <Card title="配置分派策略" icon="paper-plane" href="/zh/on-call/channel/escalation-rule">
    使用标签匹配分派条件
  </Card>

  <Card title="配置告警降噪" icon="volume-slash" href="/zh/on-call/channel/noise-reduction">
    使用标签作为聚合维度
  </Card>

  <Card title="配置过滤条件" icon="filter" href="/zh/on-call/configuration/filter-conditions">
    了解标签匹配语法
  </Card>

  <Card title="配置路由规则" icon="route" href="/zh/on-call/integration/alert-integration/routing-rules">
    将告警分发到不同协作空间
  </Card>
</CardGroup>