Zabbix Documentation 4.2

3.04.04.4 (current)| In development:5.0 (devel)| Unsupported:1.82.02.22.43.23.44.2Guidelines

User Tools

Site Tools


manual:discovery:low_level_discovery

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
Next revision Both sides next revision
manual:discovery:low_level_discovery [2019/02/04 10:04]
martins-v removing some possibly redundant information
manual:discovery:low_level_discovery [2019/03/28 13:45]
martins-v formatting fix
Line 21: Line 21:
 Built-in discovery keys have been updated to return an array of LLD rows at the root of JSON document. Zabbix will automatically extract a macro and value if an array field uses the {#MACRO} syntax as a key. Any new native discovery checks will use the new syntax without the %%"​%%data%%"​%% elements. When processing a low-level discovery value first the root is located (array at ''​$.''​ or ''​$.data''​). ​ Built-in discovery keys have been updated to return an array of LLD rows at the root of JSON document. Zabbix will automatically extract a macro and value if an array field uses the {#MACRO} syntax as a key. Any new native discovery checks will use the new syntax without the %%"​%%data%%"​%% elements. When processing a low-level discovery value first the root is located (array at ''​$.''​ or ''​$.data''​). ​
  
-While the %%"​%%data%%"​%% element has been removed from all native items related to discovery, for backward compatibility Zabbix will still accept the now deprecated ​JSON notation with a %%"​%%data%%"​%% element. If the JSON contains an object with only one %%"​%%data%%"​%% array element, then it will automatically extract the content of the element using JSONPath ''​$.data''​. Low-level discovery now accepts optional user-defined LLD macros with a custom path specified in JSONPath syntax.+While the %%"​%%data%%"​%% element has been removed from all native items related to discovery, for backward compatibility Zabbix will still accept the JSON notation with a %%"​%%data%%"​%% element, though its use is discouraged. If the JSON contains an object with only one %%"​%%data%%"​%% array element, then it will automatically extract the content of the element using JSONPath ''​$.data''​. Low-level discovery now accepts optional user-defined LLD macros with a custom path specified in JSONPath syntax.
  
 <note warning>​As a result of the changes above, newer agents no longer will be able to work with an older Zabbix server.</​note>​ <note warning>​As a result of the changes above, newer agents no longer will be able to work with an older Zabbix server.</​note>​
Line 57: Line 57:
 ^Parameter^Description^ ^Parameter^Description^
 |//​Name// ​ |Name of discovery rule.  | |//​Name// ​ |Name of discovery rule.  |
-|//​Type// ​ |The type of check to perform discovery; should be //Zabbix agent// or //Zabbix agent (active)// for file system discovery. ​ | +|//​Type// ​ |The type of check to perform discovery; should be //Zabbix agent// or //Zabbix agent (active)// for file system discovery.\\ The discovery rule can also be a [[:​manual/​config/​items/​itemtypes/​dependent_items|dependent item]], depending on a regular item. It cannot depend on another discovery rule. For a dependent item, select the respective type (//​Dependent item//) and specify the master item in the '​Master item' field. The master item must exist.  | 
-|//​Key// ​ |An item with "​vfs.fs.discovery"​ key is built into Zabbix agent since version 2.0 on many platforms (see [[manual:​appendix:​items:​supported_by_platform|supported item key list]] for details), and will return a JSON with the list of file systems present on the computer and their types. ​ |+|//​Key// ​ |An item with "​vfs.fs.discovery"​ key is built into Zabbix agent on many platforms (see [[manual:​appendix:​items:​supported_by_platform|supported item key list]] for details), and will return a JSON with the list of file systems present on the computer and their types. ​ |
 |//Update interval// ​ |This field specifies how often Zabbix performs discovery. In the beginning, when you are just setting up file system discovery, you might wish to set it to a small interval, but once you know it works you can set it to 30 minutes or more, because file systems usually do not change very often.\\ [[:​manual/​appendix/​suffixes|Time suffixes]] are supported, e.g. 30s, 1m, 2h, 1d, since Zabbix 3.4.0.\\ [[:​manual/​config/​macros/​usermacros|User macros]] are supported, since Zabbix 3.4.0.\\ //Note//: If set to '​0',​ the item will not be polled. However, if a flexible interval also exists with a non-zero value, the item will be polled during the flexible interval duration.\\ ​ //Note// that for an existing discovery rule the discovery can be performed immediately by pushing the //Check now// [[#​form_buttons|button]]. | |//Update interval// ​ |This field specifies how often Zabbix performs discovery. In the beginning, when you are just setting up file system discovery, you might wish to set it to a small interval, but once you know it works you can set it to 30 minutes or more, because file systems usually do not change very often.\\ [[:​manual/​appendix/​suffixes|Time suffixes]] are supported, e.g. 30s, 1m, 2h, 1d, since Zabbix 3.4.0.\\ [[:​manual/​config/​macros/​usermacros|User macros]] are supported, since Zabbix 3.4.0.\\ //Note//: If set to '​0',​ the item will not be polled. However, if a flexible interval also exists with a non-zero value, the item will be polled during the flexible interval duration.\\ ​ //Note// that for an existing discovery rule the discovery can be performed immediately by pushing the //Check now// [[#​form_buttons|button]]. |
 |//Custom intervals// ​ |You can create custom rules for checking the item:\\ **Flexible** - create an exception to the //Update interval// (interval with different frequency)\\ **Scheduling** - create a custom polling schedule.\\ For detailed information see [[manual:​config:​items:​item:​custom_intervals|Custom intervals]]. Scheduling is supported since Zabix 3.0.0. ​ | |//Custom intervals// ​ |You can create custom rules for checking the item:\\ **Flexible** - create an exception to the //Update interval// (interval with different frequency)\\ **Scheduling** - create a custom polling schedule.\\ For detailed information see [[manual:​config:​items:​item:​custom_intervals|Custom intervals]]. Scheduling is supported since Zabix 3.0.0. ​ |
-|//Keep lost resources period// ​ |This field allows you to specify the duration for how long the discovered entity will be retained (won't be deleted) once its discovery status becomes "Not discovered anymore"​ (min 1 hour, max 25 years).\\ [[:​manual/​appendix/​suffixes|Time suffixes]] are supported, e.g. 2h, 1d, since Zabbix 3.4.0.\\ [[:​manual/​config/​macros/​usermacros|User macros]] are supported, since Zabbix 3.4.0.\\ //Note:// If set to "​0",​ entities will be deleted immediately. Using "​0"​ is not recommended,​ since just wrongly editing the filter may end up in the entity being deleted with all the historical data.   |+|//Keep lost resources period// ​ |This field allows you to specify the duration for how long the discovered entity will be retained (won't be deleted) once its discovery status becomes ​%%"%%Not discovered anymore%%"%% (between ​1 hour to 25 years; or %%"​%%0%%"​%%).\\ [[:​manual/​appendix/​suffixes|Time suffixes]] are supported, e.g. 2h, 1d, since Zabbix 3.4.0.\\ [[:​manual/​config/​macros/​usermacros|User macros]] are supported, since Zabbix 3.4.0.\\ //Note:// If set to %%"%%0%%"%%, entities will be deleted immediately. Using %%"%%0%%"%% is not recommended,​ since just wrongly editing the filter may end up in the entity being deleted with all the historical data.   |
 |//​Description// ​ |Enter a description. ​ | |//​Description// ​ |Enter a description. ​ |
 |//​Enabled// ​ |If checked, the rule will be processed. ​ | |//​Enabled// ​ |If checked, the rule will be processed. ​ |
Line 71: Line 71:
 The **Preprocessing** tab allows to define transformation rules to apply to the result of discovery. One or several transformations are possible in this step. Transformations are executed in the order in which they are defined. All preprocessing is done by Zabbix server. The **Preprocessing** tab allows to define transformation rules to apply to the result of discovery. One or several transformations are possible in this step. Transformations are executed in the order in which they are defined. All preprocessing is done by Zabbix server.
  
-{{manual:​discovery:​low_level_discovery:​lld_rule_fs1b.png?600|}}+{{manual:​discovery:​low_level_discovery:​lld_rule_fs2b.png?600|}}
  
 ^Type^Transformation^Description^ ^Type^Transformation^Description^
 |  ||| |  |||
 ^Text  ^^^ ^Text  ^^^
-|   ​|//​Regular expression// ​ |Match the received value to the <​pattern>​ regular expression and replace value with the extracted <​output>​. The regular expression supports extraction of maximum 10 captured groups with the \N sequence.\\ Parameters:​\\ **pattern** - regular expression\\ **output** - output formatting template. An \N (where N=1…9) escape sequence is replaced with the Nth matched group. A \0 escape sequence is replaced with the matched text.\\ Please refer to [[manual:​regular_expressions#​example|regular expressions]] section for some existing examples.\\ If you mark the //Custom on fail// checkbox, it is possible to specify custom error handling options: either to discard the value, set a specified value or set a specified error message. ​ |+|   ​|//​Regular expression// ​ |Match the received value to the <​pattern>​ regular expression and replace value with the extracted <​output>​. The regular expression supports extraction of maximum 10 captured groups with the \N sequence.\\ Parameters:​\\ **pattern** - regular expression\\ **output** - output formatting template. An \N (where N=1…9) escape sequence is replaced with the Nth matched group. A \0 escape sequence is replaced with the matched text.\\ If you mark the //Custom on fail// checkbox, it is possible to specify custom error handling options: either to discard the value, set a specified value or set a specified error message. ​ |
 ^Structured data  ^^^ ^Structured data  ^^^
-|   |//JSON Path//  |Path that is used to extract LLD macro value from a LLD row, using JSONPath syntax.\\ For example, ''​$.foo''​ will extract %%"​%%bar%%"​%% and %%"​%%baz%%"​%% from this JSON: ''​[{%%"​%%foo%%"​%%:​%%"​%%bar%%"​%%},​ {%%"​%%foo%%"​%%:​%%"​%%baz%%"​%%}]''​\\ JSONPath can be specified using the dot notation or the bracket notation. Bracket notation should be used in case of any special characters and Unicode, like ''​$['​unicode + special chars #​1'​]['​unicode + special chars #​2'​]''​.\\ If you mark the //Custom on fail// checkbox, it is possible to specify custom error handling options: either to discard the value, set a specified value or set a specified error message. ​ |+|   |//JSONPath//  |Path that is used to extract LLD macro value from a LLD row, using JSONPath syntax.\\ For example, ''​$.foo''​ will extract %%"​%%bar%%"​%% and %%"​%%baz%%"​%% from this JSON: ''​[{%%"​%%foo%%"​%%:​%%"​%%bar%%"​%%},​ {%%"​%%foo%%"​%%:​%%"​%%baz%%"​%%}]''​\\ JSONPath can be specified using the dot notation or the bracket notation. Bracket notation should be used in case of any special characters and Unicode, like ''​$['​unicode + special chars #​1'​]['​unicode + special chars #​2'​]''​.\\ If you mark the //Custom on fail// checkbox, it is possible to specify custom error handling options: either to discard the value, set a specified value or set a specified error message.  | 
 +^Custom scripts ​ ^^^ 
 +|   ​|//​JavaScript// ​ |Enter JavaScript code in the block that appears when clicking in the parameter field or on //Open//.\\ Note that available JavaScript length depends on the [[:​manual/​config/​items/​item#​custom_script_limit|database used]].  |
 ^Validation ​ ^^^ ^Validation ​ ^^^
-|   ​|//​Does not match regular expression// ​ |Specify a regular expression that a value must not match.\\ E.g. Pattern: ​''​%%Error:​(.*?​)\.%%''​, Output: ''​%%"​Exiting,​ error found: '​\1'​."​%%''​. If a match is found, error with message specified in //Output// is returned. If no match, unmodified value is processed further.\\ If you mark the //Custom on fail// checkbox, it is possible to specify custom error handling options: either to discard the value, set a specified value or set a specified error message. ​ |+|   ​|//​Does not match regular expression// ​ |Specify a regular expression that a value must not match.\\ E.g. ''​%%Error:​(.*?​)\.%%''​\\ If you mark the //Custom on fail// checkbox, it is possible to specify custom error handling options: either to discard the value, set a specified value or set a specified error message. ​ |
 |:::​|//​Check for error in JSON// ​ |Check for an application-level error message located at JSONpath. Stop processing if succeeded and message is not empty; otherwise continue processing with the value that was before this preprocessing step. Note that these external service errors are reported to user as is, without adding preprocessing step information.\\ E.g. ''​$.errors''​. If a JSON like ''​%%{"​errors":"​e1"​}%%''​ is received, the next preprocessing step will not be executed. ​ | |:::​|//​Check for error in JSON// ​ |Check for an application-level error message located at JSONpath. Stop processing if succeeded and message is not empty; otherwise continue processing with the value that was before this preprocessing step. Note that these external service errors are reported to user as is, without adding preprocessing step information.\\ E.g. ''​$.errors''​. If a JSON like ''​%%{"​errors":"​e1"​}%%''​ is received, the next preprocessing step will not be executed. ​ |
 ^Throttling ​ ^^^ ^Throttling ​ ^^^
-|   ​|//​Discard unchanged with heartbeat// ​ |Discard a value if it has not changed within the defined time period (in seconds).\\ Positive integer values are supported to specify the seconds (minimum - 1 second). Time suffixes can be used in this field (e.g. 30s, 1m, 2h, 1d). User macros and low-level discovery macros can be used in this field.\\ Only one throttling option can be specified for a discovery item.\\ E.g. ''​10''​. If identical text is passed into this rule twice within ​10 seconds, ​further processing ​will not be executed.  |+|   ​|//​Discard unchanged with heartbeat// ​ |Discard a value if it has not changed within the defined time period (in seconds).\\ Positive integer values are supported to specify the seconds (minimum - 1 second). Time suffixes can be used in this field (e.g. 30s, 1m, 2h, 1d). User macros and low-level discovery macros can be used in this field.\\ Only one throttling option can be specified for a discovery item.\\ E.g. ''​1m''​. If identical text is passed into this rule twice within ​60 seconds, ​it will be discarded.\\ //Note//: Changing item prototypes does not reset throttling. Throttling is reset only when preprocessing steps are changed. ​ | 
 +^Prometheus ​ ^^^ 
 +|   ​|//​Prometheus to JSON// ​ |Convert required Prometheus metrics to JSON.\\ See [[:​manual/​config/​items/​itemtypes/​prometheus|Prometheus checks]] for more details.  |
  
 Note that if the discovery rule has been applied to the host via template then the content of this tab is read-only. Note that if the discovery rule has been applied to the host via template then the content of this tab is read-only.
Line 129: Line 133:
 {{manual:​discovery:​low_level_discovery:​item_prototype_fs1.png|}} {{manual:​discovery:​low_level_discovery:​item_prototype_fs1.png|}}
  
-Low-level discovery [[:​manual/​config/​macros/​lld_macros|macros]] and user [[:​manual/​appendix/​macros/​supported_by_location_user|macros]] may be used in item prototype configuration and item value preprocessing [[:​manual/​config/​items/​item#​item_value_preprocessing|parameters]].+Low-level discovery [[:​manual/​config/​macros/​lld_macros|macros]] and user [[:​manual/​appendix/​macros/​supported_by_location_user|macros]] may be used in item prototype configuration and item value preprocessing [[:​manual/​config/​items/​item#​item_value_preprocessing|parameters]]. Note that when used in update intervals, a single macro has to fill the whole field. Multiple macros in one field or macros mixed with text are not supported.
  
 <​note>​Context-specific escaping of low-level discovery macros is performed for safe use in regular expression and XPath preprocessing parameters.</​note>​ <​note>​Context-specific escaping of low-level discovery macros is performed for safe use in regular expression and XPath preprocessing parameters.</​note>​