跳转到主要内容
通过标准协议推送自有系统告警事件到 Flashduty。
Flashduty 已经适配了大部分常用告警系统的 webhook 协议,对于这些系统您应该首先使用对应的集成,更加简单方便。本集成提供了一个标准的 HTTP 接口,需要您开发适配。好处是您可以推送任何您想进行 oncall 的告警事件。

操作步骤

在 Flashduty

您可通过以下两种方式获取集成推送地址,任选其一即可。
如果您只需将告警发往一个协作空间,选择此方式,配置更简单。
  1. 进入 Flashduty 控制台,选择 协作空间,打开一个协作空间
  2. 选择 配置 → 集成数据 → 专属集成,点击 新增集成
  3. 选择 标准告警事件 集成,点击 保存,生成卡片。
  4. 打开生成的集成卡片,复制 推送地址
如果您需要根据告警事件的 Payload 将告警路由到不同协作空间,选择此方式。
  1. 进入 Flashduty 控制台,选择 集成中心 → 告警事件
  2. 选择 标准告警事件 集成:
    • 集成名称:为当前集成定义一个名称。
  3. 配置默认路由并选择协作空间;创建后可在 路由 中增加更多规则
  4. 点击 保存,复制生成的 推送地址

在您的系统中配置

本集成没有第三方产品界面,配置发生在您自己的系统和 Flashduty 集成设置中。
1

在您的系统中向 Flashduty 推送告警事件

操作路径:您的告警系统 › 发送 HTTP 请求的代码或脚本状态变化时都要推送:触发时推送 Critical / Warning / Info,恢复时推送同一 alert_key 的 Ok 事件,否则告警会一直保持打开。
2

在 Flashduty 中配置字段映射(上游 JSON 格式不符时)

操作路径:Flashduty 控制台 › 集成中心 › 告警事件(专属集成:Flashduty 控制台 › 协作空间 › 配置 › 集成数据 › 专属集成)在右侧集成列表中点开您的标准告警事件集成,进入 接收 › 映射配置 卡片。该卡片的开关位于标题行右侧,默认关闭,开启后才显示映射编辑器,在其中配置 字段映射。您的系统能直接按上文 Payload 推送时,跳过本步。否则在 字段映射 中用 {{变量路径}} 把原始 JSON 的字段映射到标准字段,需要转换取值时再配置 字段值映射(仅在配置字段映射后显示)。语法和示例见下文「字段映射与值映射」。
3

推送测试事件并确认

操作路径:您的系统所在主机的终端
返回 request_id 和 alert_key 即推送成功,回到 Flashduty,集成显示 最新事件时间。再用同一 alert_key、event_status 为 Ok 的事件验证自动恢复。

请求描述

请求方式

POST, Content-Type:“application/json”
请求体不能超过 10 MiB,超出时返回 HTTP 413。

请求参数

Headers

Query Strings

Payload

image 结构体

请求响应

Data: Error: Code:

请求示例

请求:
成功响应:
失败响应:

字段映射与值映射

如果您的系统推送的 JSON 格式无法直接匹配上述标准 Payload 结构,可以在集成设置中配置 字段映射 和 值映射,让 Flashduty 自动将任意格式的 JSON 转换为标准告警事件。
配置字段映射后,请求体不再要求固定格式,可以接收任意 JSON 对象,也支持 JSON 数组批量推送(单次最多 100 条)。

字段映射

使用 {{变量路径}} 语法引用原始 JSON 中的字段,将其映射到标准告警事件的目标字段。 支持的目标字段: 以上为集成设置中字段映射编辑器支持的目标字段白名单。images 字段在控制台字段映射编辑器中不可选,请在请求 Payload 中直接上报。 变量语法:
  • 用 . 分隔路径层级,如 {{data.severity}} 引用嵌套字段
  • 当整个值只有一个变量时(如 "{{tags}}"),会保留原始数据类型(对象、数组等)
  • 当变量与其他文本混合时(如 "{{host}} - {{check}}"),变量会被转为字符串拼接
labels 的两种映射方式:
  • 通配符展开:"labels": "{{tags}}" — 将 tags 对象的所有子字段展开为标签
  • 逐个映射:"labels": {"env": "{{tags.env}}", "host": "{{hostname}}"} — 每个标签单独映射
示例: 您的系统推送格式如下:
配置如下字段映射:

值映射

当源系统的字段值与 Flashduty 标准不一致时(如严重程度使用 high 而非 Critical),可以配置值映射进行自动转换。 值映射按字段路径分组配置,每个路径下是一个 源值 → 目标值 的映射表。 示例:
配合上面的字段映射,原始 JSON 中的 "severity": "high" 会先通过字段映射提取,再通过值映射转换为 Critical,最终写入 event_status 字段。
所有 {{...}} 变量必须能在原始 JSON 中解析到值,否则请求会报错。建议先用少量数据测试映射配置是否正确。

无事件检测

无事件检测 卡片在指定时间内未收到有效事件时,生成一条 Warning 告警。开关位于卡片标题行右侧,默认关闭;关闭时卡片只有一行,不显示其他选项。 开启后显示以下选项:

最佳实践

  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。如果无法访问,请为服务器开通外网,或单独放行 Flashduty 的域名。
  3. 打印 Flashduty 的响应,查看其中的错误信息。
如果完成以上步骤后仍未找到原因,请 携带响应中的 request_id 联系我们。
Flashduty 使用 2 层降噪机制:
  1. 首先对告警 event 进行去重检查,如果您推送的 event 和之前推送的 event 内容完全一致,则新的 event 将被直接丢弃。
  2. 如果新的 event 的状态和描述和其对应的告警的上一条 event 的状态、标题、描述均一致,则新的 event 将被直接丢弃,同时更新归属告警属性。
  3. 新的 event 可能由于匹配到排除、丢弃、抑制或静默规则,而被丢弃。
  4. 当新的 event 触发了新告警,则系统会进入第二层降噪检查,判断新告警是否可以被合并到某个活跃的故障中,如果可以,则只会并入已有的故障,而不会产生新故障。
更多内容请参考 告警降噪。