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

# Coralogix 告警集成

> 通过 Notification Center 的 Generic HTTPS 连接器，将 Coralogix 告警的触发和恢复同步到 Flashduty On-call。

通过 Coralogix Notification Center 的 Generic HTTPS 连接器将告警同步到 Flashduty On-call。Coralogix 用 `groupingKey` 标识一条告警通知，Flashduty 用它作为 Alert Key：同一告警的触发、重复通知和恢复会持续更新同一条 Flashduty 告警。

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

  ***

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

  ### 使用专属集成

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

  ### 使用共享集成

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

## 在 Coralogix 中配置

***

以下步骤需要 Notification Center 的管理权限（创建连接器、预设和路由器，编辑告警定义的标签）。

<Steps>
  <Step title="创建 Generic HTTPS 连接器">
    1. 在左侧导航中将鼠标悬停在 **Integrations** 上，选择 **Notification Center**，打开 **Connectors** 页签
    2. 在 **Add new connector** 中点击 **Generic HTTPS** 右侧的 **+**，名称可填写 `Flashduty`
    3. 将 Flashduty 集成的完整推送地址粘贴到 **URL**，其余字段保持默认，保存连接器

    连接器的 **Send test notification** 会发送空的 JSON 对象 `{}`，Flashduty 返回成功但不会生成告警。
  </Step>

  <Step title="创建告警预设">
    1. 打开 **Presets** 页签，切换到 **Alerts**，在 **Add new alert preset** 中点击 **Generic HTTPS** 右侧的 **+**
    2. 把下面的 JSON 粘贴到 **Body**，保存预设

    ```json theme={null}
    {
      "grouping_key": {{ alert.groupingKey | json_encode }},
      "status": {{ alert.status | json_encode }},
      "priority": {{ alert.highestPriority | default(value = alertDef.priority) | json_encode }},
      "alert_name": {{ alertDef.name | json_encode }},
      "alert_description": {{ alertDef.description | json_encode }},
      "alert_definition_id": {{ alertDef.id | default(value = "") | json_encode }},
      "alert_type": {{ alertDef.type | default(value = "") | json_encode }},
      "alert_url": {{ alert.alertDataUrl | default(value = "") | json_encode }},
      "team_name": {{ _context.system.name | default(value = "") | json_encode }},
      "entity_labels": {% if alertDef.entityLabels %}{{ alertDef.entityLabels | json_encode }}{% else %}{}{% endif %},
      "groups": [{% if alert.groups %}{% for g in alert.groups %}{"priority": {{ g.priority | default(value = "") | json_encode }}, "key_values": {% if g.keyValues %}{{ g.keyValues | json_encode }}{% else %}{}{% endif %}}{% if not loop.last %},{% endif %}{% endfor %}{% endif %}]
    }
    ```

    <Warning>
      请保留 `grouping_key` 和 `status`。缺少 `grouping_key` 时 Flashduty 会拒绝请求，因为无法把恢复关联到原告警；`status` 只接受 `Triggered` 和 `Resolved`。
    </Warning>
  </Step>

  <Step title="创建路由器并添加告警规则">
    1. 打开 **Routers** 页签创建路由器，设置路由标签，例如 **Team** 为 `payments`。路由标签的键只能是 **Environment**、**Team** 或 **Service**
    2. 保存后在路由器中打开 **Alerts** 页签（默认显示的是 **Cases**），点击 **New rule**。**Notify for all trigger types** 默认开启，会同时发送触发和恢复通知；条件留空表示匹配所有告警
    3. 目标选择刚创建的 `Flashduty` 连接器和告警预设

    请使用 **Alerts** 规则，不要使用 **Cases** 规则：Flashduty 自己负责告警分组和故障管理，本集成只解析告警通知。
  </Step>

  <Step title="配置告警定义">
    1. 编辑或创建告警定义，在 **Response** 步骤中将通知对象选为 **Alerts**（不是 **Cases**），**Notification Method** 选择 **Route via Labels**
    2. 添加与路由器匹配的路由标签，例如 **Team** 为 `payments`，渲染后为 `routing.team: payments`
    3. 保持 **Send a notification when resolved** 勾选（默认已勾选），否则 Coralogix 不会发送恢复通知
    4. 告警设置了 **Group by** 时，建议在 **Case settings** 中选择 **Separate cases**，每个分组组合分别发送通知，在 Flashduty 中成为一条独立告警。默认的 **Combined case** 会把所有组合放进同一条通知
  </Step>

  <Step title="验证生命周期">
    让告警真正触发，确认 Flashduty 收到活动告警；再让条件恢复正常，确认原告警恢复。以 5 分钟窗口的日志阈值告警为例，日志写入后约 3 分钟收到触发通知，停止写入后约 6 分钟收到恢复通知。

    预设的 **Send test notification** 使用示例数据渲染预设，会在 Flashduty 生成一条 Info 级别的告警 `[Test Alert] General Example`。这条告警不会收到恢复通知，请在 Flashduty 中手动关闭。
  </Step>
</Steps>

## Alert Key

***

Flashduty 直接使用 `alert.groupingKey` 作为 Alert Key。Coralogix 在告警通知的字段说明中将 `groupingKey` 定义为去重键，其官方 Opsgenie 和 Jira Service Management 配置也在 `Resolved` 时用 `groupingKey` 关闭对应的告警。

选择 **Separate cases** 时，每个 Group by 组合分别发送通知，各自拥有自己的 `groupingKey`，因此在 Flashduty 中是不同的告警。选择 **Combined case** 时，一次通知汇总所有命中的组合，Flashduty 只生成一条告警，并在描述中逐行列出每个组合的优先级和取值。

标题、描述、优先级和分组取值的变化都不会改变 Alert Key。

## 状态和告警等级

***

Flashduty 根据 `status` 判断触发或恢复，根据 `priority`（`alert.highestPriority`，缺省时取告警定义的优先级）确定告警等级。

| Coralogix `priority` | Flashduty 告警等级 |
| :------------------- | :------------- |
| `P1`                 | Critical       |
| `P2`                 | Critical       |
| `P3`                 | Warning        |
| `P4`                 | Info           |
| `P5`                 | Info           |
| 空值或其他值               | Warning        |

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

## 标签

***

| 标签                                 | 来源                                                                                |
| :--------------------------------- | :-------------------------------------------------------------------------------- |
| `check`                            | 告警定义名称                                                                            |
| `grouping_key`                     | `alert.groupingKey`                                                               |
| `priority`                         | 告警优先级                                                                             |
| `alert_definition_id`、`alert_type` | 告警定义 ID 和类型                                                                       |
| `alert_url`                        | Coralogix 中该告警的链接                                                                 |
| `team_name`                        | Coralogix 团队名称                                                                    |
| 告警定义标签                             | `alertDef.entityLabels`，键中的 `.`、`-` 等字符转为 `_`，例如 `routing.team` 变为 `routing_team` |
| 分组取值                               | 只有一个分组组合时，写入 `alert.groups[0].keyValues` 中的每个键值                                   |

单条告警最多 50 个标签，超出时请求会被拒绝。

## 排查问题

***

* **Coralogix 显示投递失败**：确认连接器 URL 是完整的推送地址，且包含 `integration_key`
* **Flashduty 返回参数错误**：确认预设 Body 与上文一致，渲染结果是有效 JSON，`grouping_key` 和 `status` 非空
* **告警没有恢复**：确认告警定义勾选了 **Send a notification when resolved**，路由规则开启了 **Notify for all trigger types** 或勾选了 **Resolved**；通过 Terraform 或 API 创建的告警还需确认 `notifyOn` 不是 `triggered_only`。在 Coralogix 中手动解决告警不会发送通知
* **多个分组合并成一条告警**：告警定义的 **Case settings** 是 **Combined case**，改为 **Separate cases**
* **使用旧版 Outbound Webhook**：本集成解析 Notification Center 预设渲染的请求体，旧版 Outbound Webhook 的 `$` 占位符模板不适用。Coralogix 推荐使用 Notification Center 替代旧版 Webhook

更多信息请参阅 Coralogix 文档 [Alerts as a notification source type](https://coralogix.com/docs/user-guides/alerting/configure-notifications/source-type-schema/)、[Generic HTTPS 连接器](https://coralogix.com/docs/user-guides/notification-center/destination-types/https/connector-config/) 和 [路由规则](https://coralogix.com/docs/user-guides/notification-center/routing/define-routing-rule/)。