创建指标模型

您可以根据实际业务场景中的指标需求，通过定义说明指标计算规则的查询语句、指标度量单位等参数，创建适于不同数据类型（支持指标数据（Metric）、链路数据（Trace）、日志数据（Log）及事件数据（Event））的指标模型，同时支持配置指标模型的持久化任务，用于实现指标数据的持久化。创建指标模型的配置流程如下：

快速阅读链接如下：

› 1. 配置指标模型基本信息

› 2. 配置指标模型模型参数

› 3. 配置指标数据持久化任务

进入数据管理 > 数据模型 > 指标模型配置页面，点击【+新建】，进入“新建指标模型”的配置流程，如下所示：

1. 配置基本信息

配置参数说明如下：

2. 配置模型信息

完成"基本配置"后，点击配置步骤条右侧的【下一步】，进入“模型配置”步骤页面，如下所示：

配置参数说明如下：

• *指标类型：在下拉框中选择指标的类型，默认为“原子指标”。原子指标可以理解为是对指标计算逻辑、具体算法的第一层抽象，皆在从根源上规范指标的定义，以保证指标的一致性。

说明：指标类型为必选项，当前仅支持配置“原子指标”。

• *日志分组：点击【设置日志分组】后，在弹出的"选择日志分组"抽屉中配置数据来源所属的日志分组。

说明：1. 日志分组为必填项。配置时，仅支持选择日志分组中的根分组，且仅支持配置1个分组；

         2. 若找不到需要的日志分组，可点击抽屉最下方的“新建日志分组”进行创建。

• *查询语言：您需根据数据源的数据类别（category）选择适用的查询语言，可选项：PromQL、DSL。具体如下：

说明：查询语言为必选项。

• *计算公式：根据上方已配置的*查询语言，填写用于说明指标计算规则的对应查询语句。配置生效后，系统会根据此处定义的计算公式进行指标计算，得到对应指标数据（请参见 预览指标数据了解详情）。

说明：计算公式为必填项。

1）当*查询语言选择“PromQL”时，需填写用于说明指标计算规则的PromQL查询语句，具体书写规范请参见《AnyRobot Eyes 5 UniQuery 开发者指南》2.3PromQL查询语言>2.3.1-2.3.4 章节，若获取此文档失败请联系相关技术支持人员。

2）当*查询语言选择“DSL”时，配置框中默认提供了计算公式（DSL语句）的预输入结构，指标模型通过此处配置的DSL语句实现对指定数据集的聚合查询操作，进而获取所需的指标数据（即返回的查询结果）。

具体配置时：

-若您所需的指标数据能够基于此预输入计算公式结构实现，您可以查阅下方› 预输入计算公式（DSL语句）配置说明，并结合实际需求修改少量参数，应用此预输入结构，快速配置所需计算公式；

-若您所需的指标数据需要基于其他聚合方式实现，您可以参考下方› 计算公式（DSL语句）基本规范说明，遵循不同聚合方式的合法格式，配置所需计算公式。

注意：此处配置的计算公式中，必须包含一层date_histogram（日期直方图）聚合和一层value_count（计数）聚合。

› 预输入计算公式（DSL语句）配置说明

配置框中提供的预输入DSL语句为嵌套的聚合结构，包括过滤查询部分、嵌套的三层聚合查询部分。基于此结构的计算公式，其查询结果将返回一个多层嵌套的数据结构，此结果包含了按照指定字段值进行分组（terms聚合）后，在每个分组内再按照时间间隔分组后（date_histogram聚合）的统计值（value_count聚合）信息，如下所示：

关于嵌套的三层聚合查询，每层聚合的查询结果说明如下：

1. 1. 1. 最外层terms聚合：按照指定字段的值对来源数据进行分组
      2. 第二层的date_histogram聚合：在每个terms分组内，按照指定时间字段对数据进行分组
      3. 第三层的value_count聚合：统计每个时间段内文件数量（事件发生次数或数据记录数量）

若您所需的指标数据能够基于此预输入计算公式结构实现，您可以参照下方的简要配置提示，或查看下方的详细配置说明，配置所需计算公式。

» 下图为预输入计算公式（DSL语句）的简要配置说明。配置时，请参考下方说明，并结合实际需求进行：

-计算公式中尖括号"<>"标识的项（红框标识）为用户自定义配置项，您需要根据实际情况直接替换修改此参数；

-系统为计算公式中的某些项（灰框标识）提供了默认参数，您可以直接应用此类参数，也可以根据实际需求修改；

-系统对计算公式中的某些项（黑框标识）有强限制配置要求，具体限制请查看下图：

» 若需要了解此预输入计算公式结构及配置限制的详细说明，请具体参考下文。配置框中提供的预输入DSL语句为嵌套的聚合结构，包括过滤查询部分、聚合查询部分。

• 过滤查询部分

• 聚合查询部分

“aggs”部分具体定义了需执行的聚合查询操作，包括三层嵌套的聚合：terms（词条）聚合、date_histogram（日期直方图）聚合、value_count（计数）聚合。terms聚合将按照<terms-field-name>.keyword字段的值对所选数据集分组。每个分组内再执行date_histogram聚合，具体按照@timestamp字段的值进行时间分组，时间分组的具体时间间隔由{{__interval}}的具体参数决定。最后，每个时间间隔内再进行value_count值聚合，用于统计每个间隔内@timestamp字段值对应的文档数量，查询指标数据。此默认嵌套聚合结构，可用于实现根据指定时间间隔（按天/周/月）对指定对象类别下某一指标的统计分析，帮助进行时间趋势相关的数据分析及可视化。

提示：您可根据实际指标需求自行定义所需的聚合方式，详情请参见支持的聚合方式。

三层嵌套聚合的详细说明如下：

› terms（词条）聚合

› date_histogram（日期直方图）聚合

› value_count (计数)聚合

› 计算公式（DSL语句）基本规范说明

上文仅对预输入框架中示意的聚合方式进行了配置说明，若实际场景中需要使用其他聚合方式，请参考OpenSearch官网文档>Aggregations章节中对应聚合方式的示例结构书写。DSL计算公式的书写需遵循DSL语句的基本语法结构（具体请参见OpenSearch官网文档）及以下特有约束。

• 聚合方式及聚合层数约束

• 当前不支持并行聚合（Multiple aggregation）查询；

• 支持的聚合方式如下：

1）分桶聚合：date_histogram（日期直方图）、terms（词条）、filters（过滤）、range（范围）、date_range（日期范围）；

2）值聚合：value_count（计数）、cardinality（去重计数）、sum（求和）、avg（均值）、max（最大值）、min（最小值）、top_hits（桶内排序取 Top N）。

• 支持配置的分桶聚合层数需≤7，值聚合层数需＝1，各层聚合的聚合名称不能重复。

• 子聚合约束

• date_histogram（日期直方图） 

• 计算公式中必须包含date_histogram，且只能有一个；

• date_histogram 分桶聚合下的子聚合类型需为值聚合。

• top_hits（桶内排序取 Top N）

• top_hits 需满足如下结构：

"size": <number>,
"sort": [
    {
        "<sort_field_name>": {
            "order": "desc | asc"
        }
    }
],
"_source": {
    "includes": [
        "<field_name1>",
        "<field_name2>",
        ......
    ]
}

校验说明：

1. 完成指标模型的配置后，点击【数据预览】/【保存】按钮，系统将对计算公式（PromQL语句/DSL语句)的合法性进行校验，校验通过后，方可预览指标数据/成功创建指标模型；

2. 当前暂不支持对查询语句中字段的权限进行校验，若查询了日志分组中不存在的字段，数据查询结果则为空。

注意：当前版本仅支持DSL的时序分析。

*度量字段：仅当*查询语言选择“DSL”时，此项可配置且为必填项，配置说明如下： 

• 当计算公式中的值聚合方式为top_hits时，此处配置的度量字段应为top_hits中_source所包含的字段名称，且此字段名称对应的字段类型应为数值字段，不兼容日期。

• 当计算公式中的值聚合方式为其他类型时，此处配置的度量字段应为公式中的值聚合名称，若配置的度量字段与值聚合名称不匹配，系统将会报错。

 说明：度量字段为必填项。

*单位类型：根据实际指标需求设置输出指标（即“度量值”）的度量单位类型，可选项包括：数值单位、存储单位、时间单位、传输速率。

*度量单位：根据实际指标需求设置输出指标（即“度量值”）的度量单位，不同单位类型下可选择的具体度量单位如下：

• 数值单位：无, 千, 百万, 十亿, 万亿,%

• 存储单位：bit(s), Byte(s), KB, MB, GB, TB, PB

• 时间单位：微秒，毫秒, 秒, 分, 时, 天, 周, 月, 年

• 传输速率：bps, Kbps, Mbps

3. 配置数据持久化任务

指标模型的数据持久化是指将指标模型查询到的指标数据存储到指定索引库中，确保数据的长期存储、保持数据历史状态，以实现基于所需指标数据在复杂场景中的计算，加速指标数据查询。

完成"模型配置"后，点击配置步骤条右侧的【下一步】进入“持久化配置”页面，如下所示：

注意：指标模型持久化配置默认为“关闭”状态，即默认不进行对应指标数据的持久化存储；

点击打开持久化配置开关“”，可以为此模型添加数据持久化任务，以便将模型查询到的指标数据存储到指定索引库中。如下所示：

注意：开启“持久化配置”后，每个指标模型仅支持添加一个持久化任务。

注意：指标模型查询语言为PromQL、DSL时，支持配置的持久化任务参数不同，具体请参见下方说明。

配置参数说明如下：

1）当查询语言为PromQL，此参数也决定了指标模型查询指标数据的时间范围。例如，当持久化步长配置为5分钟时，则每隔5分钟，指标模型将查询当前时间点前5分钟的指标数据，计算生成指标数据点，并进行持久化存储。

特殊情况说明：查询语言为PromQL时，若计算公式中使用了 irate() 函数，持久化步长与数据查询的时间范围参数有如下情况：

• • 若计算公式中的range参数设置为auto，则持久化任务查询指标数据时，持久化步长参数也决定了查询指标数据的时间范围；
  • 若计算公式中的range参数设置为常量，则持久化任务查询指标数据时，查询指标数据的时间范围由此常量决定。

2）当查询语言为DSL，此参数不影响指标模型查询指标数据的时间范围。例如，当持久化步长配置为5分钟，则每隔5分钟，指标模型将查询当前时间点前5分钟（时间范围由上方*时间窗口参数决定）的指标数据，计算生成指标数据点，并存入持久化数据。

特殊情况说明：查询语言为DSL时，若计算公式中使用了date_histogram聚合方式，持久化步长与数据查询的时间范围参数有如下情况：

• • 若计算公式中date_histogram使用了fixed_interval：
    • 若使用了变量{{_interval}}，则持久化任务在查询指标数据时，持久化任务配置的时间窗口参数决定了指标数据查询时的具体时间范围；
    • 若使用了常量，则持久化任务查询指标数据时，查询指标数据的时间范围由此常量决定。
  • 若计算公式中date_histogram使用了calendar_interval，则持久化任务查询在指标数据时，查询指标数据的时间范围由此参数决定。

• 追溯时长：追溯时长是指从当前时间向过去回退的时间长度，用于确定持久化数据的起始时间点。点击文本配置框，填写或点击“”按钮设置追溯时长，并选择其时间单位，可选单位：小时、天。例如，当追溯时长配置为“2天”，系统会从当前时间回退2天的时间点开始，并按照持久化任务配置信息，逐个步长计算历史数据点，进行数据持久化。即系统会根据持久化任务的配置信息补充前面2天的持久化数据点。

说明：追溯时长需要配置为正整数，最小单位为小时，上限为30天；完成指标模型的配置后，不支持修改此配置项。

• *执行频率：设置系统执行持久化任务的时间间隔，即持久化任务的运行频率。当前支持固定频率、Cron表达式两种配置方式，具体如下：

1）固定频率：点击文本配置框，填写或点击“”按钮配置具体时间间隔，并选择时间单位，可选单位：分钟、小时、天。例如：当固定频率设置为“每5分钟”，则此持久化任务每5分钟执行一次；

2）Cron表达式：Cron表达式是一个具有时间含义的字符串，用于计划任务。使用Cron表达式可以精准配置持久化任务的执行时间，包括持久化任务执行的具体时间点、任务执行间隔、任务执行频率。

-手动输入Cron表达式：点击文本配置框，您可以参考通用Cron语法，手动输入Cron表达式字符串，定义任务执行频率。Cron表达式以5个空格隔开，分为6个域，每个域可以是确定取值，也可以是具有逻辑意义的特殊字符。关于域取值及特殊字符的说明如下：

域取值（下表为Cron表达式中7个域允许的取值以及支持的特殊字符）

-勾选配置Cron任务：您也可以点击“”进入任务执行频率配置窗口，自行勾选Cron表达式每个域（秒/分钟/小时/日/周/月）的取值，配置窗口右上角会同步展示该执行频率对应的Cron表达式。例如：0 0 12 * * ?，表示每天中午12点执行一次。

说明：执行频率为必填项，不能为空。

• *索引库：选择存储持久化数据的索引库。

说明：索引库为必选项，不能为空。 

•  批量导入创建指标模型

进入指标模型配置页面，点击列表上方的【导入】按钮，在弹出的窗口中选中包含指标模型配置信息的文件，点击【打开】后即可批量导入并创建指标模型。

注意：

1. 仅支持导入json格式的文件；

2. 支持导入多个指标模型：导入时，若指标模型的日志分组名称不存在，则导入操作失败。您需在完成对应日志分组的创建后，再进行导入操作；若AnyRobot中存有重名的指标模型对象，则导入动作将会停止，导入操作失败；

3. 批量导入失败后，您可在审计日志中查看对应的“失败”记录。

在指标模型列表中勾选某一指标模型后，点击列表上方的【导出】按钮，可将已创建的指标模型以“.json”格式导出，可供其他场景快速应用，如下所示：

提示：支持导出多个指标模型。

指标模型创建成功后，您可以在AnyRobot其他数据模型模块和可视化分析模块引用此指标数据资源，进一步丰富数据基础，对模型定义的指标数据实现多维度、多场景的可视化指标分析、指标告警。详情请参见 指标模型应用 章节。