公式运算符和函数

可以在 Formula Editor 中使用的公式运算符和函数的参考（包括示例）。

派生的属性值是根据同一数据源中的常量和其他属性值对表达式求值的结果。表达式语法是常规数学表达式 - 操作数运算符操作数（以及用于分组的圆括号）。通过使用一般数学运算符 +、-、*、/ 和 % 来组合数字属性和其他数字属性或常量，% 用于将左操作数乘以 100，然后再除以右操作数。可使用 + 将字符串属性与其他字符串属性或常量组合。还可以使用以下描述的函数。使用以下格式输入函数：function_name(argument_1, argument_2, argument_3)。

属性通过其名称表示（与您在“数据源”信息树中看到的名称相同）。整数常量指定为数字。字符串常量用引号括起。

可以在公式中使用以下函数：

abs

返回某个数字的绝对值

atof

将字符串转换为浮点值

atoi

将字符串转换为整数值。其运算方法与一般 C atoi 的工作原理相同：在第一个非十进制字符处停止。

average

返回单个值，该值是一组值中的平均值。这组值来自函数的自变量。可以提供多个单独的值（例如属性名称或常量），每个值位于单独的自变量中。或者，也可将 last 函数作为此函数的唯一自变量（以计算属性的最近值的平均值）。

此函数的使用示例包括：

average (Attr_A, AttrB, Attr_C)

average (last (Attr_A, 10))

ceiling

返回不小于自变量的最小整数。

例如，如果 attribute_a = 12.4，那么 ceiling(attribute_a) 返回值 13。如果 attribute_a = -12.4，那么 ceiling(attribute_a) 返回值 -12。

delta

属性的最新值与先前针对该属性收集到的某个值的差。delta 的单一自变量必须是 last 函数，后者用于获取属性的当前值和先前值。常规用法如下所示：

delta (last(OtherAttribute, 2))

有关使用 last 函数中的哪些属性值来计算 delta 的更多信息，请参阅特定于区间的计算。此函数仅适用于派生属性，而不适用于属性组过滤器。

floor

返回不大于自变量的最大整数。

例如，如果 attribute_a = 12.4，那么 floor(attribute_a) 返回值 12。如果 attribute_a =-12.4，那么 floor(attribute_a) 返回值 -13。

getenv

返回提供的环境或“配置变量”的值。

ipAddressToName

将 IP 地址转换为主机名。此函数需要一个自变量（采用点分十进制表示法的 IP 地址字符串）。如果无法解析该地址，那么会返回 IP 地址。

itoa

将整数转换为字符串。当您想要将数字值连接成字符串时，此函数非常有用。派生字符串 + 函数仅采用两个字符串自变量。

last

返回一列值以供 min、max、average、stddev、rate 和 delta 函数使用。它采用两个自变量：要收集的属性以及要在计算中使用的值的数量。如果所需的属性是“用字符串表示的整数值”属性，那么第一个自变量可包含 atoi 函数，例如 atoi(numericalStringAttribute)。第二个自变量必须为数字。它可以硬编码为常量，也可以是 atoi(getenv("ENV_VAR")) 表达式的结果。它不能引用任何属性值。

此函数的使用示例包括：

average (last (Attr_A, 10))

last (Attribute_A, ${K01_NUM_COLLECTIONS}))

限制：在特定公式中，只能使用一次 last 函数。

matches

返回布尔值 true 或 false，以指示正则表达式是否与某个值匹配。此函数采用两个自变量，即字符串源以及结果要与此字符串进行比较的正则表达式。此函数对于过滤属性组而言非常有用。

max

返回单个值，该值是一组值中的最大值。这组值来自函数的自变量。可以提供多个单独的值（例如属性名称或常量），每个值位于单独的自变量中。或者，也可将 last 函数作为此函数的唯一自变量（以计算属性的最近值的最大值）。

min

返回单个值，该值是一组值中的最小值。这组值来自函数的自变量。可以提供多个单独的值（例如属性名称或常量），每个值位于单独的自变量中。或者，也可将 last 函数作为此函数的唯一自变量（以计算属性的最近值的最小值）。

nameToIpAddress

将主机名转换为 IP 地址。此函数需要一个自变量，即主机名字符串。如果无法解析该地址，那么会返回主机名。

NetWareTimeToTivoliTimestamp

将 Novell NetWare 十六进制时间值转换为 Tivoli® Monitoring 时间戳记。此函数需要一个自变量，即一个特殊的 NetWare 十六进制时间值。属性类型为时间戳记。

rate

属性的最新值与先前针对该属性收集到的某个值的变化率（每秒）。rate 的单一自变量必须是 last 函数，后者用于获取属性的当前值和先前值。常规用法如下所示：

rate (last(OtherAttribute, 2))

有关使用 last 函数中的哪些属性值来计算 rate 的更多信息，请参阅特定于区间的计算。此函数仅适用于派生属性，而不适用于属性组过滤器。

replaceFirst

将匹配正则表达式的第一个子串替换为替换字符串。此函数采用三个自变量。第一个：输入字符串。第二个：用于匹配输入字符串中的子串的正则表达式。第三个：替换字符串。有关正则表达式和替换字符串中允许使用的替换值的详细信息，请参阅（ICU 正则表达式）。

replaceAll

将匹配正则表达式的所有子串替换为替换字符串。此函数采用三个自变量。第一个：输入字符串。第二个：用于匹配输入字符串中的子串的正则表达式。第三个：替换字符串。有关正则表达式和替换字符串中允许使用的替换值的详细信息，请参阅（ICU 正则表达式）。

round

将数字四舍五入至最近的整数。

sqrt

返回数字的平方根

stddev

返回单个值，该值是一组值的标准差。这组值来自函数的自变量。可以提供多个单独的值（例如属性名称或常量），每个值位于单独的自变量中。或者，也可将 last 函数作为此函数的唯一自变量（以计算属性的最近值的标准差）。

StringToTivoliTimestamp

将日期和时间字符串转换为 Tivoli Monitoring 时间戳记。此函数需要两个自变量。第一个自变量是以自由格式字符串表示的时间戳记。第二个自变量是识别如何解析以自由格式字符串表示的时间戳记的格式字符串。（表 1）描述了有效格式参数。属性类型为时间戳记。

表 1. StringToTivoliTimestamp 的有效格式参数
符号	含义	格式	示例
`y`	年份	`yy` `yyyy`	`96` `1996`
`M`	月份注：仅支持以英语表示的月份字符串。	`M` 或 `MM` `MMM` `MMMM`	`09` `Sept` `September`
`d`	`日期`	`d` `dd`	`2` `02`
`E`	周历日注：仅支持以英语表示的周历日字符串。	`EE` `EEE` `EEEE`	`Sa` `Sat` `Saturday`
`h`	以 AM 或 PM 表示的钟点 (1-12)	`hh`	`07`
`H`	一天中的钟点 (0-23)	`HH`	`00`
`m`	小时中的分钟	`mm`	`04`
`s`	分钟中的秒	`ss`	`05`
`S`	毫秒	`S` `SS` `SSS`	`2` `24` `245`
`a`	AM 或 PM 标记	`a` 或 `aa`	`am`
任何其他 ASCII 字符	跳过此字符	`-`（连字符）（空格） `/`（正斜杠） `:`（冒号） `*`（星号） `,`（逗号）

表 2 提供了时间戳记的字符串表示和用于解析它们的格式字符串。

表 2. StringToTivoliTimestamp 示例. 下表列出并说明了时间戳记字符串表示的一些示例
时间戳记的字符串表示	格式字符串
`96.07.10 at 15:08:56`	`yy.MM.dd ** HH:mm:ss`
`Wed, August 10, 2010 12:08 pm`	`EEE, MMMM dd, yyyy hh:mm a`
`Thu 21/01/2010 14:10:33.17`	`EEE dd/MM/yyyy HH:mm:ss.SS`

sum

返回单个值，该值是一组值的总和。这组值来自函数的自变量。可以提供多个单独的值（例如特性名称或常量），每个值位于单独的自变量中。或者，也可将 last 函数作为此函数的唯一自变量（以计算特性的最近值的总和）。

TivoliLogTimeToTivoliTimestamp

将 Tivoli 日志文件时间戳记转换为 Tivoli Monitoring 时间戳记。此函数需要一个自变量，即来自 Tivoli 日志文件的字符串时间戳记。特性类型为时间戳记。

tokenize

标记化的字符串的一个标记。此函数需要三个自变量。第一个自变量是要分割成标记的字符串。第二个自变量给出该字符串中用于分隔各个标记的一个或多个字符。任何时候出现此自变量中的任意字符时，都将用于识别和分隔第一个自变量中的标记。第三个自变量是要作为此函数结果返回的标记的索引。第一个标记为 index 0，第二个标记为 index 1，以此类推。此自变量还可以是返回最后一个标记的字符串 LAST。

UTCtoGMT

将世界标准时间转换为 GMT Tivoli Monitoring 时间戳记。此函数需要一个自变量，即整数 time_t 值。特性类型为时间戳记。

UTCtoLocalTime

将世界标准时间转换为本地 Tivoli Monitoring 时间戳记。此函数需要一个自变量，即整数 time_t 值。特性类型为时间戳记。

以下函数不采用任何自变量并返回数字。

count

保留一个计数器，首次调用时，起始值为 1，之后每调用一次，值递增 1。如果在同时使用 last 的表达式中使用该函数，它将与 last() 存储的元素数目匹配，但此过程仅持续到 last() 达到其最大值。此时，每增加一个新值，last() 就将删除最旧的值，从而保持值总数不变，而 count() 的值会不断增加。

cumulativeSum

返回由流量控制摘要事件表示的重复事件的自变量值总和。或者如果自变量是来自数据源的单个事件，返回该自变量。它采用单一数字自变量。此函数仅适用于开启了事件过滤和摘要功能的事件属性组。

eventThreshold

返回为生成事件的属性组配置的阈值。这是一个数字，具有以下三个枚举值：

SEND_ALL (-3)
SEND_FIRST (-2)
SEND_NONE (-1)

括号中的数字是原始值。但是，Agent Builder 会定义枚举，这样在缺省情况下，文本版本在 Tivoli Enterprise Portal 或 IBM® Cloud Application Performance Management 控制台中可见。如果您指定了一个实际的数字阈值，且并非上述三个预定义选项之一，那么此函数将返回该数字。该值是大于 0 的整数。此函数仅适用于开启了事件过滤和摘要功能的事件属性组。

isSummaryEvent

如果是来自数据源的单个事件，那么返回 0，如果事件是流量控制摘要事件，那么返回 1。如果对该函数使用缺省特性，那么显示的值是 Event 和 Summary Event。如果手动创建特性，那么除非您将名称定义为枚举值，否则显示的值是 0 和 1。此函数仅适用于开启了事件过滤和摘要功能的事件属性组。

occurrenceCount

返回由流量控制摘要事件表示的匹配事件数，如果是来自数据源的单个事件，那么返回 1。（流量控制摘要事件包括第一个事件）。此函数仅适用于开启了事件过滤和摘要功能的事件属性组。

summaryInterval

返回为生成事件的属性组配置的摘要时间间隔（以秒为单位）。此函数仅适用于开启了事件过滤和摘要功能的事件属性组。

示例

使用公式运算符和函数创建派生特性和过滤特性的示例

示例 1 - 派生特性

如果您拥有定义了以下特性类型的数据源：

名称	字符串
`xBytes`	数字
`yBytes`	数字
`Virtual_Size`	数字

您可以定义：

用于表示 xbytes 和 ybytes 之和的特性 totalbytes。输入公式 xBytes + yBytes。
表示 yBytes 占字节总数百分比的特性 yPercent，可以定义为 yBytes % (xBytes + yBytes) 或 yBytes % totalBytes。

示例 2 - 派生特性

以下公式返回 Virtual_Size 特性的最近收集值中的最大值。收集的样本数是配置变量 K4P_COLLECTIONS_PER_HISTORY_INTERVAL（通过 getenv 访问）的值，该值将（通过 atoi）转换为数字：


max(last(Virtual_Size,atoi(getenv("K4P_COLLECTIONS_PER_HISTORY_INTERVAL"))))

示例 3 - 派生特性

以下公式返回 xbytes 和 ybytes 特性值的平方总和的平方根：

sqrt(xBytes * xBytes + yBtyes * yBytes)

示例 4 - 派生特性

以下公式返回属性组的最近 20 个样本中 xBytes 特性的平均值。如果自代理程序启动以来收集的样本数少于 20，那么它将返回所有样本中 xBytes 特性的平均值：

average(last(xBytes,20))

示例 5 - 过滤特性

您的数据源返回下列数据：

Name    Type  Size  Used  Free 
Memory  MEM      8     4     4
Disk1   DISK   300   200   100
Disk2   DISK   500   100   400

您只对磁盘使用情况感兴趣。解决方案是创建过滤器以限制返回的数据。要限制返回的数据，您可以创建返回布尔值 true 或 false 的简单过滤器，如下所示

磁盘过滤器：

Type=="DISK"

现在，当过滤器 Type=="DISK" 为 true 时，此属性组仅返回磁盘使用情况数据，例如：

Name    Type   Size  Used  Free 
Disk1   DISK   300   200   100
Disk2   DISK   500   100   400

示例 6 - 过滤属性

您的数据源返回下列数据：

Name   Size  Used  Free 
Memory    8     4     4
Disk1   300   200   100
Disk2   500   100   400

返回的数据与上一示例相似，但这次没有 Type 属性。在这里，您可以使用 matches 函数来查找名称属性值与 "Disk" 后跟一个数字匹配的任何数据行。

磁盘过滤器：

matches(Name, "Disk[0-9]*")

现在，仅当此过滤器在属性 Name 中与字符串 "Disk" 后跟一个数字匹配时，才会返回磁盘使用情况数据行：

Name   Size  Used  Free 
Disk1   300   200   100
Disk2   500   100   400