Zabbix Documentation 2.2

2.23.04.04.2 (current)In development:4.4 (devel)Unsupported:1.82.02.43.23.4

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
manual:discovery:low_level_discovery [2014/09/25 14:40]
sasha Page moved from 2.2:manual:discovery:low_level_discovery to manual:discovery:low_level_discovery
manual:discovery:low_level_discovery [2019/06/07 07:51] (current)
martins-v lld rule will not go unsupported because of skipping existing entities
Line 19: Line 19:
 An item that discovers the necessary entities is like a regular item seen elsewhere: the server asks a Zabbix agent (or whatever the type of the item is set to) for a value of that item, the agent responds with a textual value. The difference is that the value the agent responds with should contain a list of discovered entities in a specific JSON format. While the details of this format are only important for implementers of custom discovery checks, it is necessary to know that the returned value contains a list of macro -> value pairs. For instance, item "​net.if.discovery"​ might return two pairs: "​{#​IFNAME}"​ -> "​lo"​ and "​{#​IFNAME}"​ -> "​eth0"​. An item that discovers the necessary entities is like a regular item seen elsewhere: the server asks a Zabbix agent (or whatever the type of the item is set to) for a value of that item, the agent responds with a textual value. The difference is that the value the agent responds with should contain a list of discovered entities in a specific JSON format. While the details of this format are only important for implementers of custom discovery checks, it is necessary to know that the returned value contains a list of macro -> value pairs. For instance, item "​net.if.discovery"​ might return two pairs: "​{#​IFNAME}"​ -> "​lo"​ and "​{#​IFNAME}"​ -> "​eth0"​.
  
-<​note>​Low-level discovery items vfs.fs.discoverynet.if.discovery are supported since Zabbix agent version 2.0.</​note>​+<​note>​Low-level discovery items "vfs.fs.discovery" and "net.if.discovery" ​are supported since Zabbix agent version 2.0.\\ Discovery of SNMP OIDs is supported since Zabbix server and proxy version 2.0.</​note>​
  
-<​note>​On a Zabbix proxy the return value of low-level discovery rule is limited to 4000 characters with Oracle DB and 2048 characters ​with IBM DB2.</​note>​+<​note>​Return values ​of low-level discovery rule are limited to 2048 bytes on a Zabbix proxy run with IBM DB2 database. This limit does not apply to Zabbix server as return values are processed without being stored in a database.</​note>​
  
-These macros are then used in names, keysand other prototype fields ​that are basis for creating real items, triggers, ​and graphs for each discovered entity. ​These macros ​can be used: +These macros are used in names, keys and other prototype fields ​where they are then substituted with the received values ​for creating real items, triggers, graphs ​or even hosts for each discovered entity. ​See the full list of [[:​manual/​appendix/​macros/​supported_by_location#​macros_used_in_low-level_discovery|options]] ​for using LLD macros.
- +
-  * for item prototypes in +
-    * names +
-    * keys +
-    * SNMP OIDs +
-    * calculated item formulas +
-    * SSH and Telnet scripts +
-    * database monitor item parameters  +
-  * for trigger prototypes in +
-    * names +
-    * expressions (insofar as when referencing an item key prototype and as standalone constants)  +
-  * for graph prototypes in +
-    * names+
  
 When the server receives a value for a discovery item, it looks at the macro -> value pairs and for each pair generates real items, triggers, and graphs, based on their prototypes. In the example with "​net.if.discovery"​ above, the server would generate one set of items, triggers, and graphs for the loopback interface "​lo",​ and another set for interface "​eth0"​. When the server receives a value for a discovery item, it looks at the macro -> value pairs and for each pair generates real items, triggers, and graphs, based on their prototypes. In the example with "​net.if.discovery"​ above, the server would generate one set of items, triggers, and graphs for the loopback interface "​lo",​ and another set for interface "​eth0"​.
  
-The following sections illustrate the process described above in detail and serve as a how-to for performing discovery of file systems, network interfaces, and SNMP OIDs. The last section describes ​the JSON format for discovery items and gives an example of how to implement your own file system discoverer as a Perl script.+See also: [[#​discovered_entities|Discovered entities]] 
 + 
 +The following sections illustrate the process described above in detail and serve as a how-to for performing discovery of file systems, network interfaces, and SNMP OIDs. See [[#​creating_custom_lld_rules|Creating custom LLD rules]] for a description of the JSON format for discovery items and an example of how to implement your own file system discoverer as a Perl script.
  
 === - Discovery of file systems === === - Discovery of file systems ===
Line 49: Line 38:
   * Click on //​Discovery//​ in the row of an appropriate template   * Click on //​Discovery//​ in the row of an appropriate template
  
-{{:2.2/manual/discovery/low_level_discovery/1.9.9_fs_templates.png?​600|}}+{{manual:discovery:low_level_discovery:1.9.9_fs_templates.png?​600|}}
  
   * Click on //Create discovery rule// in the upper right corner of the screen   * Click on //Create discovery rule// in the upper right corner of the screen
   * Fill in the form with the following details   * Fill in the form with the following details
  
-{{:2.2/manual/discovery/low_level_discovery/lld_rule_fs.png?​570|}}+{{manual:discovery:low_level_discovery:lld_rule_fs.png?​570|}}
  
 ^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. ​ |
-|//​Key// ​ |An item with "​vfs.fs.discovery"​ key is built into the Zabbix agent on many platforms (see [[:2.2/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 the 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 (in sec)// ​ |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.\\ //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. ​ | +|//Update interval (in sec)// ​ |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.\\ //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. ​ | 
-|//Flexible intervals// ​ |You can create exceptions to //Update interval//. For example:\\ Interval: **0**, Period: **6-7,​00:​00-24:​00** - will disable the polling at the weekend. Otherwise default update interval will be used.\\ Up to seven flexible intervals can be defined.\\ If multiple flexible intervals overlap, the smallest //​Interval//​ value is used for the overlapping period.\\ See [[:2.2/manual/appendix/time_period|Time period specification]] page for description of the //Period// format.\\ //Note//: If set to '0', the item will not be polled during the flexible interval duration and will resume polling according to the //Update interval// once the flexible interval period is over.  | +|//Flexible intervals// ​ |You can create exceptions to //Update interval//. For example:\\ Interval: **0**, Period: **6-7,​00:​00-24:​00** - will disable the polling at the weekend. Otherwise default update interval will be used.\\ Up to seven flexible intervals can be defined.\\ If multiple flexible intervals overlap, the smallest //​Interval//​ value is used for the overlapping period.\\ See [[manual:appendix:time_period|Time period specification]] page for description of the //Period// format.\\ //Note//: If set to %%"%%0%%"%%, the item will not be polled during the flexible interval duration and will resume polling according to the //Update interval// once the flexible interval period is over.  | 
-|//Keep lost resources period (in days)// ​ |This field allows you to specify for how many days the discovered entity will be retained (won't be deleted) once its discovery status becomes "Not discovered anymore"​ (max 3650 days). \\ //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 (in days)// ​ |This field allows you to specify for how many days the discovered entity will be retained (won't be deleted) once its discovery status becomes "Not discovered anymore"​ (max 3650 days). \\ //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.   | 
-|//​Filter// ​ |The filter can be used to only generate real items, triggers, and graphs for certain file systems. It expects [[:2.2/manual/regular_expressions|POSIX Extended Regular Expression]]. For instance, if you are only interested in C:, D:, and E: file systems, you could put {#FSNAME} into "​Macro"​ and <​nowiki>"​^C|^D|^E"</​nowiki>​ regular expression into "​Regexp"​ text fields. Filtering is also possible by file system types using {#FSTYPE} macro (e. g. <​nowiki>"​^ext|^reiserfs"</​nowiki>​).\\ You can enter a regular expression or reference a global [[:2.2/manual/regular_expressions|regular expression]] in "​Regexp"​ field.\\ In order to test the regular expression you can use "grep -E", for example: <code bash>for f in ext2 nfs reiserfs smbfs; do echo $f | grep -E '​^ext|^reiserfs'​ || echo "SKIP: $f"; done</​code>​|+|//​Filter// ​ |The filter can be used to only generate real items, triggers, and graphs for certain file systems. It expects [[manual:​regular_expressions|POSIX Extended Regular Expression]]. For instance, if you are only interested in C:, D:, and E: file systems, you could put {#FSNAME} into "​Macro"​ and <​nowiki>"​^C|^D|^E"</​nowiki>​ regular expression into "​Regexp"​ text fields. Filtering is also possible by file system types using {#FSTYPE} macro (e. g. <​nowiki>"​^ext|^reiserfs"</​nowiki>​).\\ You can enter a regular expression or reference a global [[manual:​regular_expressions|regular expression]] in "​Regexp"​ field.\\ In order to test the regular expression you can use "grep -E", for example: <code bash>for f in ext2 nfs reiserfs smbfs; do echo $f | grep -E '​^ext|^reiserfs'​ || echo "SKIP: $f"; done</​code>​Note that if some macro from the filter is missing in the response, the found entity will be ignored.  ​|
 |//​Description// ​ |Enter a description. ​ | |//​Description// ​ |Enter a description. ​ |
-|//​Status// ​ |**Enabled** - the rule will be processed.\\ **Disabled** - the rule will not be processed.\\ **Not supported** - the item is not supported. This item will not be processed, however Zabbix may try to periodically set the status of the item to //Enabled// according to the interval set for [[:2.2/manual/web_interface/frontend_sections/administration/general?&#​other_parameters|refreshing unsupported items]]. ​ |+|//​Status// ​ |**Enabled** - the rule will be processed.\\ **Disabled** - the rule will not be processed.\\ **Not supported** - the item is not supported. This item will not be processed, however Zabbix may try to periodically set the status of the item to //Enabled// according to the interval set for [[manual:web_interface:frontend_sections:administration:general#​other_parameters|refreshing unsupported items]]. ​ |
  
 <note important>​Zabbix database in MySQL must be created as case-sensitive if file system names that differ only by case are to be discovered correctly.</​note>​ <note important>​Zabbix database in MySQL must be created as case-sensitive if file system names that differ only by case are to be discovered correctly.</​note>​
 +
 +<note important>​The mistake or typo in regex used in LLD rule may cause deleting thousands of configuration elements, historical values and events for many hosts. For example, incorrect “File systems for discovery” regular expression may cause deleting thousands of items, triggers, historical values and events.</​note>​
  
 <​note>​Discovery rule history is not preserved.</​note>​ <​note>​Discovery rule history is not preserved.</​note>​
Line 73: Line 64:
 Once a rule is created, go to the items for that rule and press "​Create prototype"​ to create an item prototype. Note how macro {#FSNAME} is used where a file system name is required. When the discovery rule is processed, this macro will be substituted with the discovered file system. Once a rule is created, go to the items for that rule and press "​Create prototype"​ to create an item prototype. Note how macro {#FSNAME} is used where a file system name is required. When the discovery rule is processed, this macro will be substituted with the discovered file system.
  
-{{:2.2/manual/discovery/low_level_discovery/item_prototype_fs.png?​570|}}+{{manual:discovery:low_level_discovery:item_prototype_fs.png?​570|}}
  
 <​note>​If an item prototype is created with a //​Disabled//​ status, it will be added to a discovered entity, but in a disabled state.</​note>​ <​note>​If an item prototype is created with a //​Disabled//​ status, it will be added to a discovered entity, but in a disabled state.</​note>​
Line 79: Line 70:
 We can create several item prototypes for each file system metric we are interested in: We can create several item prototypes for each file system metric we are interested in:
  
-{{:2.2/manual/discovery/low_level_discovery/item_prototypes_fs.png?​600|}}+{{manual:discovery:low_level_discovery:item_prototypes_fs.png?​600|}}
  
 Then, we create trigger prototypes in a similar way: Then, we create trigger prototypes in a similar way:
  
-{{:2.2/manual/discovery/low_level_discovery/trigger_prototype_fs.png?​550|}}+{{manual:discovery:low_level_discovery:trigger_prototype_fs.png?​550|}}
  
-{{:2.2/manual/discovery/low_level_discovery/trigger_prototypes_fs.png?​600|}}+{{manual:discovery:low_level_discovery:trigger_prototypes_fs.png?​600|}}
  
 And graph prototypes too: And graph prototypes too:
  
-{{:2.2/manual/discovery/low_level_discovery/graph_prototype_fs.png?​600|}}+{{manual:discovery:low_level_discovery:graph_prototype_fs.png?​600|}}
  
-{{:2.2/manual/discovery/low_level_discovery/graph_prototypes_fs.png?​600|}}+{{manual:discovery:low_level_discovery:graph_prototypes_fs.png?​600|}}
  
 Finally, we have created a discovery rule that looks like shown below. It has five item prototypes, two trigger prototypes, and one graph prototype. Finally, we have created a discovery rule that looks like shown below. It has five item prototypes, two trigger prototypes, and one graph prototype.
  
-{{:2.2/manual/discovery/low_level_discovery/lld_rules_fs.png?​600|}}+{{manual:discovery:low_level_discovery:lld_rules_fs.png?​600|}} 
 + 
 +//Note//: For configuring host prototypes, see the section about [[:​manual/​vm_monitoring#​host_prototypes|host prototype]] configuration in virtual machine monitoring. 
 + 
 +== - Discovered entities ==
  
 The screenshots below illustrate how discovered items, triggers, and graphs look like in the host's configuration. Discovered entities are prefixed with a golden link to a discovery rule they come from. The screenshots below illustrate how discovered items, triggers, and graphs look like in the host's configuration. Discovered entities are prefixed with a golden link to a discovery rule they come from.
  
-{{:2.2/manual/discovery/low_level_discovery/discovered_items.png?​600|}}+{{manual:discovery:low_level_discovery:discovered_items.png?​600|}} 
 + 
 +Note that discovered entities will not be created in case there are already existing entities with the same uniqueness criteria, for example, an item with the same key or graph with the same name. An error message is displayed in this case in the frontend that the low-level discovery rule could not create certain entities. The discovery rule itself, however, will not turn unsupported because some entity could not be created and had to be skipped. The discovery rule will go on creating/​updating other entities. 
 + 
 +Items (similarly, triggers and graphs) created by a low-level discovery rule cannot be manually deleted. However, they will be deleted automatically if a discovered entity (file system, interface, etc) stops being discovered (or does not pass the filter anymore). In this case the items, triggers and graphs will be deleted after the days defined in the //Keep lost resources period// field pass. Note that triggers (until Zabbix 2.2.2) and graphs (until Zabbix 2.2.3) are deleted immediately.
  
-Items (similarly, triggers and graphs) created by a low-level discovery rule cannot be manually deleted. However, they will be deleted automatically if a discovered ​entity (file systeminterface, etc) stops being discovered (or does not pass the filter anymore)In this case the items will be deleted after the days defined in the //Keep lost resources period// field pass; triggers and graphs will be deleted ​immediately.+When discovered entities become '​Not ​discovered ​anymore'​an orange lifetime indicator is displayed in the item listMove your mouse pointer over it and a message ​will be displayed indicating how many days are left until the item is deleted.
  
-When discovered entities become 'Not discovered anymore',​ an orange lifetime indicator is displayed in the items listMove your mouse pointer over it and a message will be displayed indicating how many days are left until the item will be deleted.+{{1.9.9_lifetime_indicator.png?​400|}}
  
-{{:​2.2/​manual/​discovery/​1.9.9_lifetime_indicator.png?400|}}+If entities were marked for deletion, but were not deleted at the expected time (disabled ​discovery ​rule or item host), they will be deleted the next time the discovery rule is processed.
  
-{{:2.2/manual/discovery/low_level_discovery/discovered_triggers.png?​600|}}+{{manual:discovery:low_level_discovery:discovered_triggers.png?​600|}}
  
-{{:2.2/manual/discovery/low_level_discovery/discovered_graphs.png?​600|}}+{{manual:discovery:low_level_discovery:discovered_graphs.png?​600|}}
  
 === - Discovery of network interfaces === === - Discovery of network interfaces ===
Line 122: Line 121:
 In this example, we will perform SNMP discovery on a switch. First, go to "​Configuration"​ -> "​Templates"​. In this example, we will perform SNMP discovery on a switch. First, go to "​Configuration"​ -> "​Templates"​.
  
-{{:2.2/manual/discovery/low_level_discovery/templates_snmp.png?​600|}}+{{manual:discovery:low_level_discovery:templates_snmp.png?​600|}}
  
 To edit discovery rules for a template, click on the link in the "​Discovery"​ column. To edit discovery rules for a template, click on the link in the "​Discovery"​ column.
Line 147: Line 146:
   {#​SNMPINDEX} -> 3   ​{#​SNMPVALUE} -> LAN2   {#​SNMPINDEX} -> 3   ​{#​SNMPVALUE} -> LAN2
  
-{{:2.2/manual/discovery/low_level_discovery/lld_rule_snmp.png|}}+{{manual:discovery:low_level_discovery:lld_rule_snmp.png|}}
  
 The following screenshot illustrates how we can use these macros in item prototypes: The following screenshot illustrates how we can use these macros in item prototypes:
  
-{{:2.2/manual/discovery/low_level_discovery/item_prototype_snmp.png?​570|}}+{{manual:discovery:low_level_discovery:item_prototype_snmp.png?​570|}}
  
 Again, creating as many item prototypes as needed: Again, creating as many item prototypes as needed:
  
-{{:2.2/manual/discovery/low_level_discovery/item_prototypes_snmp.png?​600|}}+{{manual:discovery:low_level_discovery:item_prototypes_snmp.png?​600|}}
  
 As well as trigger prototypes: As well as trigger prototypes:
  
-{{:2.2/manual/discovery/low_level_discovery/trigger_prototype_snmp.png?​550|}}+{{manual:discovery:low_level_discovery:trigger_prototype_snmp.png?​550|}}
  
-{{:2.2/manual/discovery/low_level_discovery/trigger_prototypes_snmp.png?​600|}}+{{manual:discovery:low_level_discovery:trigger_prototypes_snmp.png?​600|}}
  
 And graph prototypes: And graph prototypes:
  
-{{:2.2/manual/discovery/low_level_discovery/graph_prototype_snmp.png?​600|}}+{{manual:discovery:low_level_discovery:graph_prototype_snmp.png?​600|}}
  
-{{:2.2/manual/discovery/low_level_discovery/graph_prototypes_snmp.png?​600|}}+{{manual:discovery:low_level_discovery:graph_prototypes_snmp.png?​600|}}
  
 A summary of our discovery rule: A summary of our discovery rule:
  
-{{:2.2/manual/discovery/low_level_discovery/lld_rules_snmp.png?​600|}}+{{manual:discovery:low_level_discovery:lld_rules_snmp.png?​600|}}
  
 When server runs, it will create real items, triggers, and graphs, based on the values "​snmp.discovery"​ returns. In host's configuration they will be prefixed with a golden link to a discovery rule they come from. When server runs, it will create real items, triggers, and graphs, based on the values "​snmp.discovery"​ returns. In host's configuration they will be prefixed with a golden link to a discovery rule they come from.
  
-{{:2.2/manual/discovery/low_level_discovery/discovered_items_snmp.png?​600|}}+{{manual:discovery:low_level_discovery:discovered_items_snmp.png?​600|}}
  
-{{:2.2/manual/discovery/low_level_discovery/discovered_triggers_snmp.png?​600|}}+{{manual:discovery:low_level_discovery:discovered_triggers_snmp.png?​600|}}
  
-{{:2.2/manual/discovery/low_level_discovery/discovered_graphs_snmp.png?​600|}}+{{manual:discovery:low_level_discovery:discovered_graphs_snmp.png?​600|}}
  
 === - Creating custom LLD rules === === - Creating custom LLD rules ===