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

# OpenSearch 告警集成

> 通过 Alerting 插件的自定义 Webhook 通知渠道，将 OpenSearch 监控的触发通知同步到 Flashduty On-call。

通过 OpenSearch Alerting 插件的 Monitor 触发器，将 per query 和 per cluster metrics 类型的监控通知同步到 Flashduty On-call。OpenSearch 没有固定的 Webhook 报文，通知内容由触发器动作中的 Mustache 消息模板决定。本页提供一份模板，Flashduty 按这份模板解析。

每个 Monitor 的每个触发器对应一条 Flashduty 告警：触发器条件成立期间，Monitor 每运行一次就推送一次通知，这些通知合并到同一条告警。OpenSearch 在条件不再成立时不会发送恢复通知，因此需要在协作空间开启超时自动关闭。

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

  ***

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

  ### 使用专属集成

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

  ### 使用共享集成

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

## 在 OpenSearch 中配置

***

需要安装 Alerting 和 Notifications 插件（OpenSearch 默认自带），并有创建通知渠道和 Monitor 的权限。

<Steps>
  <Step title="创建自定义 Webhook 通知渠道">
    1. 在 OpenSearch Dashboards 中进入 **Notifications → Channels → Create channel**
    2. 填写渠道名称，**Channel type** 选择 **Custom webhook**
    3. **Define endpoints by** 选择 **Webhook URL**，将 Flashduty 集成的完整推送地址粘贴进去，地址中需包含 `integration_key`
    4. **Method** 选择 `POST`
    5. 在 **Webhook headers** 中添加 `Content-Type: application/json`
    6. 点击 **Create**

    如果 OpenSearch 集群配置了 `opensearch.notifications.core.http.host_deny_list`，需要保证 `api.flashcat.cloud` 不在其中。
  </Step>

  <Step title="在 Monitor 的触发器中添加动作">
    1. 进入 **Alerting → Monitors**，创建或编辑一个 **Per query monitor** 或 **Per cluster metrics monitor**
    2. 在 **Triggers** 中添加触发器，填写 **Trigger name**、**Severity level**（1 到 5）和触发条件
    3. 在触发器下点击 **Add action**，**Notification channel** 选择上一步创建的渠道
    4. 将下面的模板完整粘贴到 **Message**，不要改动引号和字段名：

    ```text theme={null}
    {
      "monitor_id": "{{ctx.monitor._id}}",
      "monitor_name": "{{ctx.monitor.name}}",
      "trigger_id": "{{ctx.trigger.id}}",
      "trigger_name": "{{ctx.trigger.name}}",
      "severity": "{{ctx.trigger.severity}}",
      "period_start": "{{ctx.periodStart}}",
      "period_end": "{{ctx.periodEnd}}",
      "hit_count": "{{ctx.results.0.hits.total.value}}",
      "error": "{{ctx.error}}"
    }
    ```

    5. 保存 Monitor

    `hit_count` 是 Per query monitor 查询命中的文档数，Per cluster metrics monitor 没有这个值，会推送空字符串，不影响告警。Per bucket、Per document 和 Composite monitor 的通知变量与上面的模板不同，本集成不支持。

    **Action throttling** 可以限制通知频率。节流期间不推送通知，节流时长内没有新通知，告警仍按下面的超时自动关闭时长关闭。
  </Step>

  <Step title="开启超时自动关闭">
    Per query 和 Per cluster metrics 的触发器只在条件成立时执行动作，条件不再成立后 OpenSearch 不会发送任何通知。请在接收这些告警的协作空间中开启[超时自动关闭](/zh/on-call/channel/create-edit)，**超时计时起点** 选择 **故障触发**，超时时长建议设置为 **1 小时**。条件恢复后，告警在超时时长到达时关闭；如果条件仍然成立，超时关闭后 Monitor 的下一次通知会重新创建告警。
  </Step>

  <Step title="验证">
    1. 在 **Notifications → Channels** 中打开该渠道，点击 **Send test message**，Flashduty 会创建一条标题为 `OpenSearch test notification` 的 Info 告警，验证后请手动关闭
    2. 让 Monitor 的触发条件真正成立（例如临时降低阈值），等待 Monitor 下一次运行，确认 Flashduty 收到告警，等级与触发器的 Severity level 对应
    3. 恢复阈值，等待超时自动关闭时长到达，确认告警自动关闭
  </Step>
</Steps>

## Alert Key

***

Flashduty 用 Monitor ID 和触发器 ID 计算 Alert Key，即模板中的 `monitor_id` 和 `trigger_id`。同一个 Monitor 的同一个触发器，每次通知使用同一个 Alert Key，因此合并为一条告警；不同的触发器、不同的 Monitor 各有各的告警。Monitor 名称、触发器名称、等级、命中数和时间段的变化不会改变 Alert Key。`monitor_id` 或 `trigger_id` 为空的通知会被拒绝并返回参数错误。

模板中没有使用 `ctx.alert.id`：触发器第一次执行动作时，OpenSearch 还没有创建告警，这个变量为空。

## 状态和告警等级

***

OpenSearch 触发器的 **Severity level** 取值 1（最高）到 5（最低），Flashduty 按下表映射：

| Severity level | Flashduty 等级 |
| :- | :- |
| 1、2 | Critical |
| 3 | Warning |
| 4、5 | Info |
| 空或其他值 | Warning |

每条通知都是触发状态，Flashduty 不会因为 OpenSearch 的通知而自动恢复告警，恢复由超时自动关闭完成，也可以在 Flashduty 中手动关闭。

## 标签

***

| 标签 | 来源 |
| :- | :- |
| `check` | Monitor 名称和触发器名称，格式为 `Monitor 名称: 触发器名称` |
| `monitor_id` / `monitor_name` | Monitor 的 ID 和名称 |
| `trigger_id` / `trigger_name` | 触发器的 ID 和名称 |
| `severity` | 触发器的 Severity level 原始值 |
| `period_start` / `period_end` | 本次 Monitor 执行的时间段 |
| `hit_count` | 查询命中的文档数（仅 Per query monitor） |
| `error` | 触发器无法取得结果或无法计算条件时的错误信息 |

## 排查问题

***

* **Flashduty 返回参数错误**：确认 Message 是完整的模板，`monitor_id` 和 `trigger_id` 都有值；确认 URL 完整且包含 `integration_key`
* **OpenSearch 中通知发送失败**：在 **Notifications → Channels** 中对该渠道点击 **Send test message** 查看错误，常见原因是集群无法访问 `api.flashcat.cloud` 或该域名在 `host_deny_list` 中
* **告警没有自动关闭**：确认协作空间已开启超时自动关闭，计时起点为 **故障触发**
* **在 OpenSearch 中认领（Acknowledge）告警后没有新通知**：OpenSearch 对已认领的告警不再执行动作，Flashduty 的告警会在超时自动关闭后关闭
* **告警标题里出现空的触发器名称**：触发器没有填写名称时，Flashduty 只用 Monitor 名称作标题；两者都为空时标题为 `OpenSearch alert: 触发器 ID`

更多变量含义请参阅 [OpenSearch Alerting 触发器](https://docs.opensearch.org/latest/observing-your-data/alerting/triggers/) 和 [Notifications 渠道](https://docs.opensearch.org/latest/observing-your-data/notifications/)。