You are viewing documentation for the development version, it may be incomplete.
Join our translation project and help translate Zabbix documentation into your native language.

1 Macro functions

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 encoding.
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.

Function details

The syntax of a macro function is:

{macro.func(params)}
Copy
✔ Copied
  • macro - the macro to customize, for example {ITEM.VALUE} or {#LLDMACRO};
  • func - the function to apply;
  • params - a comma-delimited list of function parameters, which must be quoted if:
    • start with a space or double quotes;
    • contain closing parentheses "``" or a comma.

Optional function parameters are indicated by < >.

btoa

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:

{{ITEM.VALUE}.btoa()} - Base64-encode a value like "zabbix" into "emFiYml4"
Copy
✔ Copied

fmtnum(digits)

Number formatting to control the number of digits printed after the decimal point.

Parameters:

  • digits - the number of digits after decimal point. Valid range: 0-20. No trailing zeros will be produced.

Examples:

Macro function Received value Output
{{ITEM.VALUE}.fmtnum(2)} 24.3413523 24.34
{{ITEM.VALUE}.fmtnum(0)} 24.3413523 24

fmttime(format,<time_shift>)

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)
  • unix timestamp

Parameters:

  • format - mandatory format string, compatible with strftime function formatting;
  • time_shift (optional) - 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).

Comments:

  • The 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.
  • Time operations are calculated from left to right without priorities. For example, -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

htmldecode

Decoding a macro value from HTML encoding.

The following characters are supported:

Value Decoded value
&amp; &
&lt; <
&gt; >
&quot; "
&#039; '
&#39; '

Example:

{{ITEM.VALUE}.htmldecode()} - HTML-decode a value like "&lt;" into "<"
Copy
✔ Copied

htmlencode

Encoding a macro value into HTML encoding.

The following characters are supported:

Value Encoded value
& &amp;
< &lt;
> &gt;
" &quot;
' &#39;

Example:

{{ITEM.VALUE}.htmlencode()} - HTML-encode a character like "<" into "&lt;"
Copy
✔ Copied

iregsub(pattern,output)

Substring extraction by a regular expression match (case-insensitive).

Parameters:

  • pattern - the regular expression to match;
  • output - the output options. \1 - \9 placeholders are supported to capture groups. \0 returns the matched text.

Comments:

  • If the function pattern is an incorrect regular expression, then the macro evaluates to 'UNKNOWN' (except for low-level discovery macros, in which case the function will be ignored, and the macro will remain unresolved).

lowercase

Transformation of all macro value characters into lowercase. Works with single-byte character sets (such as ASCII) and does not support UTF-8.

Example:

{{ITEM.VALUE}.lowercase()} - transform a value like "Zabbix SERVER" into "zabbix server" (lowercase)
Copy
✔ Copied

regrepl(pattern,replacement,<pattern2>,<replacement2>,...)

Replacement of character/substring in macro value. Note that this function is only supported with the libpcre2 library. If Zabbix server/proxy was compiled with libpcre, this function will return UNKNOWN.

Parameters:

  • pattern - the regular expression to match;
  • replacement - the replacement string.

Comments:

  • The patterns and replacements are processed sequentially, with each subsequent pair being applied in accordance with the outcome of the previous replacement;
  • This function also allows referencing captured groups in replacement strings using \1 to \9 placeholders.

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
Copy
✔ Copied

regsub(pattern,output)

Substring extraction by a regular expression match (case-sensitive).

Parameters:

  • pattern - the regular expression to match;
  • output - the output options. \1 - \9 placeholders are supported to capture groups. \0 returns the matched text.

Comments:

  • If the function pattern is an incorrect regular expression, then the macro evaluates to 'UNKNOWN' (except for low-level discovery macros, in which case the function will be ignored, and the macro will remain unresolved).

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)

tr(characters,replacement)

Transliteration of macro value characters.

  • characters - the set of characters to replace;
  • replacement - the set of positionally corresponding replacement characters.

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 \"
Copy
✔ Copied

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
Copy
✔ Copied

uppercase

Transformation of all macro value characters into uppercase. Works with single-byte character sets (such as ASCII) and does not support UTF-8.

Example:

{{ITEM.VALUE}.uppercase()} - transform a value like "Zabbix Server" into "ZABBIX SERVER" (uppercase)
Copy
✔ Copied

urldecode

Decoding a macro value from URL encoding.

Example:

{{ITEM.VALUE}.urldecode()} - URL-decode a value like "%2F" into "/"
Copy
✔ Copied

urlencode

Encoding a macro value into URL encoding.

Example:

{{ITEM.VALUE}.urlencode()} - URL-encode a character like "/" into "%2F"
Copy
✔ Copied
To toggle search highlight, press Ctrl+Alt+H
Have an improvement suggestion for this page? Select the text that could be improved and press Ctrl+Enter to send it to the editors.