> ## 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.
# 标准告警事件
> 通过标准协议推送自有系统告警事件到 Flashduty，实现告警事件自动化降噪处理。
通过标准协议推送自有系统告警事件到 Flashduty，实现告警事件自动化降噪处理。
Flashduty 已经适配了大部分常用告警系统的 webhook 协议，对于这些系统您应该首先使用对应的集成，更加简单方便。本集成提供了一个标准的 HTTP 接口，需要您开发适配。好处是您可以推送任何你想进行oncall的告警事件。
## 操作步骤
***
### 在 Flashduty
您可通过以下2种方式，获取一个集成推送地址，任选其一即可。
当您不需要将告警事件路由到不同的协作空间，优先选择此方式，更简单。
1. 进入 Flashduty 控制台，选择 **协作空间**，进入某个空间的详情页面
2. 选择 **集成数据** tab，点击 **添加一个集成**，进入添加集成页面
3. 选择 **标准告警事件** 集成，点击 **保存**，生成卡片。
4. 点击生成的卡片，可以查看到 **推送地址**，复制备用，完成。
当您需要根据告警事件的 Payload 信息，将告警路由到不同的协作空间，优先选择此方式。
1. 进入 Flashduty 控制台，选择 **集成中心=>告警事件**，进入集成选择页面。
2. 选择 **标准告警事件** 集成：
* **集成名称**：为当前集成定义一个名称。
3. 配置默认路由，并选择对应的协作空间（集成创建后可以前往 `路由` 进行更多路由规则的配置）。
4. 点击 **保存** 后，复制当前页面的新生成的 **推送地址** 备用。
5. 完成。
POST, Content-Type:"application/json"
### 请求参数：
#### Headers:
| 字段 | 必含 | 类型 | 释义 |
| :----------: | :-: | :----: | :---------------------- |
| Content-Type | 是 | string | 固定值：`application/json`。 |
#### Query Strings:
| 字段 | 必含 | 类型 | 释义 |
| :--------------: | :-: | :----: | :------------------- |
| integration\_key | 是 | string | 集成秘钥，用于访问控制。添加集成后获得。 |
#### Payload:
| 字段 | 必含 | 类型 | 释义 |
| :-----------: | :-: | :----------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| title\_rule | 是 | string | 告警标题，不超过`512`个字符，超出后将自动截断。支持根据告警内容动态生成标题，生成规则请参考 [定制故障标题](https://docs.flashcat.cloud/zh/on-call/integration/alert-integration/alert-pipelines)。 |
| event\_status | 是 | string | 告警状态。枚举值（`首字母大写`）：*Critical*：严重，*Warning*：警告，*Info*：提醒，*Ok*：恢复。当指定为Ok时，意味着对告警进行自动恢复。 |
| alert\_key | 否 | string | 告警标识，用于对已经存在的告警进行更新或自动恢复。您可以自定义此值，但不可超过`255`个字符。您也可以依赖系统自动生成，该值会在响应中返回。如果您上报的是恢复事件，则此值必须存在。 |
| description | 否 | string | 告警描述，不超过`2048`个字符，超出后将自动截断。 |
| labels | 否 | map | 告警标签集合，key 为标签名称，value 为标签值。1. 标签的 key 和 value 均为 string 类型，区分大小写。2. 标签的 key 不要超过`128`个字符，遵循Prometheus标签命名规范。value 不超过`2048`个字符，超出后将自动截断。3. 至多传入`50`个标签。`标签内容参考`[最佳实践](#最佳实践)。示例："resource": "171.26.23.22", "check": "api latency > 500ms" |
| images | 否 | \[][image](#image) | 图片数组，可用于前端或飞书和钉钉应用通知的图片展示。系统根据 alt 进行合并覆盖，相同(包括空字符)的alt只保留一条 |
#### image 结构体
| 字段 | 必含 | 类型 | 释义 |
| :--: | :-: | :----: | :------------------------------------------------------------------------------------------------------------------------------------------- |
| alt | 否 | string | 图片的替代文本, 长度限制 128 字符，超长截断。 |
| src | 是 | string | 图片来源，值：http/https 开头的图片链接地址 或 [图片上传接口](/zh/on-call/integration/alert-integration/alert-sources/image-upload)返回的image\_key，长度限制 256 字符，超长会被丢弃 |
| href | 否 | string | 超链接引用路径，长度限制 256 字符，超长截断 |
### 请求响应
| 字段名称 | 必选 | 类型 | 描述 |
| :---------: | :-: | :-------------: | :------------- |
| request\_id | 是 | string | 请求 ID，用于链路追踪 |
| error | 否 | [Error](#Error) | 错误描述，仅当出现错误时返回 |
| data | 否 | [Data](#Data) | 上报信息 |
Data:
| 字段名称 | 必选 | 类型 | 描述 |
| :--------: | :-: | :----: | :---------------------------------------------------------- |
| alert\_key | 否 | string | 告警标识，可依据此值上报恢复事件。如果您上报事件时，已经指定了 alert\_key，则此值不变。否则，系统自动生成。 |
Error:
| 字段名称 | 必选 | 类型 | 描述 |
| :-----: | :-: | :----: | :---------------------- |
| code | 是 | string | 错误码，枚举值参考 [Code](#Code) |
| message | 否 | string | 错误描述 |
Code:
| 错误码 | HTTP Status | 描述 |
| :------------------: | :---------: | ------------------------------ |
| InvalidParameter | 400 | 参数错误 |
| InvalidContentType | 400 | Conten-Type 不支持 |
| MethodNotAllowed | 400 | HTTP Method 不支持 |
| Unauthorized | 401 | 登录认证未通过 |
| AccessDenied | 403 | 权限认证未通过 |
| RequestTooFrequently | 429 | 请求过于频繁 |
| RouteNotFound | 404 | 请求 Method+Path 未匹配 |
| ResourceNotFound | 400 | 账户未购买资源，先前往费用中心线操作下单 |
| NoLicense | 400 | 账户无充足订阅 License，先前往费用中心升级或购买订阅 |
| InternalError | 500 | 内部或未知错误 |
### 二、请求示例
***
请求：
```
curl -X POST '{api_host}/event/push/alert/standard?integration_key={integration_key}' \
-H 'Content-Type: application/json' \
-d '{
"event_status": "Warning",
"title_rule": "cpu idle low than 20%",
"labels": {
"service": "engine",
"cluster":"nj",
"resource":"es.nj.01",
"check":"cpu.idle<20%",
"metric":"node_cpu_seconds_total"
}
}' -v
```
成功响应：
```
{
"request_id": "0ace00116215ab4ca0ec5244b8fc54b0",
"data": {
"alert_key": "9qJ798NJoXS4UMVB5SHsNj"
}
}
```
失败响应：
```
{
"request_id": "0ace00116215abc0ba4e52449bd305b0",
"error": {
"code": "InvalidParameter",
"message": "integration_key is not a valid one"
}
}
```
## 三、字段映射与值映射
***
如果您的系统推送的 JSON 格式无法直接匹配上述标准 Payload 结构，可以在集成设置中配置 **字段映射** 和 **值映射**，让 Flashduty 自动将任意格式的 JSON 转换为标准告警事件。
配置字段映射后，请求体不再要求固定格式，可以接收任意 JSON 对象，也支持 JSON 数组批量推送（单次最多 100 条）。
### 字段映射
使用 `{{变量路径}}` 语法引用原始 JSON 中的字段，将其映射到标准告警事件的目标字段。
支持的目标字段：
| 目标字段 | 说明 |
| :------------ | :----------------------------------- |
| title | 告警标题 |
| title\_rule | 告警标题规则 |
| description | 告警描述 |
| event\_status | 告警状态（Critical / Warning / Info / Ok） |
| alert\_key | 告警标识 |
| labels | 告警标签 |
| images | 图片数组 |
**变量语法：**
* 用 `.` 分隔路径层级，如 `{{data.severity}}` 引用嵌套字段
* 当整个值只有一个变量时（如 `"{{tags}}"`），会保留原始数据类型（对象、数组等）
* 当变量与其他文本混合时（如 `"{{host}} - {{check}}"`），变量会被转为字符串拼接
**labels 的两种映射方式：**
* **通配符展开**：`"labels": "{{tags}}"` — 将 `tags` 对象的所有子字段展开为标签
* **逐个映射**：`"labels": {"env": "{{tags.env}}", "host": "{{hostname}}"}` — 每个标签单独映射
**示例：**
您的系统推送格式如下：
```json theme={null}
{
"alert_name": "CPU usage high",
"status": "firing",
"severity": "high",
"host": "web-01",
"tags": {
"env": "production",
"service": "api"
}
}
```
配置如下字段映射：
```json theme={null}
{
"title_rule": "{{alert_name}}",
"event_status": "{{severity}}",
"alert_key": "{{host}}::{{alert_name}}",
"description": "Host {{host}} alert: {{alert_name}}",
"labels": "{{tags}}"
}
```
### 值映射
当源系统的字段值与 Flashduty 标准不一致时（如严重程度使用 `high` 而非 `Critical`），可以配置值映射进行自动转换。
值映射按**字段路径**分组配置，每个路径下是一个 `源值 → 目标值` 的映射表。
**示例：**
```json theme={null}
{
"severity": {
"high": "Critical",
"medium": "Warning",
"low": "Info",
"resolved": "Ok"
}
}
```
配合上面的字段映射，原始 JSON 中的 `"severity": "high"` 会先通过字段映射提取，再通过值映射转换为 `Critical`，最终写入 `event_status` 字段。
所有 `{{...}}` 变量必须能在原始 JSON 中解析到值，否则请求会报错。建议先用少量数据测试映射配置是否正确。
## 四、最佳实践
***
1. 当告警状态发生变更时，向 Flashduty发送事件
2. 当告警恢复时，发送一个 status 为 Ok 的事件，来关闭告警。否则，告警将一直处于打开状态。如果您的告警系统没有恢复事件，建议您手动发送恢复事件
3. 标签是事件的描述，应尽量丰富标签内容（发送时指定，或者通过配置 enrichment 规则来生成新的标签），比如：
* 告警的发生来源，如 host，cluster，check 或 metric 等
* 告警的归属信息，如 team，owner 等
* 告警的类别信息，如 class（api，db，net）
## 五、常见问题
***
**在 Flashduty**
1. 查看集成是否展示了 **最新事件时间**？如果没有，代表Flashduty没有收到推送，直接优先您的系统。
2. 如果您使用的是 **共享集成**，优先确认您是否配置了 **路由规则**。不设置路由规则，系统会直接拒绝新的推送，因为没有协作空间可以承接您的告警。这种情况下，直接配置路由规则到您期望的空间即可。
**在您的系统**
1. 确认您请求的地址，和集成详情中的地址完全一致。
2. 确认您的服务可以访问外网 api.flashcat.cloud 域名。如果不可以，您首先需要为 server 开通外网，或单独针对 Flashduty 的域名开通外网访问。
3. 打印 Flashduty 服务的响应结果，查看是否有明确信息。
如果以上步骤执行之后，仍然没有查询到问题根因，请 **携带请求响应中的 request\_id** 联系我们。
Flashduty 使用2层降噪机制：
1. 首先对告警event进行去重检查，如果您推送的event和之前推送的event内容完全一致，则新的event将被直接丢弃。
2. 如果新的event的状态和描述和其对应的告警的上一条event的状态、标题、描述均一致，则新的event将被直接丢弃，同时更新归属告警属性。
3. 新的event可能由于匹配到排除、丢弃、抑制或静默规则，而被丢弃。
4. 当新的event触发了新告警，则系统会进入第二层降噪检查，判断新告警是否可以被合并到某个活跃的故障中，如果可以，则只会并入已有的故障，而不会产生新故障。
更多内容请参考 [告警降噪](/zh/on-call/channel/noise-reduction)。