跳转至

对接观测云自建通知对象

此功能需要 2.5.2 及以后版本

1. 背景

在某些情况下，观测云提供的告警通知方式无法满足实际的业务需要。 而通过「自定义 Webhook」方式调用又需要用户修改现有业务系统或单独搭建接收系统，较为不便。

此时，可以使用观测云的「自建通知对象」实现将告警通知直接到本地 DataFlux Func 的某个函数，由此来执行后续的操作。

2. 准备工作

为了实现自建通知对象，需要做好以下准备工作：

准备 参考文档
将 DataFlux Func 升级到 2.5.2 及以上版本 部署和维护 / 日常维护 / 升级系统
在观测云中创建好 API Key 观测云文档 / 工作空间管理 / API Key 管理

3. 具体操作步骤

以下为具体的操作步骤：

3.1 创建观测云连接器

在「管理 / 实验性功能」中，启用「观测云连接器」

前往「开发 / 连接器 / 添加连接器」，类型选择「观测云」，并填入相关配置参数。

3.2 编写自建通知函数

前往「开发 / 脚本库」，创建用于存放自建通知函数的脚本

用于自建通知的函数，存在固定要求：

  1. 需要在使用@DFF.API(...)装饰的基础上，添加category='guance.alertFunc'
  2. 函数名不限，但必须有且仅有唯一一个参数event，参数值详情见附录

以发送钉钉通知为例，完整代码如下：

发送钉钉通知本身可以直接在观测云配置，不需要自建通知对象，此处代码仅作为示例，并无实际意义

有关钉钉机器人的相关文档见附录

Python
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
import time
import hmac
import hashlib
import base64
import urllib.parse

import requests

@DFF.API('自定义通知对象示例', category='guance.alertFunc')
def test(event=None):
    # 钉钉机器人 Webhook 地址
    webhook = 'https://oapi.dingtalk.com/robot/send?access_token=xxxxxxxxxx'
    # 钉钉机器人加签密钥
    secret  = 'SECxxxxxxxxxx'

    # 计算并添加签名
    timestamp = str(round(time.time() * 1000))
    secret_enc = secret.encode('utf-8')
    string_to_sign = '{}\n{}'.format(timestamp, secret)
    string_to_sign_enc = string_to_sign.encode('utf-8')
    hmac_code = hmac.new(secret_enc, string_to_sign_enc, digestmod=hashlib.sha256).digest()
    sign = urllib.parse.quote_plus(base64.b64encode(hmac_code))
    webhook += f'&timestamp={timestamp}&sign={sign}'

    # 发送钉钉机器人请求
    event = event or {}
    title   = event.get('df_title')   or '没有具体标题'
    message = event.get('df_message') or '没有具体内容'
    data = {
         'msgtype': 'markdown',
         'markdown': {
             'title': title,
             'text' : f"#### {title} \n\n {message} \n\n 本消息通过自建通知对象发出"
         }
     }
    r = requests.post(webhook, json=data)
    return r.text

代码编写完成后，不要忘记发布

3.3 在观测云中确认自建通知对象

进入观测云「监控 / 通知对象管理」，可以在列表中看到之前编写并发布的通知对象函数

3.4 在监控器中选择自建通知对象

进入观测云「监控 / 监控器」，为监控器配置告警策略，并选中新建的自建通知对象。

3.5 接收自建通知

根据之前编写的代码，我们提取了事件的标题和内容，并额外添加了一行「本消息通过自建通知对象发出」提示。

假设在监控器的「事件内容」中简单配置了如下内容：

Text Only
1
2
- Status: {{df_status}}
- Result: {{Result}}

那么，经过自建通知对象处理后，最终在钉钉机器人中收到的消息如下：

X. 附录

以下为附录

X.1 钉钉机器人相关文档

X.2 自建通知对象函数 event 参数

自建通知对象接收的 event 参数为一个 dict，其内部字段如下：

字段名 类型 是否必须 说明
timestamp Integer 必须 产生时间。Unix 时间戳，单位秒
df_status Enum 必须 状态。取值ok, info, warning, error, critical, nodata
df_event_id String 必须 eventID。
df_title String 必须 标题。
df_message String 详细描述。
df_dimension_tags String(JSON-format) 必须 检测纬度标签，如{"host":"web01"}
df_monitor_id String 监控器分组 ID
df_monitor_name String 监控器组名
df_monitor_checker_id String 监控器 ID
df_monitor_checker_name String 监控器名
df_monitor_checker_value String 检测触发事件时的值
df_monitor_checker_value_dumps str(JSON) 检测触发事件时的值（JSON 序列化）
方便使用方通过反序列化获取原始值
df_event_link String 事件跳转链接
df_workspace_uuid String 所属工作空间 UUID
df_workspace_name String 所属工作空间名
Result Float 检测值
{其他更多字段} 略

一般来说，对接第三方消息平台时，只需要用到 df_title 和 df_message 两个字段即可

具体示例如下：

JSON
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
{
    "timestamp"                     : 1625638440,
    "df_status"                     : "warning",
    "df_event_id"                   : "event-xxxxxxxxxx",
    "df_title"                      : "web001 存在问题",
    "df_message"                    : "web001 存在问题、nCPU 使用率大于 90\n 内存使用率大于 90",
    "df_dimension_tags"             : "{\"host\":\"web001\"}",
    "df_monitor_id"                 : "monitor_xxxxxxxxxx",
    "df_monitor_name"               : "异常检测名",
    "df_monitor_checker_id"         : "rul_xxxxxxxxxx",
    "df_monitor_checker_name"       : "异常检测项目名",
    "df_monitor_checker_value"      : "99",
    "df_monitor_checker_value_dumps": "99",
    "df_event_link"                 : "https://console.guance.com/keyevents/monitorChart?xxxxxxxxxx",
    "df_workspace_uuid"             : "wksp_xxxxxxxxxx",
    "df_workspace_name"             : "我的工作空间",
    "Result"                        : 99,
    "... 其他更多字段": "略",
}