1 宏函数

概述

宏函数提供了自定义macro值的功能(例如,缩短或提取特定子字符串),使其更易于使用。

宏函数的语法为:

{macro.func(params)}

其中:

  • macro - 要自定义的宏;
  • func - 要应用的函数(参见支持的函数);
  • params - 逗号分隔的函数参数列表,如果参数:
    • 以空格或双引号开头;
    • 包含右括号或逗号; 则必须使用双引号括起。

例如:

{{TIME}.fmttime(format,time_shift)}
       {{ITEM.VALUE}.regsub(pattern, output)}
       {{$USERMACRO}.regsub(pattern, output)}
       {{#LLDMACRO}.regsub(pattern, output)}

支持在以下位置使用宏函数:

宏函数可以在所有支持列出宏的位置使用。除非明确说明仅接受宏(例如,配置配置或低级别自动发现规则的过滤器时)。

另请参阅:宏函数

每个宏仅支持一个函数;不支持多个宏函数串联使用。

有关宏函数在其他上下文(函数、监控项键、另一个宏等)中使用的情况,请参见escaping examples

支持的函数

函数列表未包含额外信息。点击函数名称可查看完整详情。

函数 描述
btoa 将宏值编码为Base64格式。
fmtnum 数字格式化,用于控制小数点后显示的位数。
fmttime 时间格式化。
htmldecode 从HTML编码中解码宏值。
htmlencode 将宏值编码为HTML编码。
iregsub 通过正则表达式匹配提取子字符串(不区分大小写)。
lowercase 将宏值中的字符转换为小写。
regrepl 替换宏值中的字符/子字符串。
regsub 通过正则表达式匹配提取子字符串(区分大小写)。
tr 宏值字符的转写转换。
uppercase 将宏值中的字符转换为大写。
urldecode 从URL编码中解码宏值。
urlencode 将宏值编码为URL编码。

函数详情

可选函数参数由 < > 标识。

btoa

将宏值编码为Base64格式。Base64编码是一种将二进制数据表示为文本的方法,适用于在基于文本的协议中存储和安全传输二进制内容。

示例:

{{ITEM.VALUE}.btoa()} - 将把像 "zabbix" 这样的值Base64编码为 "emFiYml4"

此功能自Zabbix 7.0.4 起支持。

fmtnum(digits)

数字格式化以控制小数点后显示的位数。

参数:

  • digits - 小数点后的位数。有效范围:0-20。不会产生尾随零。

示例:

{{ITEM.VALUE}.fmtnum(2)} - 从接收到的值 "24.3483523" 将返回 "24.35"
       {{ITEM.VALUE}.fmtnum(0)} - 从接收到的值 "24.3483523" 将返回 "24"
fmttime(format,<time_shift>)

时间格式化。
请注意,此函数可与宏一起使用,前提是宏解析为以下时间格式之一的值:

  • hh:mm:ss
  • yyyy-mm-ddThh:mm:ss[tz](ISO8601 标准)
  • UNIX 时间戳

参数:

  • format - 必填格式 string,与 strftime 函数的格式兼容;
  • time_shift(可选)- 在格式化之前应用于时间的时间偏移;应以 -<N><time_unit>+<N><time_unit> 开头,其中:
    • N - 要增加或减少的时间单位数量;
    • time_unit - h(小时)、d(天)、w(周)、M(月)或 y(年)。

备注:

  • time_shift 参数支持多步时间操作,可能包含 /<time_unit>,用于将时间移至时间单位的开始 (例如:/d - 午夜,/w - 周一(周的第一天),/M - 月的第一天等)。 示例:-1w - 恰好 7 天前;-1w/w - 上周的周一;-1w/w+1d - 上周的周二。
  • 时间操作按从左到右的顺序计算,没有优先级。例如,-1M/d+1h/w 将被解析为 ((-1M/d)+1h)/w

示例:

{{TIME}.fmttime(%B)} - 将从接收到的值 "1633098961" 返回 "October"
       {{TIME}.fmttime(%d %B,-1M/M)} - 将从接收到的值 "1633098961" 返回 "1 September"
htmldecode

从HTML编码中解码宏值。此函数自Zabbix 7.0.4起受支持。

支持以下字符:

解码值
&amp; &
&lt; <
&gt; >
&quot; "
&#039; '
&#39; '

示例:

{{ITEM.VALUE}.htmldecode()} - 将类似"&lt;"的值解码为"<"
htmlencode

将宏值编码为HTML编码。此功能自Zabbix 7.0.4起支持。

支持以下字符:

编码后的值
& &amp;
< &lt;
> &gt;
" &quot;
' &#39;

示例:

{{ITEM.VALUE}.htmlencode()} - 将会把字符如 "<" 编码为 "&lt;"
iregsub(pattern,output)

通过正则表达式匹配进行子字符串提取(不区分大小写)。

参数:

  • pattern - 要匹配的正则表达式;
  • output - 输出选项。支持使用 \1 - \9 占位符来捕获组。\0 返回匹配的文本。

注释:

  • 如果正则表达式没有匹配项,该函数不返回任何内容;
  • 如果函数的模式是一个不正确的正则表达式,则宏将解析为 '未知' (低级别发现宏除外,在这种情况下,该函数将被忽略,宏将保持未解析状态);
  • 替换 string 中对不存在的捕获组的引用将被替换为空的 string。

示例:

{{ITEM.VALUE}.iregsub("fail|error|fault|problem","ERROR")} - 如果接收到 "fail""error""fault""problem" 子字符串(不区分大小写)时将解析为 "ERROR";如果没有匹配项则不返回任何内容
lowercase

将所有宏值字符转换为小写。此功能适用于单字节字符集(例如 ASCII),但不支持 UTF-8。自 Zabbix 7.0.4 起支持此功能。

示例:

{{ITEM.VALUE}.lowercase()} - 将类似 "Zabbix server" 的值转换为 "Zabbix server"(小写)
regrepl(pattern,replacement,<pattern2>,<replacement2>,...)

宏值中字符/子字符串的替换。注意,此功能仅在支持 libpcre2 库时可用。如果 Zabbix server/proxy 是使用 libpcre 编译的,则此功能将返回 UNKNOWN。此功能自 Zabbix 7.0.4 起可用。

参数:

  • pattern - 要匹配的正则表达式;
  • replacement - 替换的 string。替换字符串中支持使用 \1 - \9 占位符来捕获组。

备注:

  • 模式和替换是按顺序处理的,后续的每一对模式/替换是根据前一次替换的结果进行应用的;
  • 替换 string 中对不存在的捕获组的引用将被替换为空的 string。

示例:

{{ITEM.VALUE}.regrepl("oldParam", "newParam")} -"oldParam" 替换为 "newParam"
       {{ITEM.VALUE}.regrepl("([^a-z])","\\\1")} - 所有非字母字符将使用反斜杠进行转义
       {$THRESHOLD:"{{#FSNAME}.regrepl(\"\\$\",\"\")}"} - 将移除末尾的反斜杠(例如,将 "C:\" 替换为 "C:")
       {{ITEM.VALUE}.regrepl("_v1\.0", "_v2.0", "\(final\)", "")} - 将在 监控项 值中替换多个部分
regsub(pattern,output)

通过正则表达式匹配提取子字符串(区分大小写)。

参数:

  • pattern - 要匹配的正则表达式;
  • output - 输出选项。支持使用 \1 - \9 占位符来捕获组。\0 返回匹配的文本。

注释:

  • 如果正则表达式没有匹配项,函数将不返回任何内容;
  • 如果函数的模式是一个不正确的正则表达式,则宏将解析为 '未知' (低级别发现宏除外,在这种情况下函数将被忽略,并且宏将保持未解析状态);
  • 替换 string 中对不存在的捕获组的引用将被替换为空 string。

示例:

{{ITEM.VALUE}.regsub("^([0-9]+)", Problem ID: \1)} - 如果接收到类似 "123 Log line" 的值,将解析为 "Problem ID: 123"
       {{ITEM.VALUE}.regsub("fail|error|fault|problem","ERROR")} - 如果接收到 "fail""error""fault""problem" 子字符串(区分大小写),将解析为 "ERROR";如果没有匹配项则不返回任何内容

参见 更多示例

tr(characters,replacement)

宏值字符的转写。此功能自 Zabbix 7.0.4 起支持。

  • characters - 要替换的字符集合;
  • replacement - 按位置对应的替换字符集合。

示例:

{{ITEM.VALUE}.tr(abc, xyz)} - 将所有 "a" 替换为 "x""b" 替换为 "y""c" 替换为 "z"
       {{ITEM.VALUE}.tr(abc, xyzq)} - 将所有 "a" 替换为 "x""b" 替换为 "y""c" 替换为 "z""q" 被忽略)
       {{ITEM.VALUE}.tr(abcde, xyz)} - 将所有 "a" 替换为 "x""b" 替换为 "y""c" 替换为 "z""d" 替换为 "z""e" 替换为 "z"(即 xyzzz)
       {{ITEM.VALUE}.tr("\\\'", "\/\"")} - 将所有反斜杠替换为正斜杠,单引号替换为双引号
       {{ITEM.VALUE}.tr(A-Z,a-z)} - 将所有字母转换为小写
       {{ITEM.VALUE}.tr(0-9a-z,*)} - 将所有数字和小写字母替换为 "*"
       {{ITEM.VALUE}.tr(0-9,ab)} - 将所有 0 替换为 "a",并将所有 1、2、3、4、5、6、7、8 和 9 替换为 "b"
       {{ITEM.VALUE}.tr(0-9abcA-L,*)} - 将所有数字、"abc" 字符和 A-L 范围内的字符替换为 "*"
       {{ITEM.VALUE}.tr("\n","*")} - 将所有换行符替换为 *
       {{ITEM.VALUE}.tr("e", "\n")} - 将所有 "e" 替换为换行符

包含字面字符的方法:

反斜杠 - 必须转义为 \\
       单引号 - 必须转义为 \'
       双引号 - 必须转义为 \"

支持的反斜杠转义序列:

\\\\ => \\ - 双反斜杠转换单反斜杠
       \\a  => \a - 警报
       \\b  => \b - 退格
       \\f  => \f - 换页
       \\n  => \n - 换行
       \\r  => \r - 回车
       \\t  => \t - 水平制表符
       \\v  => \v - 垂直制表符
uppercase

将所有宏值字符转换为大写。此功能适用于单字节字符集(例如 ASCII),但不支持 UTF-8。自 Zabbix 7.0.4 起支持此功能。

示例:

{{ITEM.VALUE}.uppercase()} - 将类似 "Zabbix server" 的值转换为 "Zabbix server"(大写)
urldecode

对URL编码的宏值进行解码。此功能自Zabbix 7.0.4起受支持。

示例:

{{ITEM.VALUE}.urldecode()} - 将对类似"%2F"的值进行URL解码为"/"
urlencode

将宏值编码为URL编码格式。此功能自Zabbix 7.0.4起受支持。

示例:

{{ITEM.VALUE}.urlencode()} - 将把字符如"/"编码为"%2F"

附加示例

下表展示了使用宏函数的更多示例。

宏函数 接收到的值 输出
{{ITEM.VALUE}.regsub(^[0-9]+, Problem)} 123Log line Problem
{{ITEM.VALUE}.regsub("^([0-9]+)", "Problem")} 123 Log line Problem
{{ITEM.VALUE}.regsub(".*", "Problem ID: \1")} Log line Problem ID:
{{ITEM.VALUE}.regsub("^(\w+).*?([0-9]+)", " Problem ID: \1_\2 ")} MySQL crashed errno 123 Problem ID: MySQL\_123 
{{ITEM.VALUE}.regsub("([1-9]+", "Problem ID: \1")} 123 Log line UNKNOWN(无效的正则表达式)
{{#IFALIAS}.regsub("(.*)_([0-9]+)", \1)} customername_1 customername
{{#IFALIAS}.regsub("(.*)_([0-9]+)", \2)} customername_1 1
{{#IFALIAS}.regsub("(.*)_([0-9]+", \1)} customername_1 {{#IFALIAS}.regsub("(.*)_([0-9]+", \1)}(无效的正则表达式)
{$MACRO:"{{#IFALIAS}.regsub(\"(.*)_([0-9]+)\", \1)}"} customername_1 {$MACRO:"customername"}
{$MACRO:"{{#IFALIAS}.regsub(\"(.*)_([0-9]+)\", \2)}"} customername_1 {$MACRO:"1"}
{$MACRO:"{{#IFALIAS}.regsub(\"(.*)_([0-9]+\", \1)}"} customername_1 {$MACRO:"{{#M}.regsub(\"(.*)_([0-9]+\", \1)}"}(无效的正则表达式)
"{$MACRO:\"{{#IFALIAS}.regsub(\\"(.*)_([0-9]+)\\", \1)}\"}" customername_1 "{$MACRO:\"customername\"}"
"{$MACRO:\"{{#IFALIAS}.regsub(\\"(.*)_([0-9]+)\\", \2)}\"}" customername_1 "{$MACRO:\"1\"}"
"{$MACRO:\"{{#IFALIAS}.regsub(\\"(.*)_([0-9]+\\", \1)}\"}" customername_1 "{$MACRO:\"{{#IFALIAS}.regsub(\\"(.*)_([0-9]+\\", \1)}\"}"(无效的正则表达式)

{HEADER_81904684}

在某些前端位置,文本/日志监控项的已解析{ITEM.VALUE}和{ITEM.LASTVALUE}宏的长值会被截断为20个字符。 要查看这些宏的完整值,您可以使用宏函数,例如:

{{ITEM.VALUE}.regsub("(.*)", \1)}
       {{ITEM.LASTVALUE}.regsub("(.*)", \1)}

另请参阅:{ITEM.VALUE}和{ITEM.LASTVALUE} macro details