Macro functions offer the ability to customize macro values (for example, shorten or extract specific substrings), making them easier to work with.
All functions listed here are supported with all types of macros:
Macro functions can be used in all locations supporting the listed macros. This applies unless explicitly stated that only a macro is expected (for example, when configuring host macros or low-level discovery rule filters).
The functions are listed without additional information. Click on the function to see the full details.
Function | Description |
---|---|
btoa | Encoding macro value into Base64 format. |
fmtnum | Number formatting to control the number of digits printed after the decimal point. |
fmttime | Time formatting. |
htmldecode | Decoding macro value from HTML encoding. |
htmlencode | Encoding macro value into HTML encoding. |
iregsub | Substring extraction by a regular expression match (case-insensitive). |
lowercase | Transformation of macro value characters into lowercase. |
regrepl | Replacement of character/substring in macro value. |
regsub | Substring extraction by a regular expression match (case-sensitive). |
tr | Transliteration of macro value characters. |
uppercase | Transformation of macro value characters into uppercase. |
urldecode | Decoding macro value from URL encoding. |
urlencode | Encoding macro value into URL encoding. |
The syntax of a macro function is:
Optional function parameters are indicated by < >.
Encoding a macro value into Base64 encoding. Base64 encoding is a method for representing binary data as text, useful for storing and secure transmission of binary content over text-based protocols.
Example:
This function is supported since Zabbix 7.0.4.
Number formatting to control the number of digits printed after the decimal point.
Parameters:
Examples:
Macro function | Received value | Output |
---|---|---|
{{ITEM.VALUE}.fmtnum(2)} |
24.3413523 |
24.34 |
{{ITEM.VALUE}.fmtnum(0)} |
24.3413523 |
24 |
Time formatting.
Note that this function can be used with macros that resolve to a value in one of the following time formats:
hh:mm:ss
yyyy-mm-ddThh:mm:ss[tz]
(ISO8601 standard)Parameters:
strftime
function formatting;-<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).Comments:
time_shift
parameter supports multistep 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.-1M/d+1h/w
will be parsed as ((-1M/d)+1h)/w
.Examples:
Macro function | Received value | Output |
---|---|---|
{{TIME}.fmttime(%B)} |
12:36:01 |
October |
{{TIME}.fmttime(%d %B,-1M/M)} |
12:36:01 |
1 September |
Decoding a macro value from HTML encoding. This function is supported since Zabbix 7.0.4.
The following characters are supported:
Value | Decoded value |
---|---|
& |
& |
< |
< |
> |
> |
" |
" |
' |
' |
' |
' |
Example:
Encoding a macro value into HTML encoding. This function is supported since Zabbix 7.0.4.
The following characters are supported:
Value | Encoded value |
---|---|
& |
& |
< |
< |
> |
> |
" |
" |
' |
' |
Example:
Substring extraction by a regular expression match (case-insensitive).
Parameters:
Comments:
Transformation of all macro value characters into lowercase. Works with single-byte character sets (such as ASCII) and does not support UTF-8. This function is supported since Zabbix 7.0.4.
Example:
{{ITEM.VALUE}.lowercase()} - transform a value like "Zabbix SERVER" into "zabbix server" (lowercase)
Replacement of character/substring in macro value. This function is supported since Zabbix 7.0.4.
Parameters:
Comments:
Examples:
{{ITEM.VALUE}.regrepl("oldParam", "newParam")} - replace "oldParam" with "newParam"
{{ITEM.VALUE}.regrepl("([^a-z])","\\\1")} - escape all non-letter characters with a backslash
{{ITEM.VALUE}.regrepl("_v1\.0", "_v2.0", "\(final\)", "")} - replace multiple parts in item value
Substring extraction by a regular expression match (case-sensitive).
Parameters:
Comments:
Examples:
Macro function | Received value | Output |
---|---|---|
{{ITEM.VALUE}.regsub(^[0-9]+, Problem)} |
123Log line |
Problem |
{{ITEM.VALUE}.regsub("^([0-9]+)", "Problem")} |
123 Log line |
Problem |
{{ITEM.VALUE}.regsub("^([0-9]+)", Problem ID: \1)} |
123 Log line |
Problem ID: 123 |
{{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* (invalid regular expression) |
{{#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)} (invalid regular expression) |
{$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)}"} (invalid regular expression) |
"{$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)}\"}") (invalid regular expression) |
Transliteration of macro value characters. This function is supported since Zabbix 7.0.4.
Examples:
{{ITEM.VALUE}.tr(abc, xyz)} - replace all occurrences of "a" with "x", "b" with "y", "c" with "z"
{{ITEM.VALUE}.tr(abc, xyzq)} - replace all occurrences of "a" with "x", "b" with "y", "c" with "z" ("q" is ignored)
{{ITEM.VALUE}.tr(abcde, xyz)} - replace all occurrences of "a" with "x", "b" with "y", "c" with "z", "d" with "z", "e" with "z" (i.e. xyzzz)
{{ITEM.VALUE}.tr("\\\'", "\/\"")} - replace all occurrences of backslash with forward slash, ' with "
{{ITEM.VALUE}.tr(A-Z,a-z)} - convert all letters to lowercase
{{ITEM.VALUE}.tr(0-9a-z,*)} - replace all numbers and lowercase letters with "*"
{{ITEM.VALUE}.tr(0-9,ab)} - replace all occurrences of 0 with "a", and replace all occurrences of 1, 2, 3, 4, 5, 6, 7, 8, and 9 with "b"
{{ITEM.VALUE}.tr(0-9abcA-L,*)} - replace all numbers, "abc" characters, and A-L range with "*"
{{ITEM.VALUE}.tr("\n","*")} - replace end-of-line occurrences with *
{{ITEM.VALUE}.tr("e", "\n")} - replace all "e" to end-of-line
To include literal characters:
backslash - must be escaped as \\
single quote - must be escaped as \'
double quote - must be escaped as \"
Supported escape sequences with backslash:
\\\\ => \\ - double backslash to single backslash
\\a => \a - alert
\\b => \b - backspace
\\f => \f - form feed
\\n => \n - newline
\\r => \r - return
\\t => \t - horizontal tab
\\v => \v - vertical tab
Transformation of all macro value characters into uppercase. Works with single-byte character sets (such as ASCII) and does not support UTF-8. This function is supported since Zabbix 7.0.4.
Example:
{{ITEM.VALUE}.uppercase()} - transform a value like "Zabbix Server" into "ZABBIX SERVER" (uppercase)
Decoding a macro value from URL encoding. This function is supported since Zabbix 7.0.4.
Example:
Encoding a macro value into URL encoding. This function is supported since Zabbix 7.0.4.
Example: