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

# Observium 告警集成

> 通过 Observium 的 Webhook JSON 通知通道将告警检查器和 Syslog 告警同步到 Flashduty On-call，检查器恢复时自动关闭告警。

Observium 通过 **Webhook JSON** 类型的联系人（Contact）推送告警：告警检查器（Alert Checker）触发、重复提醒或恢复时，Observium 按联系人中的 JSON 模板向 Flashduty 发送一条 JSON。每个「告警检查器 + 监控对象」对应一条 Flashduty 告警：检查失败时打开，检查恢复时自动关闭。Syslog 告警规则的每次命中各生成一条独立告警。

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

  ***

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

  ### 使用专属集成

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

  ### 使用共享集成

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

## 在 Observium 中配置

***

Observium 社区版（Community Edition）即自带 **Webhook JSON** 通道，无需订阅版。以下界面名称以 Observium CE 26.1 为准。

<Steps>
  <Step title="创建联系人">
    以管理员身份登录 Observium，在顶部菜单 **Observium**（地球图标）中选择 **Contacts**，点击右上角 **Add Contact**，按下表填写：

    | 字段 | 填写内容 |
    | :- | :- |
    | **Transport** | `Webhook JSON` |
    | **Description** | 自定义名称，例如 `Flashduty` |
    | **URL** | Flashduty 的完整推送地址，包括 `?integration_key=...` |
    | **JSON passed to Webhook** | 保持默认模板，见下方 |
    | **Fallback URL**、**Authentication token** | 留空 |

    点击 **Add Contact** 保存。

    <Warning>**Transport** 请选择 **Webhook JSON**，不要选择 **Webhook**。**Webhook** 通道要求接收方返回 `{"status": "successful"}`，Flashduty 的响应不含该字段，Observium 会把每次推送记为失败并在通知有效期（5 分钟）内重试，Flashduty 会收到重复事件。</Warning>

    **JSON passed to Webhook** 的默认模板如下。Flashduty 读取其中的 `ALERT_STATE`、`ALERT_ID`、`ALERT_SEVERITY`、`ALERT_MESSAGE`、`ALERT_URL`、`CONDITIONS`、`METRICS`、`DURATION`、`ENTITY_*` 和 `DEVICE_*` 字段；如果您修改过模板，请至少保留 `ALERT_STATE` 和 `ALERT_ID`，并保持每个值都带引号：

    ```json theme={null}
    {
      "ALERT_STATE": "%ALERT_STATE%",
      "ALERT_STATE_NAME": "%ALERT_STATE_NAME%",
      "ALERT_EMOJI": "%ALERT_EMOJI%",
      "ALERT_EMOJI_NAME": "%ALERT_EMOJI_NAME%",
      "ALERT_STATUS": "%ALERT_STATUS%",
      "ALERT_STATUS_CUSTOM": "%ALERT_STATUS_CUSTOM%",
      "ALERT_SEVERITY": "%ALERT_SEVERITY%",
      "ALERT_COLOR": "#%ALERT_COLOR%",
      "ALERT_URL": "%ALERT_URL%",
      "ALERT_UNIXTIME": "%ALERT_UNIXTIME%",
      "ALERT_TIMESTAMP": "%ALERT_TIMESTAMP%",
      "ALERT_TIMESTAMP_RFC2822": "%ALERT_TIMESTAMP_RFC2822%",
      "ALERT_TIMESTAMP_RFC3339": "%ALERT_TIMESTAMP_RFC3339%",
      "ALERT_ID": "%ALERT_ID%",
      "ALERT_MESSAGE": "%ALERT_MESSAGE%",
      "CONDITIONS": "%CONDITIONS%",
      "METRICS": "%METRICS%",
      "DURATION": "%DURATION%",
      "ENTITY_URL": "%ENTITY_URL%",
      "ENTITY_LINK": "%ENTITY_LINK%",
      "ENTITY_NAME": "%ENTITY_NAME%",
      "ENTITY_ID": "%ENTITY_ID%",
      "ENTITY_TYPE": "%ENTITY_TYPE%",
      "ENTITY_DESCRIPTION": "%ENTITY_DESCRIPTION%",
      "DEVICE_HOSTNAME": "%DEVICE_HOSTNAME%",
      "DEVICE_SYSNAME": "%DEVICE_SYSNAME%",
      "DEVICE_DESCRIPTION": "%DEVICE_DESCRIPTION%",
      "DEVICE_ID": "%DEVICE_ID%",
      "DEVICE_URL": "%DEVICE_URL%",
      "DEVICE_LINK": "%DEVICE_LINK%",
      "DEVICE_HARDWARE": "%DEVICE_HARDWARE%",
      "DEVICE_OS": "%DEVICE_OS%",
      "DEVICE_TYPE": "%DEVICE_TYPE%",
      "DEVICE_LOCATION": "%DEVICE_LOCATION%",
      "DEVICE_UPTIME": "%DEVICE_UPTIME%",
      "DEVICE_REBOOTED": "%DEVICE_REBOOTED%",
      "TITLE": "%TITLE%"
    }
    ```
  </Step>

  <Step title="关联告警检查器">
    1. 在 **Contacts** 列表中点击刚创建的联系人，进入联系人详情
    2. 在 **Associated Alert Checkers** 区域的下拉框中选择需要推送的告警检查器，点击 **Associate**；每次关联一个，重复操作关联多个
    3. 如需推送 Syslog 告警，在 **Associated Syslog Rules** 区域同样选择规则并点击 **Associate**

    确认每个检查器的 **Send recovery notification** 为开启状态（新建检查器时默认开启；已有检查器在顶栏 **Observium** 菜单 → **Alert Checks** 中打开检查器，点击 **Edit Check** 查看），否则检查恢复时 Observium 不发送通知，Flashduty 中的告警不会关闭。
  </Step>

  <Step title="验证生命周期">
    Observium 社区版的网页界面没有联系人测试按钮，请在 Observium 安装目录（通常为 `/opt/observium`）中用命令行发送测试通知，`<contact_id>` 为 **Contacts** 列表中该联系人的 ID：

    ```bash theme={null}
    ./test_alert.php -c <contact_id>      # 测试告警通知
    ./test_alert.php -c <contact_id> -r   # 测试恢复通知
    ./test_alert.php -c <contact_id> -s   # 测试 Syslog 通知
    ```

    测试通知使用 Observium 自带的示例数据，其中的链接都指向 `observium.test`。Flashduty 返回成功，不会生成告警。

    然后让一个检查器真正触发（例如让一台被监控设备不可达，使设备 up/down 检查器告警），确认 Flashduty 收到活动告警；恢复设备后，确认原告警关闭。Observium 的 alerter 在每次轮询后检查告警并发送通知，告警和恢复通常在一个轮询周期（默认 5 分钟）内送达；检查器设置了 **Alert Delay** 时，告警会再推迟相应的检查次数。
  </Step>
</Steps>

## Alert Key

***

Flashduty 使用 `ALERT_ID` 作为检查器告警的 Alert Key。`ALERT_ID` 是 Observium `alert_table` 表中的行 ID，每个「告警检查器 + 监控对象」只有一行，告警、重复提醒和恢复通知都携带同一个值。因此同一对象上同一检查器的通知落在同一条告警上，恢复后再次失败会打开一条新告警。

告警等级、检查器消息、主机名、指标值和时间的变化都不会改变 Alert Key。`ALERT_ID` 只在一个 Observium 实例内唯一：多个 Observium 实例请分别使用不同的 Flashduty 集成。

Syslog 告警的 `ALERT_ID` 是 Syslog 规则的 ID，且 Syslog 告警没有恢复通知，因此每次命中都生成一条新告警，不会自动恢复。建议在协作空间开启[超时自动关闭](/zh/on-call/channel/create-edit)，超时计时起点选 **故障触发**，超时时长建议 1 小时：每次命中只是一条日志事件，问题仍在时下一条匹配的日志会再生成新告警。也可以在 Flashduty 中手动关闭。

请求缺少 `ALERT_STATE` 或 `ALERT_ID`，或 `ALERT_STATE` 不是下表中的值时，Flashduty 会拒绝该请求。

## 告警生命周期

***

Flashduty 按 `ALERT_STATE` 字段处理通知：

| Observium `ALERT_STATE` | 含义 | Flashduty 处理 |
| :- | :- | :- |
| `ALERT` | 检查器首次告警 | 触发告警 |
| `ALERT REMINDER` | 告警持续期间的重复提醒 | 更新告警 |
| `RECOVER` | 检查器恢复 | 恢复告警 |
| `SYSLOG` | Syslog 规则命中 | 触发一条独立告警，不会自动恢复 |

`ALERT_STATE` 是 Observium 的固定状态名，不受 `$config['alerts']['status_name']` 自定义影响；自定义名称体现在 `ALERT_STATE_NAME` 中，Flashduty 不读取它。

## 告警等级

***

告警等级取自 `ALERT_SEVERITY`：

| Observium `ALERT_SEVERITY` | Flashduty 等级 |
| :- | :- |
| `Critical`、`Emergency`、`Alert`、`Error` | Critical |
| `Warning` | Warning |
| `Informational`、`Notification`、`Debugging`、`Other` | Info |
| 其他值或为空 | Critical |

检查器告警的等级是检查器的 **Severity**（`Critical` 或 `Warning`）；Syslog 告警的等级是该条日志的 Syslog 优先级。恢复通知携带同一个检查器的等级，恢复事件保留该等级。

## 告警内容

***

* **标题**：`<检查器消息> on <对象名称>`；对象不是设备本身（例如端口、传感器）时，末尾追加 `(<主机名>)`。检查器消息为空时用 `Observium alert <ALERT_ID>` 代替
* **描述**：`CONDITIONS`（未满足的条件）、`METRICS`（当前指标值）和 `DURATION`（持续时间），各占一行
* **标签**：`check`（检查器消息）、`resource`（对象名称）、`host`（主机名）、`alert_id`、`entity_type`、`entity_id`、`device_id`、`sys_name`、`os`、`hardware`、`device_type`、`location`、`severity`（原始等级）、`state`（`ALERT_STATE` 原值）、`alert_url`（Observium 中的告警页面）

值为空的字段，以及模板中未被替换的 `%TAG%` 占位符（例如 Syslog 通知中的 `ENTITY_*`），不会写入标签。

## 排查问题

***

* **Observium 把通知记为发送失败、Flashduty 收到重复事件**：联系人的 **Transport** 选成了 **Webhook**，请改为 **Webhook JSON**
* **Flashduty 返回 400，提示 `ALERT_STATE is required` 或 `ALERT_ID is required`**：联系人的 JSON 模板缺少对应字段，恢复为默认模板
* **Flashduty 返回 400，错误信息是 JSON 解析错误**：检查修改过的模板，每个 `%TAG%` 都要写在引号中
* **告警没有发出**：确认联系人已关联该检查器，且联系人未被禁用；在 Observium 安装目录运行 `./alerter.php -h all -d` 查看通知发送结果（不带 `-h` 会报 `Invalid arguments!`）
* **告警没有恢复**：确认检查器的 **Send recovery notification** 已开启
* **告警中的 Observium 链接不可访问**：在 `config.php` 中设置 `$config['web_url']` 为 Observium 的外部访问地址，命令行发送通知时用它生成链接

通知通道和告警检查器的说明请参阅 Observium 文档 [Transports](https://docs.observium.org/alerting_transports/) 和 [Alert Checkers](https://docs.observium.org/alert_checker/)。