自定义事件集成 - Flashduty帮助文档

通过标准 API 推送自有系统告警事件到快猫星云，实现告警事件自动化降噪处理。

请求描述

推送地址

POST https://api.flashcat.cloud/event/push/alert/standard

请求参数：

Headers:

字段	必含	类型	释义
Content-Type	是	string	固定值：`application/json`。

QueryStrings:

字段	必含	类型	释义
integration_key	是	string	集成秘钥，用于访问控制。添加集成后获得。

Payload:

字段	必含	类型	释义
title	是	string	告警标题，不超过512个字符，超出后将自动截断。 `高级用法`：您可根据标签动态生成标题，规则如下：`$a::b::$c`： 1. 用`::`分割子串； 2. 每一个子串可以是一个固定字符串或用`$`作为前缀的变量； 3. 变量内容将从 labels 参数中提取，提取不到将保持原样。
event_status	是	string	告警状态。枚举值（`首字母大写`）：Critical：严重，Warning：警告，Info：提醒，Ok：恢复。
alert_key	是	string	告警合并依据，用于关联同一个告警的发生与恢复。不超过255个字符。
event_time	否	int64	告警 event 发生时间戳，单位“秒”；如果不传，则使用当前时间。
description	否	string	告警描述，不超过 2048 个字符，超出后将自动截断。
resource	否	string	告警对象，该值将覆盖存储在 labels 中。示例值："171.26.23.22"，"flashduty-01.bj"，"/login/health"，"db_order"。
check	否	string	告警检查项，该值将覆盖存储在 labels 中。示例值："cpu idle < 10%"，"api latency > 500ms"，"xxxx domain is down"。
labels	否	map	告警标签集合，key 为标签名称，value 为标签值： 1. 标签的 key 和 value 均为 string 类型，区分大小写。 2. 标签的 key 不要超过 128 个字符，value 不超过 2048 个字符，超出后将自动截断。 3. 至多传入 50 个标签。`标签内容参考`最佳实践
links	否	[]Link	相关链接列表，一般为源告警系统告警详情地址
images	否	[]Image	图片列表，一般为告警产生原因截图

Link:

字段	必含	类型	释义
href	是	string	链接地址
text	否	string	链接描述

Image:

字段	必含	类型	释义
src	是	string	图片渲染地址，必须是可访问的https协议地址
href	否	string	点击跳转地址
alt	否	string	图片描述

请求响应

字段名称	必选	类型	描述
request_id	是	string	请求 ID，用于链路追踪
error	否	Error	错误描述，仅当出现错误时返回
data	否	interface{}	数据内容，可能为任何格式，具体参考 API 定义

Error:

字段名称	必选	类型	描述
code	是	string	错误码，枚举值参考 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 'https://api.flashcat.cloud/event/push/alert/standard?integration_key=$key' \
-H 'Content-Type: application/json' \
-d '{
    "event_status": "Warning",
    "alert_key": "64f6b9df2007be4b0bfe56f6",
    "description": "cpu idle low than 20%",
    "title_rule": "$cluster::$resource::$check",
    "resource":"es.nj.01",
    "check":"cpu.idle<20%",
    "labels": {
        "service": "engine",
        "cluster":"nj",
        "metric":"node_cpu_seconds_total"
    }
}' -v

成功响应：

{
    "request_id": "0ace00116215ab4ca0ec5244b8fc54b0"
}

失败响应：

{
    "request_id": "0ace00116215abc0ba4e52449bd305b0",
    "error": {
        "code": "InvalidParameter",
        "message": "integration_key is not a valid one"
    }
}

最佳实践

当告警状态发生变更时，向快猫星云发送事件
当告警恢复时，发送一个 status 为 Ok 的事件，来关闭告警。否则，告警将一直处于打开状态。如果您的告警系统没有恢复事件，建议您手动发送恢复事件
标签是事件的描述，应尽量丰富标签内容（发送时指定，或者通过配置 enrichment 规则来生成新的标签），比如：
- 告警的发生来源，如 host，cluster，check 或 metric 等
- 告警的归属信息，如 team，owner 等
- 告警的类别信息，如 class（api，db，net）