Zabbix Documentation 2.2

2.23.04.0 (current)In development:4.2 (devel)Unsupported:1.82.02.43.23.4

User Tools

Site Tools


manual:appendix:triggers:functions

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
manual:appendix:triggers:functions [2015/10/26 14:22]
richlv clarify that band() accepts and returns decimals, add a couple of examples
manual:appendix:triggers:functions [2018/10/31 12:50] (current)
martins-v formatting optional parameters
Line 6: Line 6:
 ^ ^  **Description** ​ ^  **Parameters** ​ ^  **Comments** ​ ^ ^ ^  **Description** ​ ^  **Parameters** ​ ^  **Comments** ​ ^
 |**abschange** ​ ^^^^ |**abschange** ​ ^^^^
-^ |The amount of absolute difference between last and previous values. ​ |  |Supported value types: float, int, str, text, log\\ \\ For example:\\ (previous value/last value=abschange)\\ 1/5=4\\ 3/1=2\\ 0/-2.5=2.5\\ \\ For strings returns:\\ 0 - values are equal\\ 1 - values differ ​ |+^ |The amount of absolute difference between last and previous values. ​ |  |Supported value types: float, int, str, text, log\\ \\ For example:\\ (previous value;last value=abschange)\\ 1;5=4\\ 3;1=2\\ 0;-2.5=2.5\\ \\ For strings returns:\\ 0 - values are equal\\ 1 - values differ ​ |
 ^ |||| ^ ||||
 |**avg** (sec<​nowiki>​|</​nowiki>#​num,<​time_shift>​) ​ ^^^^ |**avg** (sec<​nowiki>​|</​nowiki>#​num,<​time_shift>​) ​ ^^^^
 ^ |Average value of an item within the defined evaluation period. ​ |**sec** or **#num** - evaluation period in seconds or in latest collected values (preceded by a hash mark)\\ **time_shift** (optional) - evaluation point is moved the number of seconds back in time  |Supported value types: float, int\\ \\ Examples:\\ => avg(#5) -> average value for the five latest values\\ => avg(3600) -> average value for an hour\\ => avg(3600,​86400) -> average value for an hour one day ago.\\ \\ The ''​time_shift''​ parameter is supported since Zabbix 1.8.2. It is useful when there is a need to compare the current average value with the average value time_shift seconds back.  | ^ |Average value of an item within the defined evaluation period. ​ |**sec** or **#num** - evaluation period in seconds or in latest collected values (preceded by a hash mark)\\ **time_shift** (optional) - evaluation point is moved the number of seconds back in time  |Supported value types: float, int\\ \\ Examples:\\ => avg(#5) -> average value for the five latest values\\ => avg(3600) -> average value for an hour\\ => avg(3600,​86400) -> average value for an hour one day ago.\\ \\ The ''​time_shift''​ parameter is supported since Zabbix 1.8.2. It is useful when there is a need to compare the current average value with the average value time_shift seconds back.  |
 ^ |||| ^ ||||
-|**band** (sec<​nowiki>​|</​nowiki>#​num,​mask,<​time_shift>​) ​ ^^^^ +|**band** (<sec<​nowiki>​|</​nowiki>#​num>,​mask,<​time_shift>​) ​ ^^^^ 
-^ |Value of "​bitwise AND" of an item value and mask.  |**sec** (ignored) or **#num** - the Nth most recent value\\ **mask** (mandatory) - 64-bit unsigned integer (0 - 18446744073709551615)\\ **time_shift** (optional) - see avg()  |Supported value types: int\\ \\ Take note that ''#​num''​ works differently here than with many other functions (see last()).\\ \\ Although the comparison is done in a bitwise manner, all the values must be supplied and are returned in decimal. For example, checking for the 3rd bit is done by comparing to 4, not 100.\\ \\ Examples:\\ => %%band(,​12)=8 or band(,​12)=4%% -> 3rd or 4th bit set, but not both at the same time\\ => %%band(,​20)=16%% -> 3rd bit not set and 5th bit set.\\ \\ This function is supported since Zabbix 2.2.0. ​ |+^ |Value of "​bitwise AND" of an item value and mask.  |**sec** (ignored, equals #1) or **#​num** ​(optional) ​- the Nth most recent value\\ **mask** (mandatory) - 64-bit unsigned integer (0 - 18446744073709551615)\\ **time_shift** (optional) - see avg()  |Supported value types: int\\ \\ Take note that ''#​num''​ works differently here than with many other functions (see last()).\\ \\ Although the comparison is done in a bitwise manner, all the values must be supplied and are returned in decimal. For example, checking for the 3rd bit is done by comparing to 4, not 100.\\ \\ Examples:\\ => %%band(,​12)=8 or band(,​12)=4%% -> 3rd or 4th bit set, but not both at the same time\\ => %%band(,​20)=16%% -> 3rd bit not set and 5th bit set.\\ \\ This function is supported since Zabbix 2.2.0. ​ |
 ^ |||| ^ ||||
 |**change** ​ ^^^^ |**change** ​ ^^^^
-^ |The amount of difference between last and previous values. ​ |  |Supported value types: float, int, str, text, log\\ \\ For example:\\ (previous value/last value=change)\\ 1/5=+4\\ 3/1=-2\\ 0/-2.5=-2.5\\ \\ For strings returns:\\ 0 - values are equal\\ 1 - values differ ​ |+^ |The amount of difference between last and previous values. ​ |  |Supported value types: float, int, str, text, log\\ \\ For example:\\ (previous value;last value=change)\\ 1;5=+4\\ 3;1=-2\\ 0;-2.5=-2.5\\ \\ For strings returns:\\ 0 - values are equal\\ 1 - values differ ​ |
 ^ |||| ^ ||||
 |**count** (sec<​nowiki>​|</​nowiki>#​num,<​pattern>,<​operator>,<​time_shift>​) ​ ^^^^ |**count** (sec<​nowiki>​|</​nowiki>#​num,<​pattern>,<​operator>,<​time_shift>​) ​ ^^^^
-^ |Number of values within the defined evaluation period. ​ |**sec** or **#num** - evaluation period in seconds or in latest collected values (preceded by a hash mark)\\ **pattern** (optional) - required pattern ​(integer items - exact match; float items - match within 0.000001)\\ **operator** (optional)\\ \\ Supported ''​operators'':​\\ //eq// - equal\\ //ne// - not equal\\ //gt// - greater\\ //ge// - greater or equal\\ //lt// - less\\ //le// - less or equal\\ //like// - matches if contains pattern (case-sensitive)\\ //band// - bitwise AND (supported since Zabbix 2.2.0).\\ \\ Note that:\\ //eq// (default), //ne//, //gt//, //ge//, //lt//, //le//, //band// are supported for integer items\\ //eq// (default), //ne//, //gt//, //ge//, //lt//, //le// are supported for float items\\ //like// (default), //eq//, //ne// are supported for string, text and log items\\ \\ **time_shift** (optional) - see avg()  |Supported value types: float, ​intstr, text, log\\ \\ With //band// as third parameter, the second parameter can be specified as two numbers, separated by  '/':​ **number_to_compare_with/​mask**. count() calculates "​bitwise AND" from the value and the //mask// and compares the result to //​number_to_compare_with//​. If the result of "​bitwise AND" is equal to //​number_to_compare_with//,​ the value is counted.\\ If //​number_to_compare_with//​ and //mask// are equal, only the //mask// need be specified (without '/'​).\\ \\ Examples:\\ => count(600) -> number of values for last 10 minutes\\ => count(600,​12) -> number of values for last 10 minutes that equal '​12'​\\ => %%count(600,​12,​"gt")%% -> number of values for last 10 minutes that are over '​12'​\\ => %%count(#​10,​12,​"gt")%% -> number of values within last 10 values that are over '​12'​\\ => %%count(600,​12,​"gt",86400)%% -> number of values for preceding 10 minutes up to 24 hours ago that were over '​12'​\\ => %%count(600,​6/​7,​"band")%% -> number of values for last 10 minutes having '​110'​ (in binary) in the 3 least significant bits.\\ => count(600,,,​86400) -> number of values for preceding 10 minutes up to 24 hours ago\\ \\ The ''#​num''​ parameter is supported since Zabbix 1.6.1.\\ The ''​time_shift''​ parameter and string operators are supported since Zabbix 1.8.2. ​ |+^ |Number of values within the defined evaluation period. ​ |**sec** or **#num** - evaluation period in seconds or in latest collected values (preceded by a hash mark)\\ **pattern** (optional) - required pattern\\ \\ **operator** (optional)\\ \\ Supported ''​operators'':​\\ //eq// - equal\\ //ne// - not equal\\ //gt// - greater\\ //ge// - greater or equal\\ //lt// - less\\ //le// - less or equal\\ //like// - matches if contains pattern (case-sensitive)\\ //band// - bitwise AND (supported since Zabbix 2.2.0).\\ \\ Note that:\\ //eq// (default), //ne//, //gt//, //ge//, //lt//, //le//, //band// are supported for integer items\\ //eq// (default), //ne//, //gt//, //ge//, //lt//, //le// are supported for float items\\ //like// (default), //eq//, //ne// are supported for string, text and log items\\ \\ **time_shift** (optional) - see avg()  |Supported value types: float, ​integerstring, text, log\\ Float items match with the precision of 0.000001.\\ \\ With //band// as third parameter, the second parameter can be specified as two numbers, separated by  '/':​ **number_to_compare_with/​mask**. count() calculates "​bitwise AND" from the value and the //mask// and compares the result to //​number_to_compare_with//​. If the result of "​bitwise AND" is equal to //​number_to_compare_with//,​ the value is counted.\\ If //​number_to_compare_with//​ and //mask// are equal, only the //mask// need be specified (without '/'​).\\ \\ Examples:\\ => count(600) -> number of values for last 10 minutes\\ => %%count(10m,"​error",​eq)%% -> number of values for last 10 minutes that equal '​error'​\\ => count(600,​12) -> number of values for last 10 minutes that equal '​12'​\\ => %%count(600,​12,​gt)%% -> number of values for last 10 minutes that are over '​12'​\\ => %%count(#​10,​12,​gt)%% -> number of values within last 10 values that are over '​12'​\\ => %%count(600,​12,​gt,​86400)%% -> number of values for preceding 10 minutes up to 24 hours ago that were over '​12'​\\ => %%count(600,​6/​7,​band)%% -> number of values for last 10 minutes having '​110'​ (in binary) in the 3 least significant bits.\\ => count(600,,,​86400) -> number of values for preceding 10 minutes up to 24 hours ago\\ \\ The ''#​num''​ parameter is supported since Zabbix 1.6.1.\\ The ''​time_shift''​ parameter and string operators are supported since Zabbix 1.8.2. ​ |
 ^ |||| ^ ||||
 |**date** ​ ^^^^ |**date** ​ ^^^^
Line 36: Line 36:
 ^ |||| ^ ||||
 |**fuzzytime** (sec) ^^^^ |**fuzzytime** (sec) ^^^^
-^ |Checking ​if system local time is in sync with Zabbix server time.  |**sec** - seconds ​ |Supported value types: float, int\\ \\ Returns ​'​1' ​if the timestamp from item value does not differ from Zabbix server ​time for more than N seconds, 0 - otherwise. Usually used with system.localtime to check that local time is in sync with local time of Zabbix server. ​ |+^ |Checking ​how much an item timestamp value differs from the Zabbix server time.  |**sec** - seconds ​ |Supported value types: float, int\\ \\ Returns:\\ 0 - if difference between ​item timestamp ​value and Zabbix server ​timestamp is over T seconds\\ 1 - otherwise.\\ \\ Usually used with system.localtime to check that local time is in sync with local time of Zabbix server.\\ Can be used also with vfs.file.time[/​path/​file,​modify] key to check that file didn't get updates for long time.\\ \\ Example:\\ => fuzzytime(60)=0 -> detect a problem if time difference is over 60 seconds ​ |
 ^ |||| ^ ||||
-|**iregexp** (pattern,<​sec<​nowiki>​|</​nowiki>#​num>​) ​ ^^^^+|**iregexp** (<pattern>,<​sec<​nowiki>​|</​nowiki>#​num>​) ​ ^^^^
 ^ |This function is a non case-sensitive analogue of regexp(). ​ |see regexp() ​ |Supported value types: str, log, text  | ^ |This function is a non case-sensitive analogue of regexp(). ​ |see regexp() ​ |Supported value types: str, log, text  |
 ^ |||| ^ ||||
-|**last** (sec<​nowiki>​|</​nowiki>#​num,<​time_shift>​) ​ ^^^^ +|**last** (<sec<​nowiki>​|</​nowiki>#​num>,<​time_shift>​) ​ ^^^^ 
-^ |The most recent value. ​ |**sec** (ignored) or **#num** - the Nth most recent value\\ **time_shift** (optional) - see avg()  |Supported value types: float, int, str, text, log\\ \\ Take note that ''#​num''​ works differently here than with many other functions.\\ For example:\\ last() is always equal to last(#1)\\ last(#3) - third most recent value (//not// three latest values)\\ \\ Zabbix does not guarantee exact order of values if more than two values exist within one second in history.\\ \\ The ''#​num''​ parameter is supported since Zabbix 1.6.2.\\ The ''​time_shift''​ parameter is supported since Zabbix 1.8.2. ​ |+^ |The most recent value. ​ |**sec** (ignored, equals #1) or **#​num** ​(optional) ​- the Nth most recent value\\ **time_shift** (optional) - see avg()  |Supported value types: float, int, str, text, log\\ \\ Take note that ''#​num''​ works differently here than with many other functions.\\ For example:\\ last() is always equal to last(#1)\\ last(#3) - third most recent value (//not// three latest values)\\ \\ Zabbix does not guarantee exact order of values if more than two values exist within one second in history.\\ \\ The ''#​num''​ parameter is supported since Zabbix 1.6.2.\\ The ''​time_shift''​ parameter is supported since Zabbix 1.8.2. ​ |
 ^ |||| ^ ||||
-|**logeventid** (pattern) ​ ^^^^ +|**logeventid** (<pattern>)  ^^^^ 
-^ |Check if event ID of the last log entry matches a regular expression. ​ |**pattern** - regular expression describing the required pattern, [[http://​en.wikipedia.org/​wiki/​Regular_expression#​POSIX_Extended_Regular_Expressions|POSIX extended]] style. ​ |Supported value types: log\\ \\ Returns:\\ 0 - does not match\\ 1 - matches\\ \\ This function is supported since Zabbix 1.8.5. ​ |+^ |Check if event ID of the last log entry matches a regular expression. ​ |**pattern** ​(optional) ​- regular expression describing the required pattern, [[http://​en.wikipedia.org/​wiki/​Regular_expression#​POSIX_Extended_Regular_Expressions|POSIX extended]] style. ​ |Supported value types: log\\ \\ Returns:\\ 0 - does not match\\ 1 - matches\\ \\ This function is supported since Zabbix 1.8.5. ​ |
 ^ |||| ^ ||||
 |**logseverity** ​ ^^^^ |**logseverity** ​ ^^^^
 ^ |Log severity of the last log entry. ​ |  |Supported value types: log\\ \\ Returns:\\ 0 - default severity\\ N - severity (integer, useful for Windows event logs: 1 - Information,​ 2 - Warning, 4 - Error, 7 - Failure Audit, 8 - Success Audit, 9 - Critical, 10 - Verbose).\\ Zabbix takes log severity from **Information** field of Windows event log.  | ^ |Log severity of the last log entry. ​ |  |Supported value types: log\\ \\ Returns:\\ 0 - default severity\\ N - severity (integer, useful for Windows event logs: 1 - Information,​ 2 - Warning, 4 - Error, 7 - Failure Audit, 8 - Success Audit, 9 - Critical, 10 - Verbose).\\ Zabbix takes log severity from **Information** field of Windows event log.  |
 ^ |||| ^ ||||
-|**logsource** (pattern) ​ ^^^^ +|**logsource** (<pattern>)  ^^^^ 
-^ |Checking if log source of the last log entry matches parameter. ​ |**pattern** - required string ​ |Supported value types: log\\ \\ Returns:\\ 0 - does not match\\ 1 - matches\\ Normally used for Windows event logs. For example, %%logsource("​VMware Server"​)%%. ​ |+^ |Checking if log source of the last log entry matches parameter. ​ |**pattern** ​(optional) ​- required string ​ |Supported value types: log\\ \\ Returns:\\ 0 - does not match\\ 1 - matches\\ Normally used for Windows event logs. For example, %%logsource("​VMware Server"​)%%. ​ |
 ^ |||| ^ ||||
 |**max** (sec<​nowiki>​|</​nowiki>#​num,<​time_shift>​) ​ ^^^^ |**max** (sec<​nowiki>​|</​nowiki>#​num,<​time_shift>​) ​ ^^^^
Line 60: Line 60:
 ^ |||| ^ ||||
 |**nodata** (sec)  ^^^^ |**nodata** (sec)  ^^^^
-^ |Checking for no data received. ​ |**sec** - evaluation period in seconds. The period should not be less than 30 seconds. ​ |Supported value types: //any//\\ \\ Returns:\\ 1 - if no data received during the defined period of time\\ 0 - otherwise\\ \\ Note that this function will display an error if, within the period of the 1st parameter:​\\ - there'​s no data and Zabbix server was restarted\\ - there'​s no data and maintenance was completed\\ - there'​s no data and the item was added or re-enabled ​ |+^ |Checking for no data received. ​ |**sec** - evaluation period in seconds. The period should not be less than 30 seconds. ​ |Supported value types: //any//\\ \\ Returns:\\ 1 - if no data received during the defined period of time\\ 0 - otherwise\\ \\ Note that this function will display an error if, within the period of the 1st parameter:​\\ - there'​s no data and Zabbix server was restarted\\ - there'​s no data and maintenance was completed\\ - there'​s no data and the item was added or re-enabled\\ Errors are displayed in the //Info// column in trigger [[:​manual/​web_interface/​frontend_sections/​configuration/​hosts/​triggers|configuration]]. ​ |
 ^ |||| ^ ||||
 |**now** ​ ^^^^ |**now** ​ ^^^^
Line 68: Line 68:
 ^ |Previous value. ​ |  |Supported value types: float, int, str, text, log\\ \\ Returns the same as last(#​2). ​ | ^ |Previous value. ​ |  |Supported value types: float, int, str, text, log\\ \\ Returns the same as last(#​2). ​ |
 ^ |||| ^ ||||
-|**regexp** (pattern,<​sec<​nowiki>​|</​nowiki>#​num>​) ​ ^^^^ +|**regexp** (<pattern>,<​sec<​nowiki>​|</​nowiki>#​num>​) ​ ^^^^ 
-^ |Checking if the latest (most recent) value matches regular expression. ​ |**pattern** - regular expression, [[http://​en.wikipedia.org/​wiki/​Regular_expression#​POSIX_Extended_Regular_Expressions|POSIX extended]] style.\\ **sec** or **#num** (optional) - evaluation period in seconds or in latest collected values (preceded by a hash mark). In this case, more than one value may be processed. ​ |Supported value types: str, text, log\\ \\ Returns:\\ 1 - found\\ 0 - otherwise\\ \\ This function is case-sensitive. ​ |+^ |Checking if the latest (most recent) value matches regular expression. ​ |**pattern** ​(optional) ​- regular expression, [[http://​en.wikipedia.org/​wiki/​Regular_expression#​POSIX_Extended_Regular_Expressions|POSIX extended]] style.\\ **sec** or **#num** (optional) - evaluation period in seconds or in latest collected values (preceded by a hash mark). In this case, more than one value may be processed. ​ |Supported value types: str, text, log\\ \\ Returns:\\ 1 - found\\ 0 - otherwise\\ \\ If more than one value is processed, '​1'​ is returned if there is at least one matching value.\\ \\ This function is case-sensitive. ​ |
 ^ |||| ^ ||||
-|**str** (pattern,<​sec<​nowiki>​|</​nowiki>#​num>​) ​ ^^^^ +|**str** (<pattern>,<​sec<​nowiki>​|</​nowiki>#​num>​) ​ ^^^^ 
-^ |Finding a string in the latest (most recent) value. ​ |**pattern** - required string\\ **sec** or **#num** (optional) - evaluation period in seconds or in latest collected values (preceded by a hash mark). ​ In this case, more than one value may be processed. ​ |Supported value types: str, text, log\\ \\ Returns:\\ 1 - found\\ 0 - otherwise\\ \\ This function is case-sensitive. ​ |+^ |Finding a string in the latest (most recent) value. ​ |**pattern** ​(optional) ​- required string\\ **sec** or **#num** (optional) - evaluation period in seconds or in latest collected values (preceded by a hash mark). ​ In this case, more than one value may be processed. ​ |Supported value types: str, text, log\\ \\ Returns:\\ 1 - found\\ 0 - otherwise\\ \\ If more than one value is processed, '​1'​ is returned if there is at least one matching value.\\ \\ This function is case-sensitive. ​ |
 ^ |||| ^ ||||
-|**strlen** (sec<​nowiki>​|</​nowiki>#​num,<​time_shift>​) ​ ^^^^ +|**strlen** (<sec<​nowiki>​|</​nowiki>#​num>,<​time_shift>​) ​ ^^^^ 
-^ |Length of the latest (most recent) value in characters (not bytes). ​ |**sec** (ignored) or **#num** - the Nth most recent value\\ **time_shift** (optional) - see avg()  |Supported value types: str, text, log\\ \\ Take note that ''#​num''​ works differently here than with many other functions.\\ \\ Examples:\\ => strlen()(is equal to strlen(#1)) -> length of the latest value\\ => strlen(#3) -> length of the third most recent value\\ => strlen(,​86400) -> length of the most recent value one day ago.\\ \\ This function is supported since Zabbix 1.8.4. ​ |+^ |Length of the latest (most recent) value in characters (not bytes). ​ |**sec** (ignored, equals #1) or **#​num** ​(optional) ​- the Nth most recent value\\ **time_shift** (optional) - see avg()  |Supported value types: str, text, log\\ \\ Take note that ''#​num''​ works differently here than with many other functions.\\ \\ Examples:\\ => strlen()(is equal to strlen(#1)) -> length of the latest value\\ => strlen(#3) -> length of the third most recent value\\ => strlen(,​86400) -> length of the most recent value one day ago.\\ \\ This function is supported since Zabbix 1.8.4. ​ |
 ^ |||| ^ ||||
 |**sum** (sec<​nowiki>​|</​nowiki>#​num,<​time_shift>​) ​ ^^^^ |**sum** (sec<​nowiki>​|</​nowiki>#​num,<​time_shift>​) ​ ^^^^
Line 83: Line 83:
 ^ |Current time in HHMMSS format. ​ |  |Supported value types: //any//\\ \\ Example of returned value: 123055 ​ | ^ |Current time in HHMMSS format. ​ |  |Supported value types: //any//\\ \\ Example of returned value: 123055 ​ |
  
-<note important>​1) All functions return numeric values only. Comparison to strings is not supported, for example.\\ 2) Some of the functions cannot be used for non-numeric parameters!\\ 3) String arguments should be double quoted. Otherwise, they might get misinterpreted. ​ </​note>​+<note important>​1) All functions return numeric values only. Comparison to strings is not supported, for example.\\ 2) Some of the functions cannot be used for non-numeric parameters!\\ 3) String arguments should be double quoted. Otherwise, they might get misinterpreted.\\ 4) For all trigger functions **sec** and **time_shift** must be an integer with an optional [[manual:​config:​triggers:​suffixes#​trigger_expressions|time unit suffix]] and has absolutely nothing to do with item's data type.  </​note>​