跳转至

观测云自建巡检

本文档主要介绍如何使用脚本市场中的「观测云智能巡检」脚本包在自建 DataFlux Func GSE版中实现巡检函数的工作。

请始终使用最新版 DataFlux Func GSE 版 进行操作

本脚本包会不断加入新功能，请随时关注本文档页

1. 官方巡检脚本

  1. 在观测云「管理 / API Key 管理」中创建用于进行操作的 API Key
  2. 在自建的 DataFlux Func 中，通过「脚本市场」安装「观测云智能巡检」
  3. 安装相应的巡检脚本，然后返回观测云配置参数即可

2. 自定义巡检脚本

要实现自建巡检的搭建，需要进行如下步骤：

  1. 在观测云「管理 / API Key 管理」中创建用于进行操作的 API Key
  2. 在自建的 DataFlux Func 中，通过「脚本市场」安装「观测云自建巡检 Core 核心包」
  3. 在自建的 DataFlux Func 中，编写自建巡检处理函数
  4. 在自建的 DataFlux Func 中，通过「管理 / 自动触发配置」，为所编写的函数创建自动触发配置

2.1 编写代码

一个典型的自建巡检处理函数如下：

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
from guance_monitor__register import self_hosted_monitor
from guance_monitor__event_reporter import EventReporter

API_KEY_ID  = 'xxxxx'
API_KEY     = 'xxxxx'
GUANCE_NODE = None

# 注册自建巡检
@self_hosted_monitor(API_KEY_ID, API_KEY, GUANCE_NODE)
@DFF.API('自建巡检示例')
def run(param1=1, param2=True, param3=None):
    '''
    这是一个示例自建巡检
    参数：
        param1 {int}  参数 1
        param2 {bool} 参数 2
        param3 {str}  参数 3
    '''
    # 生成事件报告器
    event_reporter = EventReporter()

    # ... 执行巡检处理，并生成数据
    event = {
        'title'  : '自建巡检示例',
        'message': f'''
            自建巡检内容支持 Markdown 格式，如：

            1. 参数`param1`值为`{param1}`
            2. 参数`param2`值为`{param2}`
            3. 参数`param3`值为`{param3}`
            ''',
        'status'        : 'error',
        'dimension_tags': { 'host': 'my_host' },
    }

    # 使用事件报告器报告事件
    event_reporter.report(event)

在脚本发布后，对应的函数即被注册到观测云，并可以在观测云平台「监控 / 智能巡检」中看到。

2.2 代码详解

以下为本例中代码的分步解释。

import 部分

为了正常使用脚本市场提供的脚本，在安装脚本包后，需要通过import方式来引入这些组件。

Python
1
2
from guance_monitor__register import self_hosted_monitor
from guance_monitor__event_reporter import EventReporter

self_hosted_monitor是自建巡检函数装饰器，添加此装饰器的函数才会被注册到观测云。

EventReporter是事件报告器，用于上报事件数据。

自建巡检注册、函数定义部分

需要注册到观测云的自建巡检，必须同时满足：

  1. 先使用@self_hosted_monitor装饰器装饰
  2. 后使用@DFF.API(...)装饰器装饰
Python
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
API_KEY_ID  = 'xxxxx'
API_KEY     = 'xxxxx'
GUANCE_NODE = None

# 注册自建巡检
@self_hosted_monitor(API_KEY_ID, API_KEY, GUANCE_NODE)
@DFF.API('自建巡检示例')
def run(param1=1, param2=True, param3=None):
    '''
    这是一个示例自建巡检
    参数：
        param1 {int}  参数 1
        param2 {bool} 参数 2
        param3 {str}  参数 3
    '''

其中：

装饰器@self_hosted_monitor需要传入在观测云「管理 / API Key 管理」创建的 API Key ID 和 API Key。

装饰器@DFF.API(...)中指定的标题，在注册后会作为自建巡检的标题出现。

函数文档中的内容，在注册后会作为自建巡检配置页面中的文档出现。

其他观测云节点

如果需要连接到非默认节点（杭州）的观测云，则需要额外传入观测云节点名参数，具体代码示例如下：

Python
1
2
3
4
5
6
API_KEY_ID  = 'xxxxx'
API_KEY     = 'xxxxx'
GUANCE_NODE = 'aws'

@self_hosted_monitor(API_KEY_ID, API_KEY, GUANCE_NODE)
# 下略 ...

GUANCE_NODE参数可选值请参考 手册 / 界面和操作 / 观测云节点 表格中的「节点」列

对于部署版观测云，可以使用完整的 URL 地址指定节点，如：

Python
1
2
3
4
GUANCE_NODE = {
    'open_api': 'http://openapi.mydomain.com',
    'openway' : 'http://openway.mydomain.com',
}

OpenAPI 访问地址和 OpenWay 访问地址都需要配置

事件部分

需要上报的事件数据为简单的dict，如：

Python
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
    event = {
        'dimension_tags': { 'host': 'my_host' },

        'status' : 'error',
        'title'  : '自建巡检示例',
        'message': f'''
            自建巡检内容支持 Markdown 格式，如：

            1. 参数`param1`值为`{param1}`
            2. 参数`param2`值为`{param2}`
            3. 参数`param3`值为`{param3}`
            ''',
    }

具体字段定义如下：

字段 类型 是否必须 说明
title str 必须 事件标题，单行纯文本
message str 必须 事件内容，支持 Markdown 基础语法
status str 必须 事件级别
可选值：info, warning, error, critical, ok
dimension_tags dict 检测维度，如：{ "host": "my_host" }

由于钉钉机器人、飞书机器人、企业微信机器人并不支持 Markdown 的全部语法，在指定 message 字段时请做好取舍

EventReporter 使用部分

事件报告器的使用非常简单，但需要注意的是，必须在函数体内部实例化EventReporter对象。

正确示例：

Python
1
2
3
4
5
6
7
8
@self_hosted_monitor(API_KEY_ID, API_KEY)
@DFF.API('自建巡检示例')
def run(param1=1, param2=True, param3=None):
    event_reporter = EventReporter() # 正确示例

    event = { ... }

    event_reporter.report(event)

错误示例：

Python
1
2
3
4
5
6
7
8
event_reporter = EventReporter() # 错误示例

@self_hosted_monitor(API_KEY_ID, API_KEY)
@DFF.API('自建巡检示例')
def run(param1=1, param2=True, param3=None):
    event = { ... }

    event_reporter.report(event)

此外，EventReporter.report(...)方法也支持一次上报多个事件，如：

Python
1
2
3
4
5
6
7
8
@self_hosted_monitor(API_KEY_ID, API_KEY)
@DFF.API('自建巡检示例')
def run(param1=1, param2=True, param3=None):
    event_reporter = EventReporter()

    events = [ { ... } ] # 多个事件数据称为数组

    event_reporter.report(events)

3. 在观测云配置自建巡检

已经注册到观测云的自建巡检函数，可以在观测云平台中进行配置运行参数、告警策略。

并且函数的文档也会一并展示，方便使用者参考。

4. 在自建 DataFlux Func 中配置自动触发配置

完成代码，并发布后，需要前往自建 DataFlux Func「管理 / 自动触发配置」，为函数创建自动触发配置后，函数才会实际运行。

自建巡检的参数在观测云中配置，「自动触发配置」中的参数指定不起作用

执行一段时间后，即可在观测云查看生成的事件。

5. 注意事项

使用自建巡检时，需要注意以下几个事项。

5.1 函数与观测云自建巡检的关联

自建 DataFlux Func 中的自建巡检函数会按照「函数 ID + DataFlux Func Secret 配置」生成关联 Key 与观测云平台的自建巡检关联。

因此，如果修改了以下任意一项，函数都会关联到不同的自建巡检上：

  • 函数名称（def xxxx部分）
  • 函数所在脚本 ID
  • 函数所在脚本集 ID
  • 不同的 DataFlux Func（即不同的 Secret）

5.2 函数注册

添加了@self_hosted_monitor装饰器的函数，在每次执行时都会尝试访问观测云并进行函数注册。

注册同时，函数的标题、文档、参数列表也会更新到观测云。

注册完成后，装饰器会从观测云下载对应自建巡检的配置（参数指定），并以自建巡检配置中指定的参数运行函数，而自动触发中配置的参数不会起作用。

5.3 在观测云禁用自建巡检

在观测云平台中可以禁用自建巡检。

但由于观测云并不能反向控制 DataFlux Func 的数据，因此自建 DataFlux Func 中的自动触发配置依然会照常执行。

函数执行后，@self_hosted_monitor装饰器会访问观测云并检查对应的自建巡检是否已被禁用，从而决定是否需要实际执行用户编写的函数。

因此在自建 DataFlux Func 中，自建巡检函数的自动触发配置始终都会运行。只在遇到对应观测云自建巡检被禁用时，立刻结束处理。

5.4 在观测云删除自建巡检

观测云中的自建巡检可以删除，但如果实际的自建巡检存在，那么只要发布或者运行，都会再次自动在观测云创建自建巡检。

同时，由于自建巡检删除后重新创建后，UUID 会发生变化，因此实际上前后两个自建巡检并不是同一个，所产生的事件之间也不会关联。

X. 附录

X.1 各 IM 平台机器人 Markdown 支持文档