告警通道设置样例

本文档用于指导如何配置告警通道及告警订阅，其中一些细节容易被忽略，但使用中会经常用到。

适用场景

以下场景会涉及到本文档的内容：

1. 将不同告警发送给不同的责任人。

2. 发送 json 格式的告警消息。

3. 只接受告警消息，不接受告警恢复消息。

4. 验证告警是否发送成功。

告警通道与订阅

告警通道是告警消息发送的介质，如发送到钉钉群消息、发送到客户的告警平台等。

发送消息分为 2 种订阅模式：群消息通道和非群消息通道。此处的"群"不是钉钉群的意思，类比在钉钉群发送一条消息，群里的成员都能收到该消息，故群消息通道是所有人都会收到告警消息的发送介质。换一种说法：当告警被触发之后，所有的群消息通道都会发送该告警消息。非群消息通道相反，它只发送在这个告警通道订阅列表中的告警消息。

例如下图的配置，OCP 和 DBA 告警项组中的告警，并且是 OceanBase 或 OCP 的告警、停服或严重级别的告警都会通过默认通道发送出去。

通过设置非群消息通道和设置告警订阅，可实现不同告警发送给不同的责任人（先通过特定的通道发送出去，在其他系统中对应到责任人，如夜间值班群、DBA 群等）。

指定语言的告警消息

当前 OCP 支持中文简体、中文繁体、英文 3 种语言，告警消息区分这 3 种语言。若需要发送不同语言的消息，需要先切换到对应语言，将告警通道中的消息模板设置好，然后通过黑屏修改需要发送的语言：

UPDATE `ocp2_alarm_channel` SET message_language='en_US' WHERE id=xxx-id;

可以给不同的通道设置不同的发送语言，以满足运维人员的个性化消息需求。当前支持的设置项：zh_CN（中文简体）、zh_TW（中文繁体）和 en_US（英文）。

发送 json 格式的告警消息

消息分为告警消息和恢复消息 2 种，不同消息的处理方式不同。

• 告警消息

  目前 OCP 告警通道设置页面可配置告警消息模板、聚合消息模板，这些消息模板适用于钉钉群消息。若需要收到 json 格式的消息，则需要进行以下设置。

  说明

  由于只需要按一种语言发送告警消息，因此只需要设置 message_language 对应语言的通道即可。

  1. 将告警消息模板和聚合消息模板都设置为 json 格式。
  2. 在发送消息时引用 ${message_json} 消息模板变量，${message_json} 即为上一步设置的 json 格式的消息 ${message_json}。message_json 是经过转义的消息传，不能再包装，如 {"content": ${message_json}} 将不是一个合法的 json 串。

  注意

  • 如果 步骤 i 未设置 json 格式的消息模板，则在 步骤 ii 中设置的消息内容应为 {"content": "${message_json}"}，由于 ${message_json} 是一个字符串，而非 json 字符串，因此需要加双引号。
  • ${alarm_summary} 和 ${alarm_description} 中可能存在未转义的字符。如 OceanBase 日志告警，告警内容总存在引号或换行符，此时包含 ${alarm_summary} 和 ${alarm_description} 的 ${message_json} 不是合法的 json 结构，同样需要将消息内容设置为 {"content": "${message_json}"}。

• 恢复消息

  恢复消息的模板暂时不提供白屏配置，需要通过命令行修改 metadb 的数据。操作步骤如下：

  1. 登录 ocp_meta 租户的 ocp 数据库。

     obclient -hxxx.xxx.xxx.xxx -P2883 -ur***@ocp_meta#ob_cluster -p****** -Docp
     

  2. 更新 ocp.alarm.recover-message-template 参数。

     注意

     模板的值是 json 结构，定义了不同语言的恢复消息模板，更新时请确认格式无误。

     update config_properties set value='[Alarm Recover Notification]\n- Target ${alarm_target}\n- Details ${alarm_description}\n- Recovered at ${alarm_resolved_at}' where `key`='ocp.alarm.recover-message-template';
     

  默认配置如下：

  ## 英文模板恢复消息模板
  [Alarm Recover Notification]
  - Target ${alarm_target}
  - Details ${alarm_description}
  - Recovered at ${alarm_resolved_at}
  
  ## 中文简体恢复消息模板
  【告警恢复通知】
  - 告警对象 ${alarm_target}
  - 告警详情 ${alarm_description}
  - 恢复时间 ${alarm_resolved_at}
  
  ## 中文繁体恢复消息模板
  【警示恢復通知】
  - 警示對象 ${alarm_target}
  - 警示詳情 ${alarm_description}
  - 恢復時間 ${alarm_resolved_at}
  

设置告警推送时，可配置是否接收告警恢复消息。

验证告警发送结果

当 OCP 版本低于 V3.3.0 时，仅以是否成功发送到目标端来作为是否成功的依据，未校验告警消息返回结果。如响应结果中有错误码或标识失败的字段，此时 OCP 应加以校验。因此，在 OCP V3.3.0版本中，ocp2_alarm_channel 增加了 response_validation 字段用于校验，其校验规则如下：

• 如果返回结果是 json 格式，则 response_validation 也需配置为 json 字符串（默认是"{}"）, 并匹配两者是否相等：告警消息返回内容需包含 response_validation 中所有 key-value 内容。如钉钉群消息通道的 response_validation 字段设置为 {"errcode":0,"errmsg":"ok"}，错误码为 0 则标识发送结果成功。

• 如果返回结果不是 json，则 response_validation 应与返回结果相同。

  注意

  脚本通道的返回结果包括标准错误和标准输出，优先使用脚本的标准错误与 response_validation 进行匹配。若脚本的标准错误（stderr）为空，则使用脚本的标准输出（stdout）与 response_validation 进行匹配。脚本的规范如下：

  1. 如果脚本发送告警消息失败，则将响应结果输出到标准错误。
  2. 如果程序未将任何信息输出到标准错误，则仅将响应结果输出到标准输出。脚本中打印一些其他日志会导致误判为发送失败。

故升级OCP后，您需要：

1. 为 response_validation 设置合理的值。

2. 检查告警通道的脚本是否存在输出日志的情况，需改为仅将响应体输出到标准错误或标准输出。