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

# Honeybadger 告警集成

> 通过 Webhook 将 Honeybadger 项目的错误、可用性检查和 Check-in 事件同步到 Flashduty On-call。

通过 Honeybadger 项目的 Webhook 集成，将错误（Fault）、可用性检查（Uptime）和 Check-in 事件同步到 Flashduty On-call。每个错误、每个可用性检查、每个 Check-in 各对应一条 Flashduty 告警：错误发生时触发、被标记为已解决时恢复；站点宕机时触发、恢复访问时恢复；Check-in 缺失时触发、重新上报时恢复。

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

  ***

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

  ### 使用专属集成

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

  ### 使用共享集成

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

## 在 Honeybadger 中配置

***

Webhook 集成按项目配置，只有 Honeybadger 的 Team、Business 和 Enterprise 套餐提供，需要项目的管理员权限。

<Steps>
  <Step title="添加 Webhook 集成">
    1. 进入需要接入的 Honeybadger 项目，点击 **Settings → Alerts & Integrations**
    2. 在项目集成列表中选择 **Webhook**
    3. 将 Flashduty 集成的完整推送地址粘贴到 **URL**，地址中需包含 `integration_key`
    4. **Bearer token** 留空即可，Flashduty 通过地址中的 `integration_key` 认证
    5. **Payload version** 保持默认的 `v2`
  </Step>

  <Step title="选择推送的事件">
    在集成的事件选项中勾选需要值班处理的事件。建议同时勾选每类事件的触发和恢复选项，否则告警不会自动恢复。错误的已解决（`resolved`）和重新打开（`unresolved`）选项默认不勾选，需要手动勾选：

    | Honeybadger 事件                | 事件名                  | 在 Flashduty 中的效果          |
    | :---------------------------- | :------------------- | :------------------------ |
    | 错误首次出现，或已解决的错误再次出现            | `occurred`           | 触发或更新该错误的告警               |
    | 错误被手动标记为未解决                   | `unresolved`         | 触发或更新该错误的告警               |
    | 错误发生频率超过设定值（Rate escalations） | `rate_exceeded`      | 触发或更新该错误的告警，等级升为 Critical |
    | 错误被标记为已解决                     | `resolved`           | 恢复该错误的告警                  |
    | 站点宕机                          | `down`               | 触发该检查的告警                  |
    | 站点恢复                          | `up`                 | 恢复该检查的告警                  |
    | Check-in 缺失                   | `check_in_missing`   | 触发该 Check-in 的告警          |
    | Check-in 重新上报                 | `check_in_reporting` | 恢复该 Check-in 的告警          |
    | SSL 证书即将过期                    | `cert_will_expire`   | 触发告警，不会自动恢复               |
    | 项目错误量突增（Anomaly detection）    | `volume_spike`       | 触发告警，不会自动恢复               |

    错误分配（`assigned`）、评论（`commented`）和部署（`deployed`）事件不会创建告警，Flashduty 收到后直接返回成功。选项中的环境过滤、错误过滤和节流设置可以减少推送到 Flashduty 的事件。
  </Step>

  <Step title="保存并验证">
    1. 点击保存
    2. 在接入 Honeybadger SDK 的应用中触发一个新错误，确认 Flashduty 收到活动告警
    3. 在 Honeybadger 中将该错误标记为 **Resolved**，确认原告警恢复

    集成设置页的 **Test this integration** 按钮会推送一条 `occurred` 事件，内容是错误类为 `TestingException` 的示例错误，Flashduty 会为它创建一条 Warning 告警，验证后请手动关闭。
  </Step>
</Steps>

## Alert Key

***

Flashduty 按事件的对象生成 Alert Key，同一对象的触发和恢复事件使用同一个 Alert Key：

| 对象       | 事件                                                 | 使用的字段         |
| :------- | :------------------------------------------------- | :------------ |
| 错误       | `occurred`、`unresolved`、`rate_exceeded`、`resolved` | `fault.id`    |
| 可用性检查    | `down`、`up`                                        | `site.id`     |
| SSL 证书   | `cert_will_expire`                                 | `site.id`     |
| Check-in | `check_in_missing`、`check_in_reporting`            | `check_in.id` |
| 错误量突增    | `volume_spike`                                     | `project.id`  |

Alert Key 由对象类型和上表中的 ID 共同计算，因此证书过期告警不会被同一站点的 `up` 事件恢复，数字相同的错误 ID 和项目 ID 也不会互相合并。错误消息、环境、发生次数、站点名称等字段变化不会改变 Alert Key。缺少对应 ID 的事件会被拒绝。

## 状态和告警等级

***

Honeybadger 事件不携带等级，Flashduty 按事件名确定状态和等级：

| 事件名                                       | 状态 | Flashduty 等级 |
| :---------------------------------------- | :- | :----------- |
| `down`、`check_in_missing`、`rate_exceeded` | 触发 | Critical     |
| `occurred`、`unresolved`                   | 触发 | Warning      |
| `cert_will_expire`、`volume_spike`         | 触发 | Warning      |
| `resolved`、`up`、`check_in_reporting`      | 恢复 | -            |

`cert_will_expire` 和 `volume_spike` 没有对应的恢复事件，处理后需在 Flashduty 中手动关闭告警。

## 标签

***

| 标签                                        | 来源                                   |
| :---------------------------------------- | :----------------------------------- |
| `event`                                   | 本次推送的事件名                             |
| `project` / `project_id`                  | Honeybadger 项目名称和 ID                 |
| `fault_id`                                | 错误 ID                                |
| `error_class`                             | 错误类名，如 `RuntimeError`                |
| `component` / `action`                    | 错误发生的组件和动作（通常对应控制器和方法）               |
| `env`                                     | 错误所在环境                               |
| `notices_count`                           | 错误累计发生次数                             |
| `tags`                                    | 错误的标签，逗号分隔                           |
| `site_id` / `site_name`                   | 可用性检查的 ID 和名称                        |
| `resource`                                | 可用性检查访问的地址                           |
| `outage_reason`                           | 宕机原因，如 `Connection timed out`        |
| `check_in_id` / `check_in_name`           | Check-in 的 ID 和名称                    |
| `schedule_type` / `report_period`         | Check-in 的调度类型和上报周期                  |
| `observed` / `baseline_median` / `factor` | 错误量突增时最近一小时的错误数、基线中位数和倍数             |
| `url`                                     | Honeybadger 中对应错误、检查或 Check-in 页面的链接 |

## 排查问题

***

* **集成列表中没有 Webhook**：确认项目所属账号的套餐为 Team 或更高，并且您是项目管理员
* **Flashduty 返回参数错误**：确认 URL 完整且包含 `integration_key`
* **告警没有恢复**：确认已勾选对应的恢复事件（错误被解决、站点恢复、Check-in 重新上报）
* **测试成功但真实事件没收到**：检查集成的环境过滤、错误过滤和节流设置，以及可用性事件是否勾选了对应站点

更多字段含义请参阅 [Honeybadger Webhook](https://docs.honeybadger.io/guides/integrations/webhook/)。