> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashduty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Honeycomb 告警集成

> 通过 Webhook 接收方的自定义 Payload 模板，将 Honeycomb Trigger 和 SLO Burn Alert 的触发与恢复同步到 Flashduty On-call。

通过 Honeycomb 的 Webhook 接收方将 Trigger 告警和 SLO Burn Alert 同步到 Flashduty On-call。Honeycomb 用 `.Alert.InstanceID` 标识一次告警触发，Flashduty 用它作为 Alert Key：同一次触发的告警通知和恢复通知会更新同一条 Flashduty 告警。

<div className="hide">
  ## 在 Flashduty On-call

  ***

  您可通过以下两种方式获取集成推送地址，任选其一即可。

  ### 使用专属集成

  1. 进入 Flashduty 控制台，选择 **协作空间**，打开一个协作空间
  2. 选择 **配置** → **集成数据** → **专属集成**，点击 **新增一个集成**
  3. 选择 **Honeycomb**，点击 **保存**
  4. 打开生成的集成卡片，复制 **推送地址**

  ### 使用共享集成

  1. 进入 Flashduty 控制台，选择 **集成中心 → 告警事件**
  2. 选择 **Honeycomb**，填写集成名称
  3. 配置默认路由并选择协作空间；创建后可在 **路由** 中增加更多规则
  4. 点击 **保存**，复制生成的 **推送地址**
</div>

## 在 Honeycomb 中配置

***

以下步骤需要能编辑 **Team Settings** 中集成的 Honeycomb 账号。Trigger 在所有套餐中可用；SLO 和 Burn Alert 需要 Pro 或 Enterprise 套餐。

<Steps>
  <Step title="创建 Webhook 接收方">
    1. 进入 **Team Settings**，打开 **Integrations** 页面
    2. 在 **Trigger and SLO Recipients** 中点击 **Add Integration**，**Provider** 选择 **Webhook**
    3. **Name** 填写 `Flashduty`，**Webhook URL** 粘贴 Flashduty 集成的完整推送地址；**Shared Secret** 可以留空
  </Step>

  <Step title="定义 severity 变量">
    打开 **Variables** 页签，点击 **Add variable**，名称填写 `severity`，默认值填写 `critical`。

    Flashduty 用这个变量确定告警等级，可选值为 `critical`、`warning`、`info`。之后在 Trigger 或 Burn Alert 中选择这个接收方时，可以为单条规则覆盖默认值。
  </Step>

  <Step title="配置 Payload 模板">
    打开 **Payload** 页签，为三种告警类型分别点击 **Enable**，粘贴对应的模板。只启用了部分类型时，未启用的类型不能选择这个接收方。

    **Triggers**：

    ```json theme={null}
    {
      "alert_type": "trigger",
      "id": {{ toJson .ID }},
      "name": {{ toJson .Name }},
      "description": {{ toJson .Description }},
      "url": {{ toJson .URL }},
      "environment": {{ toJson .Environment }},
      "datasets": {{ toJson .Datasets }},
      "severity": {{ toJson .Vars.severity }},
      "status": {{ toJson .Alert.Status }},
      "instance_id": {{ toJson .Alert.InstanceID }},
      "alert_description": {{ toJson .Alert.Description }},
      "is_test": {{ .Alert.IsTest }},
      "investigate_url": {{ toJson .Alert.InvestigateURL }},
      "result_url": {{ toJson .Result.URL }}
    }
    ```

    **Budget Rate Burn Alerts**：

    ```json theme={null}
    {
      "alert_type": "slo_budget_rate",
      "id": {{ toJson .ID }},
      "name": {{ toJson .Name }},
      "description": {{ toJson .Description }},
      "url": {{ toJson .URL }},
      "environment": {{ toJson .Environment }},
      "datasets": {{ toJson .Datasets }},
      "severity": {{ toJson .Vars.severity }},
      "status": {{ toJson .Alert.Status }},
      "instance_id": {{ toJson .Alert.InstanceID }},
      "alert_description": {{ toJson .Alert.Description }},
      "is_test": {{ .Alert.IsTest }},
      "investigate_url": {{ toJson .Alert.InvestigateURL }},
      "slo_id": {{ toJson .SLO.ID }},
      "slo_url": {{ toJson .SLO.URL }}
    }
    ```

    **Exhaustion Time Burn Alerts**：

    ```json theme={null}
    {
      "alert_type": "slo_exhaustion_time",
      "id": {{ toJson .ID }},
      "name": {{ toJson .Name }},
      "description": {{ toJson .Description }},
      "url": {{ toJson .URL }},
      "environment": {{ toJson .Environment }},
      "datasets": {{ toJson .Datasets }},
      "severity": {{ toJson .Vars.severity }},
      "status": {{ toJson .Alert.Status }},
      "instance_id": {{ toJson .Alert.InstanceID }},
      "alert_description": {{ toJson .Alert.Description }},
      "is_test": {{ .Alert.IsTest }},
      "investigate_url": {{ toJson .Alert.InvestigateURL }},
      "slo_id": {{ toJson .SLO.ID }},
      "slo_url": {{ toJson .SLO.URL }}
    }
    ```

    完成后点击 **Add**。

    <Warning>
      请保留 `instance_id`、`status` 和 `is_test`。缺少 `instance_id` 时 Flashduty 会拒绝请求，因为无法把恢复关联到原告警；`status` 只接受 `TRIGGERED` 和 `OK`。模板中的字符串都用 `toJson` 输出，名称或描述里有引号、换行时渲染结果仍是有效 JSON。
    </Warning>
  </Step>

  <Step title="将接收方添加到 Trigger">
    1. 打开 **Triggers**，编辑已有 Trigger 或点击 **New Trigger**
    2. 在 **Recipients** 中点击 **Add Recipient**，选择 `Flashduty` 接收方；需要其他告警等级时，在变量行中覆盖 `severity`
    3. **Frequency of Alerts** 选择 **Limited alerts**（默认）或 **Group resolution alerts**，保存 Trigger

    **Continuous alerts** 在条件满足期间每次评估都会发送通知，但不会发送恢复通知，对应的 Flashduty 告警需要手动关闭。
  </Step>

  <Step title="将接收方添加到 SLO Burn Alert">
    1. 打开 **SLOs**，在目标 SLO 的 **Burn Alerts** 列点击 **Configure**，再点击 **New Burn Alert**
    2. 设置 Exhaustion Time 或 Budget Rate 条件，在 **Notify** 中选择 `Flashduty` 接收方；需要时覆盖 `severity`
    3. 点击 **Create Burn Alert**
  </Step>

  <Step title="验证生命周期">
    Trigger 和 Burn Alert 的 **Test** 会发送 `is_test` 为 `true` 的测试通知（Limited alerts 的 Trigger 和 Burn Alert 发送一条 `TRIGGERED` 和一条 `OK`，Continuous alerts 的 Trigger 只发送 `TRIGGERED`）。Flashduty 对测试通知返回成功，但不会生成告警，可以用来确认推送地址可达。

    要验证完整流程，请让 Trigger 条件真正满足，确认 Flashduty 收到活动告警；再让条件恢复，确认原告警恢复。
  </Step>
</Steps>

## Alert Key

***

Flashduty 直接使用 `instance_id`（`.Alert.InstanceID`）作为 Alert Key。Honeycomb 在模板变量说明中将它定义为一次 Trigger 或 Burn Alert 触发的唯一标识，可用于去重和关联告警；Honeycomb 官方的 incident.io 模板也用它作为 `deduplication_key`，在 `OK` 时解决对应告警。

* 同一次触发期间的重复通知（例如 Trigger 有新的分组越过阈值）和最终的恢复通知，都更新同一条 Flashduty 告警
* 同一个 Trigger 或 Burn Alert 恢复后再次触发，会生成新的 `InstanceID`，在 Flashduty 中是一条新告警
* 名称、描述、告警等级和环境的变化都不会改变 Alert Key

使用 **Group resolution alerts** 时，Flashduty 同样按 `instance_id` 合并通知，收到 `status` 为 `OK` 的通知时恢复告警；告警描述列出当前越过阈值的分组。

## 状态和告警等级

***

Flashduty 根据 `status` 判断触发或恢复，根据 `severity` 变量确定告警等级。

| `severity` | Flashduty 告警等级 |
| :--------- | :------------- |
| `critical` | Critical       |
| `warning`  | Warning        |
| `info`     | Info           |
| 空值或其他值     | Critical       |

`status` 为 `OK` 时，Flashduty 恢复原告警，并保留最后一次的告警等级。空值或其他 `status` 会被拒绝。

## 标签

***

| 标签                 | 来源                                                  |
| :----------------- | :-------------------------------------------------- |
| `check`            | Trigger 名称或 SLO 名称                                  |
| `alert_type`       | `trigger`、`slo_budget_rate` 或 `slo_exhaustion_time` |
| `alert_id`         | Trigger ID 或 Burn Alert ID                          |
| `instance_id`      | `.Alert.InstanceID`                                 |
| `env`              | Honeycomb 环境名称                                      |
| `datasets`         | 数据集名称，多个时用逗号分隔                                      |
| `severity`         | `severity` 变量的原始值                                   |
| `alert_url`        | Honeycomb 中 Trigger 或 Burn Alert 的链接                |
| `result_url`       | 触发告警的查询结果链接（仅 Trigger）                              |
| `investigate_url`  | Honeycomb Canvas 调查链接                               |
| `slo_id`、`slo_url` | 关联 SLO 的 ID 和链接（仅 Burn Alert）                       |

## 排查问题

***

* **Honeycomb 中选不到 Flashduty 接收方**：确认 **Payload** 页签中对应的告警类型已启用并填写了模板
* **Flashduty 返回参数错误**：确认模板与上文一致，`instance_id` 和 `status` 非空；Honeycomb 对 4xx 响应不会重试
* **告警等级都是 Critical**：确认定义了 `severity` 变量，并在 Trigger 或 Burn Alert 中按需覆盖
* **告警没有恢复**：确认 Trigger 没有使用 **Continuous alerts**；测试通知不会生成或恢复告警

更多信息请参阅 Honeycomb 文档 [Send Alerts to Webhooks](https://docs.honeycomb.io/notify/webhooks/)、[Custom Webhook Variables](https://docs.honeycomb.io/notify/webhooks/variables/) 和 [Monitor SLOs](https://docs.honeycomb.io/notify/slos/monitor/)。