1 Macro functions

Overview

Macro functions offer the ability to customize macro values.

Sometimes a macro may resolve to a value that is not necessarily easy to work with. It may be long or contain a specific substring of interest that you would like to extract. This is where macro functions can be useful.

The syntax of a macro function is:

{<macro>.<func>(<params>)}

where:

  • <macro> - the macro to customize (for example {ITEM.VALUE} or {#LLDMACRO})
  • <func> - the function to apply
  • <params> - a comma-delimited list of function parameters

Parameters must be quoted if they:

  • start with a space or double quotes
  • contain closing parentheses ")" or a comma

For example:

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

Supported macro functions

Optional function parameters are indicated by < >.

FUNCTION
Description Parameters Supported for
fmtnum (digits)
Number formatting to control the number of digits printed after the decimal point. digits - the number of digits after decimal point. Valid range: 0-20 (since Zabbix 6.0.21). No trailing zeros will be produced. {ITEM.VALUE}
{ITEM.LASTVALUE}
Expression macros
fmttime (format,<time_shift>)
Time formatting. format - mandatory format string, compatible with strftime function formatting
time_shift - the time shift applied to the time before formatting; should start with
-<N><time_unit> or +<N><time_unit>, where
N - the number of time units to add or subtract;
time_unit - h (hour), d (day), w (week), M (month) or y (year).
Since Zabbix 5.4, time_shift parameter supports multi-step time operations and may include /<time_unit> for shifting to the beginning of the time unit (/d - midnight, /w - 1st day of the week (Monday), /M - 1st day of the month, etc.). Examples:
-1w - exactly 7 days back;
-1w/w - Monday of the previous week;
-1w/w+1d - Tuesday of the previous week.
Note that time operations are calculated from left to right without priorities. For example, -1M/d+1h/w will be parsed as ((-1M/d)+1h)/w.
{TIME}
iregsub (pattern,output)
Substring extraction by a regular expression match (case insensitive). pattern - the regular expression to match
output - the output options. \1 - \9 placeholders are supported to capture groups. \0 returns the matched text.
{ITEM.VALUE}
{ITEM.LASTVALUE}
Low-level discovery macros (except in low-level discovery rule filter)
regsub (pattern,output)
Substring extraction by a regular expression match (case sensitive). pattern - the regular expression to match
output - the output options. \1 - \9 placeholders are supported to capture groups. \0 returns the matched text.
{ITEM.VALUE}
{ITEM.LASTVALUE}
Low-level discovery macros (except in low-level discovery rule filter)

If a function is used in a supported location, but applied to a macro not supporting macro functions, then the macro evaluates to 'UNKNOWN'.

If pattern is not a correct regular expression then the macro evaluates to 'UNKNOWN' (excluding low-level discovery macros where the function will be ignored in that case and macro will remain unexpanded)

Examples

The ways in which macro functions can be used to customize macro values is illustrated in the following examples on received values:

Received value Macro Output
24.3413523 {{ITEM.VALUE}.fmtnum(2)} 24.34
24.3413523 {{ITEM.VALUE}.fmtnum(0)} 24
12:36:01 {{TIME}.fmttime(%B)} October
12:36:01 {{TIME}.fmttime(%d %B,-1M/M)} 1 September
123Log line {{ITEM.VALUE}.regsub(^[0-9]+, Problem)} Problem
123 Log line {{ITEM.VALUE}.regsub("^([0-9]+)", "Problem")} Problem
123 Log line {{ITEM.VALUE}.regsub("^([0-9]+)", Problem ID: \1)} Problem ID: 123
Log line {{ITEM.VALUE}.regsub(".*", "Problem ID: \1")} ''Problem ID: ''
MySQL crashed errno 123 {{ITEM.VALUE}.regsub("^(\w+).*?([0-9]+)", " Problem ID: \1_\2 ")} '' Problem ID: MySQL_123 ''
123 Log line {{ITEM.VALUE}.regsub("([1-9]+", "Problem ID: \1")} *UNKNOWN* (invalid regular expression)
customername_1 {{#IFALIAS}.regsub("(.*)_([0-9]+)", \1)} customername
customername_1 {{#IFALIAS}.regsub("(.*)_([0-9]+)", \2)} 1
customername_1 {{#IFALIAS}.regsub("(.*)_([0-9]+", \1)} {{#IFALIAS}.regsub("(.*)_([0-9]+", \1)} (invalid regular expression)
customername_1 {$MACRO:"{{#IFALIAS}.regsub(\"(.*)_([0-9]+)\", \1)}"} {$MACRO:"customername"}
customername_1 {$MACRO:"{{#IFALIAS}.regsub(\"(.*)_([0-9]+)\", \2)}"} {$MACRO:"1"}
customername_1 {$MACRO:"{{#IFALIAS}.regsub(\"(.*)_([0-9]+\", \1)}"} {$MACRO:"{{#M}.regsub(\"(.*)_([0-9]+\", \1)}"} (invalid regular expression)
customername_1 "{$MACRO:\"{{#IFALIAS}.regsub(\\"(.*)_([0-9]+)\\", \1)}\"}" "{$MACRO:\"customername\"}"
customername_1 "{$MACRO:\"{{#IFALIAS}.regsub(\\"(.*)_([0-9]+)\\", \2)}\"}" "{$MACRO:\"1\"}")
customername_1 "{$MACRO:\"{{#IFALIAS}.regsub(\\"(.*)_([0-9]+\\", \1)}\"}" "{$MACRO:\"{{#IFALIAS}.regsub(\\"(.*)_([0-9]+\\", \1)}\"}") (invalid regular expression)
Seeing full item values

Long values of resolved {ITEM.VALUE} and {ITEM.LASTVALUE} macros for text/log items are truncated to 20 characters in some frontend locations. To see the full values of these macros you may use macro functions, e.g.:

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

See also: {ITEM.VALUE} and {ITEM.LASTVALUE} macro details.