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

# 自定义操作

> 配置自定义操作，当故障发生特定操作时，系统通过 HTTP 回调您配置的地址

配置故障 自定义操作，允许您在故障排查期间，快速调用外部接口，实现故障自愈、信息丰富等任何自定义操作。

## 一、创建操作

1. 登录 Flashduty 控制台，进入【集成中心-Webhook】
2. 点击添加 自定义操作 集成
3. 配置 操作名称，此名称将以按钮的形式体现在故障详情中
4. 配置 协作空间，可以配置多个，但每个协作空间至多添加三个 自定义操作
5. 配置 Endpoint、自定义 Headers
6. 保存，完成

## 二、推送描述

### 请求方式

<div class="md-block">
  POST, Content-Type:"application/json"
</div>

### 请求 Payload：

<div class="md-block">
  |      字段     |           类型          |  必含 | 释义                                   |
  | :---------: | :-------------------: | :-: | :----------------------------------- |
  | event\_time |         int64         |  是  | 事件发生`毫秒时间戳`                          |
  | event\_type |         string        |  是  | 事件类型，固定值`i_custom`                   |
  |  event\_id  |         string        |  是  | 事件 ID，`同一个事件可能因为超时等原因重试多次，接收方需要能够去重` |
  |    person   |   [Person](#Person)   |  否  | 操作人，仅人为动作时存在                         |
  |   incident  | [Incident](#Incident) |  是  | 故障详情                                 |

  <span id="Person" />

  **Person**:

  |      字段      |   类型   |  必含 | 释义    |
  | :----------: | :----: | :-: | :---- |
  |  person\_id  |  int64 |  是  | 人员 ID |
  | person\_name | string |  是  | 人员名称  |
  |     email    | string |  是  | 邮件地址  |

  <span id="Responder" />

  **Responder**:

  |        字段        |   类型   |  必含 | 释义    |
  | :--------------: | :----: | :-: | :---- |
  |    person\_id    |  int64 |  是  | 人员 ID |
  |   person\_name   | string |  是  | 人员名称  |
  |       email      | string |  是  | 邮件地址  |
  |   assigned\_at   |  int64 |  否  | 分派时间  |
  | acknowledged\_at |  int64 |  否  | 认领时间  |

  <span id="Incident" />

  **Incident**:

  |         字段         |             类型             |  必含 | 释义                                                                                    |
  | :----------------: | :------------------------: | :-: | :------------------------------------------------------------------------------------ |
  |    incident\_id    |           string           |  是  | 故障 ID                                                                                 |
  |        title       |           string           |  是  | 故障标题                                                                                  |
  |     description    |           string           |  否  | 故障描述                                                                                  |
  |       impact       |           string           |  否  | 故障影响                                                                                  |
  |     root\_cause    |           string           |  否  | 故障根本原因                                                                                |
  |     resolution     |           string           |  否  | 故障解决办法                                                                                |
  | incident\_severity |           string           |  是  | 严重程度，枚举值：Critical，Warning，Info                                                        |
  |  incident\_status  |           string           |  是  | 故障状态，枚举值：Critical，Warning，Info，Ok                                                     |
  |      progress      |           string           |  是  | 处理进度，枚举值：Triggered，Processing，Closed                                                  |
  |     created\_at    |            int64           |  是  | 创建时间                                                                                  |
  |     updated\_at    |            int64           |  是  | 更新时间                                                                                  |
  |     start\_time    |            int64           |  是  | 触发时间，Unix 秒时间戳                                                                        |
  |     last\_time     |            int64           |  否  | 最新事件时间，关联告警中的最新事件推送时间，Unix 秒时间戳，默认为 0                                                 |
  |      end\_time     |            int64           |  否  | 恢复时间，关联的告警全部恢复时，故障也会自动恢复，Unix 秒时间戳，默认为 0                                              |
  |      ack\_time     |            int64           |  否  | 首次认领时间，故障可被多人认领，此时间为最早的认领时间。Unix 秒时间戳，默认为 0                                           |
  |     close\_time    |            int64           |  否  | 关闭时间，end\_time代表故障恢复时间，close\_time代表处理进度的关闭时间，故障恢复时会同时关闭，故障关闭时不影响故障恢复。Unix 秒时间戳，默认为 0 |
  |   snoozed\_before  |            int64           |  否  | 暂缓截止时间                                                                                |
  |       labels       |     map\[string]string     |  否  | 标签 KV，Key 和 Value 均为字符串。手动创建时无此信息，自动创建时为聚合的第一条告警的标签信息                                 |
  |       fields       |   map\[string]interface{}  |  否  | 自定义字段 KV，Key 为字符串，Value 可能为任意类型，取决于字段类型                                               |
  |       creator      |      [Person](#Person)     |  否  | 创建人员信息，仅手动创建故障时存在                                                                     |
  |       closer       |      [Person](#Person)     |  否  | 关闭人员信息，仅手动关闭故障时存在                                                                     |
  |     responders     | \[][Responder](#Responder) |  否  | 处理人员信息列表                                                                              |
  |       alerts       |       [Alert](#Alert)      |  否  | 关联告警                                                                                  |
  |     alert\_cnt     |            int64           |  否  | 关联告警个数                                                                                |
  |     channel\_id    |            int64           |  否  | 协作空间ID，为0代表不属于任何空间                                                                    |
  |    channel\_name   |           string           |  否  | 协作空间名称                                                                                |
  |     detail\_url    |           string           |  是  | 详情地址                                                                                  |
  |    group\_method   |           string           |  否  | 聚合方式，枚举值：n：不聚合，p：按规则聚合，i：智能聚合                                                         |

  <span id="Alert" />

  **Alert**:

  |        字段        |         类型         |  必含 | 释义                                                      |
  | :--------------: | :----------------: | :-: | :------------------------------------------------------ |
  |     alert\_id    |       string       |  是  | 告警 ID                                                   |
  | data\_source\_id |        int64       |  是  | 集成 ID                                                   |
  |       title      |       string       |  是  | 告警标题                                                    |
  |    description   |       string       |  否  | 告警描述                                                    |
  |    alert\_key    |       string       |  是  | 告警关联依据                                                  |
  |  alert\_severity |       string       |  是  | 严重程度，枚举值：Critical，Warning，Info                          |
  |   alert\_status  |       string       |  是  | 告警状态，枚举值：Critical，Warning，Info，Ok                       |
  |     progress     |       string       |  是  | 处理进度，枚举值：Triggered，Closed                               |
  |    created\_at   |        int64       |  是  | 创建时间                                                    |
  |    updated\_at   |        int64       |  是  | 更新时间                                                    |
  |    start\_time   |        int64       |  是  | 首次触发时间（平台接收到的首个事件的时间），Unix 秒时间戳                         |
  |    last\_time    |        int64       |  是  | 最新事件时间（平台接收到的最新事件时间），Unix 秒时间戳                          |
  |     end\_time    |        int64       |  否  | 告警恢复时间（平台上一次接收到结束类型事件的时间），Unix 秒时间戳，默认为 0               |
  |    close\_time   |        int64       |  否  | 关闭时间，不同于 end\_time，这个是处理进度的关闭，不代表告警真的恢复。Unix 秒时间戳，默认为 0 |
  |      labels      | map\[string]string |  否  | 标签 KV，Key 和 Value 均为字符串                                 |
</div>

### 请求响应

HTTP status code 为 200，认为推送成功。

### 请求示例

```
curl -X POST 'https://example.com/incident/action?a=a' \
-H 'Content-Type: application/json' \
-H 'X-Customize-Header-A: a' \
-d '{
    "event_time": 1700208013988,
    "event_type": "i_custom",
    "incident": {
        "event_id":"fac0599a2a25529ba2362c0c184b6cfb",
        "account_id": 74058170041504,
        "account_name": "头铁科技",
        "ack_time": 0,
        "alert_cnt": 1,
        "alerts": [
            {
                "account_id": 74058170041504,
                "alert_id": "6551f37f8713372ad1054d54",
                "alert_key": "asdflasdfl2xzasd112621",
                "alert_severity": "Critical",
                "alert_status": "Critical",
                "close_time": 0,
                "created_at": 1699869567,
                "data_source_id": 2398086111504,
                "description": "cpu.idle < 20%",
                "end_time": 0,
                "event_cnt": 0,
                "labels": {
                    "a": "a",
                    "check": "自定义字段测试",
                    "cluster": "nj",
                    "metric": "node_cpu_seconds_total",
                    "resource": "es.nj.01",
                    "service": "engine",
                    "v": "v"
                },
                "last_time": 1699869562,
                "progress": "Triggered",
                "responder_email": "",
                "responder_id": 0,
                "responder_name": "",
                "start_time": 1699869562,
                "title": "nj / es.nj.01 - 自定义字段测试",
                "title_rule": "$cluster::$resource::$check",
                "updated_at": 1699869576
            }
        ],
        "assigned_to": {
            "assigned_at": 1699869576,
            "escalate_rule_id": "6509344bc1d50d723ca04986",
            "escalate_rule_name": "策略5",
            "id": "VobpBqvTuXgQ7BZzJ2Qu94",
            "layer_idx": 0,
            "type": "assign"
        },
        "channel_id": 1973372625504,
        "channel_name": "lim_test",
        "close_time": 0,
        "created_at": 1699869576,
        "data_source_id": 2398086111504,
        "dedup_key": "asdflasdfl2xzasd112621",
        "description": "cpu.idle < 20%",
        "detail_url": "http://10.206.0.17:8567/incident/detail/6551f3888713372ad1054d57",
        "end_time": 0,
        "equals_md5": "",
        "fields": {
            "impacted_services": [
                "passport",
                "order"
            ],
            "priority": "P3"
        },
        "group_method": "p",
        "impact": "",
        "incident_id": "6551f3888713372ad1054d57",
        "incident_severity": "Critical",
        "incident_status": "Critical",
        "labels": {
            "a": "a",
            "check": "自定义字段测试",
            "cluster": "nj",
            "metric": "node_cpu_seconds_total",
            "resource": "es.nj.01",
            "service": "engine",
            "v": "v"
        },
        "creator":{
            "email":"toutie@flashcat.cloud",
            "person_id":1552048792504,
            "person_name":"头铁"
        },
        "last_time": 1699869562,
        "num": "054D57",
        "progress": "Triggered",
        "resolution": "",
        "responders": [
            {
                "acknowledged_at": 0,
                "assigned_at": 1699869576,
                "email": "zhangsan@toutie.com",
                "person_id": 1234648032504,
                "person_name": "zhangsan"
            }
        ],
        "root_cause": "",
        "snoozed_before": 0,
        "start_time": 1699869562,
        "title": "nj / es.nj.01 - 自定义字段测试",
        "updated_at": 1699929113
    },
    "person": {
        "email": "zhangsan@toutie.com",
        "person_id": 1999632289504,
        "person_name": "zhangsan"
    }
}' -v
```

## 三、使用场景

### 重启主机

当主机内存或CPU打满，触发主机重启脚本，快速完成主机重启。

### 信息丰富

当故障发生时，回调您的服务，根据告警详情调取 Tracing、Logging、拓扑等信息，主动调用 Flashduty Open API 来更新故障信息，比如增加标签或设定自定义字段，辅助排障。

### 回滚变更

当发生故障时，如果确定故障由变更导致，可以直接触发回调到您的部署平台，开启回滚进程，加速故障恢复。

### 更新 status page

当确定故障影响到线上服务，可以触发外部 status page 更新，及时的通知到您的客户或上下游。

## 四、常见问题

1. **服务是否有响应超时时间？**

   * 服务需要在 2 秒内返回响应，超过 2 秒则认为响应失败

2. **推送失败后是否会持续推送？**

针对特定的网络错误，会进行重试，最多重试1次:

* context deadline exceeded (排除 awaiting headers)
* i/o timeout
* eof

2. **推送来源可信 IP 白名单？**
   * {ip_whitelist}
   * 未来可能会更新，请定期查验