跳转至

对接观测云高级函数

此功能需要 2.5.2 及以后版本

1.背景

DQL 查询支持选择高级函数。通过使用高级函数，用户可以根据需求和期望目标效果对数据进行更加深入的分析和处理。

高级函数主要用于对 DQL 查出的数据进行进一步的函数计算，并进行直观的时序图展示。观测云除了提供官方的时序处理函数之外，还支持通过本地 Func 上报自定义的数据处理函数，观测云时序图表中支持选择自定义函数对数据进行二次处理并返回数据结果显示。

中心函数由观测云算法团队持续更新，目前 v1 版本已经支持 DBSCAN 高级函数使用。

2. 准备工作

为了实现高级函数，需要做好以下准备工作：

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

3. 具体操作步骤

3.1 创建观测云连接器

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

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

3.2 编写高级函数

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

高级函数存在以下固定要求

需要在使用@DFF.API(...)装饰的基础上，添加category='guance.dqlFunc'

在 Func 中新建本地函数脚本，示例算法写法如下：

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
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
'''
高级函数示例算法

示例处理内容为：
1. 数据传入 DQL 语句
2. 返回算法处理后的结果

注意：

入口函数：AlgorithmScriptName(data,**kwargs)
    data 为 DQL 查询数据后里面'series'的结构，本地 Func 用 Dataway 取 DQL 数据，中心 Func 用 Kodo 取 DQL 数据：
    示例结构如下：
        [
            {
              'name': 'cpu',
              'tags': {'image': 'nginx'},
              'columns': ['usage_total', 'last'],
              'values': [[1681200000000, 8],[1681202880000, 23],......]
              }
              ...
           ]
    **kwargs 为算法可选参数

输出示例：
    在查询数据 data 的基础上新增算法标记字段 'status',例如在离群检查算法中返回示例如下：
        [
            {
                'status'        : "abnormal_series",
                                # 标记此条时序数据是正常还是离群，离群 status 为 "abnormal_series"，正常 status 为 "normal_series"
                'name'          : 'cpu',
                "tags"          : {'image': 'nginx'},
                'colums'        : ['usage_total', 'last'],
                "values"        : [[1681274880000,8],[1681277760000,20],……],
            },
            ...
        ]
'''

import guance__toolkit as toolkit

# 附带标签的DEBUG信息
debug = toolkit.tag_debug('高级函数')

@DFF.API('高级函数_A', category='guance.dqlFunc')
def A(data, **kwargs):
    '''
    Args:
        data: Input data.
    '''
    # 加入取数逻辑
    # 进入算法处理逻辑
    return data

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

3.3 在观测云中确认高级函数，进行选择

3.4 观测云时序图表显示样例

3.4.1 离群显示

配置后离群的效果：

如果没有离群，前端原数据展示：

3.4.2 预测显示

todo

3.4.3 异常显示

todo

4. 中心高级函数

4.1 离群算法

DBSCAN 算法介绍

DBSCAN 是一种基于密度的聚类算法。它将密度达到一定阈值的区域划分为簇，并将低密度区域视为噪声。DBSCAN算法不需要预先指定簇的数量，能够发现任意形状的簇，并且对噪声数据有较好的鲁棒性。

  • 检测对象：多条时间序列数据；
  • 传参: 检测区间 T，距离参数；
  • 返回: 返回 1 到 n 条离群时间线。

核心参数：

距离（eps）：float, default=0.5

距离参数表示其中一个样本与另一个样本相邻，两个样本之间的最大距离，不是簇内点距离的最大界限。

可选择配置 range(0-3.0) 之间的任意浮点值。如果不配置，默认距离参数为0.5，距离设置越大得到的异常点越少，距离值设置过小可能检测到的离群值非常多，距离值设置过大可能导致没有任何离群检测到，所以需要根据不同的数据特征设置合适的距离参数。

使用场景

在场景中选择时序图，点击查询下的添加函数按钮，选择高级函数 > DBSCAN，选定算法参数，视图中即可展示多条时间序列的离群效果。

DQL 写法示例

DBSCAN(M::cpu:(usage_idle) by host, 0.5)

4.2 预测算法

Prophet 算法介绍

Prophet是一种基于加法模型预测时间序列数据的程序，其中非线性趋势与年度、每周和每日的季节性以及假日效应相吻合。Prophet对缺失数据和趋势变化具有很强的鲁棒性，通常能很好地处理异常值。

  • 检测对象：单条或多条时间序列数据；
  • 传参: 检测区间 T，预测的点数，预测的频率；
  • 返回: 返回每条时间序列的预测值。

核心参数

periods：表示预测的点数。 Int number of periods to forecast forward.

freq：表示时间序列的频率 Any valid frequency for pd.date_range.

使用场景

在场景中选择时序图，点击查询下的添加函数按钮，选择高级函数 > Prophet，选定算法参数，视图中即可预测时序数据未来一段时间的趋势。

4.3 异常检测算法