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

# Tideways 告警集成

> 通过 Webhook 将 Tideways 的响应时间、错误率、数据中断、异常和慢 SQL 通知同步到 Flashduty On-call。

通过 Tideways 组织级的 Webhook 集成，将 PHP 应用的性能与错误通知同步到 Flashduty On-call。响应时间、错误率类事件（Incident）有完整的生命周期：开启时触发告警，持续时更新，关闭时告警自动恢复。事务失败率和数据中断只在出现时推送一次，不会发送恢复通知。异常和慢 SQL 通知在错误分组新出现、重新打开或再次出现时发送；分组被标记为已解决时 Tideways 不发送任何通知，这类告警不会自动恢复。

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

  ***

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

  ### 使用专属集成

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

  ### 使用共享集成

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

## 在 Tideways 中配置

***

需要组织的管理权限。Tideways 的 Webhook 只支持 HTTPS 地址，且请求不带签名和自定义请求头，Flashduty 通过推送地址中的 `integration_key` 识别集成，请勿泄露该地址。

<Steps>
  <Step title="添加 Webhook 集成">
    1. 进入组织的 **Integrations** 设置，点击 **Add New Integration**，选择 **Webhook**
    2. 填写名称，将 Flashduty 集成的完整推送地址粘贴到 URL，地址中需包含 `integration_key`
    3. 在触发选项中勾选 **and when the alert is fixed**。该项默认不勾选，不勾选时 Tideways 不发送 `closed` 通知，Incident 类告警在 Flashduty 中不会恢复
    4. 保存
  </Step>

  <Step title="关联到项目通知">
    进入应用的 **Project Settings → Notifications**，对需要值班处理的每条通知规则点击 **Edit**，勾选刚创建的 Webhook 集成并保存（没有对应规则时，用 **Create Notification Rule** 新建）。各类型在 Flashduty 中的处理见下表。

    | Tideways 通知规则 | `type` | 在 Flashduty 中的效果 |
    | :- | :- | :- |
    | Service Response Time | `response_time` | 触发、更新、恢复 |
    | Service Failure Rate | `error_rate` | 触发、更新、恢复 |
    | Transaction Response Times | `transaction-response-time` | 触发、更新、恢复 |
    | Transaction Failure Rates | `transaction-failure-rate` | 触发（不恢复） |
    | Heartbeat Monitoring | `missing-data` | 触发（不恢复） |
    | New Error/Exception | `exception` | 触发（不恢复） |
    | New Slow SQL Query | `slow-sql` | 触发（不恢复） |
    | Weekly Performance Report、New Release、发布对比 | `weekly_report`、`release`、`compare_release` | 只返回成功，不创建告警 |
  </Step>

  <Step title="验证生命周期">
    让应用的响应时间越过阈值，确认 Flashduty 收到活动告警。指标在规则的检查周期（5 到 60 分钟）内持续超过阈值后，Tideways 才会开启 Incident；指标回落、Tideways 关闭该 Incident 后，确认原告警恢复。

    集成页的 **Preview** 按钮发送一条状态为 `opened`、Incident ID 为占位值的 `response_time` 通知。Flashduty 会据此创建一条 Warning 告警，之后不会有 `closed` 通知，验证后请在 Flashduty 中手动关闭。
  </Step>
</Steps>

## Alert Key

***

响应时间、失败率和事务响应时间 Incident 使用 Incident ID（`notification.incident_id`）与通知类型、组织、应用一起计算 Alert Key。Tideways 文档说明，这三类通知的 `status` 为 `opened`、`ongoing` 或 `closed`，对应同一个 Incident 的不同阶段；`incidient_id` 是 `incident_id` 的历史拼写副本，值相同，Flashduty 在缺少 `incident_id` 时读取它。缺少两者的 Incident 通知会被拒绝，未知的 `status` 同样会被拒绝。

其他类型按对象计算 Alert Key：

* 新异常、新慢 SQL：使用错误分组 ID（`notification.error_group.id`）。同一分组再次出现时合并到同一条告警
* 事务失败率、数据中断：使用组织、应用、环境（`environment`）、服务（`service`）和事务（`transaction`）。同一检查对象再次触发时合并到同一条告警

数值、时间、阈值和分组的出现次数变化都不会改变 Alert Key。错误分组状态为 `resolved`、`not_error` 或 `ignored` 的通知会恢复该分组对应的告警。异常规则只在错误首次出现、再次出现（发布后）、重新打开和未确认时通知，因此分组被标记为已解决时实际不会产生通知；重新打开的分组会合并到原告警。

## 状态和告警等级

***

Tideways 通知不带告警等级，Flashduty 按类型设置：

| 通知 | Flashduty 等级 | 说明 |
| :- | :- | :- |
| 响应时间、失败率、事务响应时间、事务失败率 | Warning | 越过阈值，但服务仍在响应 |
| 数据中断（`missing-data`） | Critical | 服务或事务完全没有数据上报 |
| 新异常 | Warning | |
| 新慢 SQL | Info | |

`status` 为 `closed`，或错误分组状态为 `resolved`、`not_error`、`ignored` 时告警恢复，恢复事件保留最近一次的告警等级。

## 告警不会自动恢复的情况

***

事务失败率和数据中断只在出现时发送一次，Tideways 没有对应的恢复通知，告警不会自动恢复。异常和慢 SQL 告警在错误分组被标记为已解决或已忽略后仍保持活动，因为 Tideways 不会为此发送通知。

建议在协作空间开启[超时自动关闭](/zh/on-call/channel/create-edit)，超时计时起点选 **故障触发**，超时时长建议 24 小时。数据中断和新异常一般在一个工作日内确认处理；如果协作空间只接收响应时间和失败率通知，可以不开启。

## 标签

***

| 标签 | 来源 |
| :- | :- |
| `organization` / `application` | Tideways 组织和应用标识 |
| `check` | 通知类型（`type`） |
| `incident_id` / `status` | Incident ID 和阶段，仅 Incident 类通知 |
| `value` / `threshold` | 当前值和阈值 |
| `env` / `service` / `transaction` | 环境、服务和事务 |
| `since_hours` | 数据中断的持续小时数 |
| `error_group_id` / `exception_type` / `source_location` / `occurrences` | 错误分组 ID、异常类型、来源位置和累计次数，仅异常和慢 SQL |

## 排查问题

***

* **Tideways 显示推送失败**：确认地址使用 HTTPS 且包含 `integration_key`。Tideways 不重试，返回 400 及以上状态码的推送只记录在集成页的错误日志中
* **Flashduty 返回参数错误**：错误信息会指出缺少的字段（如 `notification.incident_id`）或不支持的 `type`
* **告警没有恢复**：响应时间、失败率和事务响应时间 Incident 在 `closed` 时恢复，异常、慢 SQL、事务失败率和数据中断请开启超时自动关闭。Incident 类告警在 Tideways 关闭后仍未恢复时，检查 Webhook 集成上是否勾选了 **and when the alert is fixed**
* **周报或发布通知没有告警**：这些通知不是故障，Flashduty 只返回成功

更多字段含义请参阅 [Tideways Webhook 文档](https://support.tideways.com/documentation/reference/integrations/webhook.html)。