Zabbix Documentation 3.4

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 [2017/06/21 10:17]
martins-v discovery of host interfaces in Zabbix
manual:discovery:low_level_discovery [2018/10/30 06:06] (current)
martins-v some rewording
Line 1: Line 1:
-==== - #3 Low-level discovery ====+==== 3 Low-level discovery ====
  
 === Overview === === Overview ===
  
 Low-level discovery provides a way to automatically create items, triggers, and graphs for different entities on a computer. For instance, Zabbix can automatically start monitoring file systems or network interfaces on your machine, without the need to create items for each file system or network interface manually. Additionally it is possible to configure Zabbix to remove unneeded entities automatically based on actual results of periodically performed discovery. Low-level discovery provides a way to automatically create items, triggers, and graphs for different entities on a computer. For instance, Zabbix can automatically start monitoring file systems or network interfaces on your machine, without the need to create items for each file system or network interface manually. Additionally it is possible to configure Zabbix to remove unneeded entities automatically based on actual results of periodically performed discovery.
- 
-In Zabbix, several types of discovery items are supported out of the box: 
- 
-  * discovery of file systems; 
-  * discovery of network interfaces; 
-  * discovery of CPUs and CPU cores; 
-  * discovery of SNMP OIDs; 
-  * discovery using ODBC SQL queries; 
-  * discovery of Windows services; 
-  * discovery of host interfaces in Zabbix. 
  
 A user can define their own types of discovery, provided they follow a particular JSON protocol. A user can define their own types of discovery, provided they follow a particular JSON protocol.
Line 22: Line 12:
  
 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.discovery"​ and "​net.if.discovery"​ are supported since Zabbix agent version 2.0.\\ Discovery item "​system.cpu.discovery"​ is supported since Zabbix agent version 2.4.\\ Discovery of SNMP OIDs is supported since Zabbix server and proxy version 2.0.\\ Discovery using ODBC SQL queries is supported since Zabbix server and proxy version 3.0.</​note>​ 
- 
-<​note>​Return values of a 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 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/​config/​macros/​lld_macros|options]] for using LLD macros. 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/​config/​macros/​lld_macros|options]] for using LLD macros.
Line 31: Line 17:
 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 all types of discovery mentioned above. 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]]
  
-=== - Discovery of file systems ​===+=== Configuring low-level discovery ​===
  
-To configure the discovery ​of file systems, do the following:+We will illustrate low-level discovery based on an example of file system discovery. 
 + 
 +To configure the discovery, do the following:
  
   * Go to: //​Configuration//​ -> //​Templates// ​   * Go to: //​Configuration//​ -> //​Templates// ​
Line 43: Line 31:
  
   * 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 discovery rule form with the required ​details 
 + 
 +=== Discovery rule ===
  
 The **Discovery rule** tab contains general discovery rule attributes: ​ The **Discovery rule** tab contains general discovery rule attributes: ​
Line 52: Line 42:
 |//​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 [[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 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. ​ |
 |//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. ​ | |//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. ​ |
 |//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. ​ |
Line 58: Line 48:
 |//​Description// ​ |Enter a description. ​ | |//​Description// ​ |Enter a description. ​ |
 |//​Enabled// ​ |If checked, the rule will be processed. ​ | |//​Enabled// ​ |If checked, the rule will be processed. ​ |
 +
 +=== Discovery rule filter ===
  
 The **Filters** tab contains discovery rule filter definitions: ​ The **Filters** tab contains discovery rule filter definitions: ​
Line 68: Line 60:
  
 <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>​
 +
 +=== Item prototypes ===
  
 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.
Line 86: Line 82:
 {{manual:​discovery:​low_level_discovery:​item_prototypes_fs.png|}} {{manual:​discovery:​low_level_discovery:​item_prototypes_fs.png|}}
  
-Then, we create trigger prototypes in a similar way:+=== Trigger prototypes === 
 + 
 +We create trigger prototypes in a similar way as item prototypes:
  
 {{manual:​discovery:​low_level_discovery:​trigger_prototype_fs.png|}} {{manual:​discovery:​low_level_discovery:​trigger_prototype_fs.png|}}
Line 100: Line 98:
  
 {{manual:​discovery:​low_level_discovery:​trigger_prototypes_fs.png|}} {{manual:​discovery:​low_level_discovery:​trigger_prototypes_fs.png|}}
 +
 +=== Graph prototypes ===
  
 We can create graph prototypes, too: We can create graph prototypes, too:
Line 112: Line 112:
  
 //Note//: For configuring host prototypes, see the section about [[:​manual/​vm_monitoring#​host_prototypes|host prototype]] configuration in virtual machine monitoring. //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 an orange 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 an orange link to a discovery rule they come from.
Line 117: Line 119:
 {{manual:​discovery:​low_level_discovery:​discovered_items.png|}} {{manual:​discovery:​low_level_discovery:​discovered_items.png|}}
  
-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.+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 that the low-level discovery rule could not create certain entities.
  
 Items (similarly, triggers and graphs) created by a low-level discovery rule 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. Items (similarly, triggers and graphs) created by a low-level discovery rule 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.
Line 133: Line 135:
 {{manual:​discovery:​low_level_discovery:​discovered_graphs.png|}} {{manual:​discovery:​low_level_discovery:​discovered_graphs.png|}}
  
-=== - Discovery ​of network interfaces ​===+=== Other types of discovery ​===
  
-Discovery ​of network interfaces is done in exactly the same way as discovery ​of file systems, except that you use the discovery ​rule key "​net.if.discovery"​ instead of "​vfs.fs.discovery"​ and use macro {#IFNAME} instead of {#​FSNAME} ​in filter and item/​trigger/​graph prototypes.+More detail and how-tos on other types of out-of-the-box discovery ​is available ​in the following sections:
  
-Examples ​of item prototypes that you might wish to create based on "​net.if.discovery""​net.if.in[{#​IFNAME},​bytes]", "​net.if.out[{#​IFNAME},​bytes]".+  * discovery ​of [[:manual/discovery/​low_level_discovery/​network_interfaces|network interfaces]];​ 
 +  * discovery of [[:manual/​discovery/​low_level_discovery/​cpu|CPUs and CPU cores]]; 
 +  * discovery of [[:​manual/​discovery/​low_level_discovery/​snmp_oids|SNMP OIDs]]; 
 +  * discovery of [[:​manual/​discovery/​low_level_discovery/​jmx|JMX objects]]; 
 +  * discovery using [[:​manual/​discovery/​low_level_discovery/​sql_queries|ODBC SQL queries]];​ 
 +  * discovery of [[:​manual/​discovery/​low_level_discovery/​windows_services|Windows services]];​ 
 +  * discovery of [[:​manual/​discovery/​low_level_discovery/​host_interfaces|host interfaces]] in Zabbix.
  
-[[#discovery_of_file_systems|See above]] for more information about the filter.+For more detail on the JSON format for discovery items and an example of how to implement your own file system discoverer as a Perl script, see [[#creating_custom_lld_rules|creating custom LLD rules]].
  
-=== - Discovery of CPUs and CPU cores ===+=== Data limits for return values ​===
  
-Discovery of CPUs and CPU cores is done in a similar fashion as network interface discovery with the exception being that the discovery rule key is "​system.cpu.discovery"​. This discovery key returns two macros - {#​CPU.NUMBER} and {#​CPU.STATUS} identifying the CPU order number and status respectively. To note, a clear distinction cannot be made between actual, physical processors, cores and hyperthreads{#​CPU.STATUS} on LinuxUNIX and BSD systems returns the status of the processorwhich can be either "​online"​ or "​offline"​. On Windows systemsthis same macro may represent a third value - "​unknown"​ - which indicates that a processor has been detected, but no information has been collected for it yet.+There is no limit for low-level ​discovery rule JSON data if it is received directly by Zabbix serverbecause return values are processed without being stored in databaseThere'​s also no limit for custom low-level discovery ruleshoweverif it is intended to acquire custom LLD data using a user parameterthen user parameter return ​value limit applies (512 KB).
  
-CPU discovery relies on the agent'​s collector process to remain consistent with the data provided by the collector and save resources on obtaining the data. This has the effect of this item key not working with the test (-t) command line flag of the agent binarywhich will return ​NOT_SUPPORTED status and an accompanying message indicating that the collector process has not been started.+If data has to go through Zabbix proxy it has to store this data in database so [[:​manual/​config/​items/​item#​text_data_limits|database limits]] applyfor example, 2048 bytes on Zabbix proxy run with IBM DB2 database.
  
-Item prototypes that can be created based on CPU discovery include, ​for example, "​system.cpu.util[{#​CPU.NUMBER},​ <​type>,​ <​mode>​]"​ or "​system.hw.cpu[{#​CPU.NUMBER},​ <​info>​]"​.+=== Multiple LLD rules for same item ===
  
-=== Discovery of SNMP OIDs ===+Since Zabbix agent version 3.2 it is possible to define several low-level discovery rules with the same discovery item. 
  
-In this example, we will perform SNMP discovery on a switch. First, go to "​Configuration"​ -> "​Templates"​. +To do that you need to define ​the Alias agent [[manual/appendix/config/zabbix_agentd|parameter]], allowing ​to use altered ​discovery item keys in different ​discovery ​rulesfor example ''​vfs.fs.discovery[foo]''​''​vfs.fs.discovery[bar]''​etc
- +=== Creating custom LLD rules ===
-{{manual:​discovery:​low_level_discovery:​templates_snmp.png|}} +
- +
-To edit discovery rules for a template, click on the link in the "​Discovery"​ column. +
- +
-Then, press "​Create rule" and fill the form with the details in the screenshot below. +
- +
-Unlike file system and network interface discovery, the item does not necessarily have to have "​snmp.discovery"​ key - item type of SNMP agent is sufficient. +
- +
-The OIDs to discover are defined in SNMP OID field in the following format: ''​discovery[{#MACRO1}, oid1, {#MACRO2}, oid2, …,​]''​ +
- +
-where //​{#​MACRO1}//,​ //​{#​MACRO2}//​ …  are valid lld macro names and //oid1//, //oid2//... are OIDs capable of generating meaningful values for these macros. A built-in macro //​{#​SNMPINDEX}//​ containing index of the discovered OID is applied to discovered entities. The discovered entities are grouped by //​{#​SNMPINDEX}//​ macro value. +
- +
-To understand what we mean, let us perform few snmpwalks on our switch:  +
-  $ snmpwalk -v 2c -c public 192.168.1.1 IF-MIB::​ifDescr +
-  IF-MIB::​ifDescr.1 = STRING: WAN +
-  IF-MIB::​ifDescr.2 = STRING: LAN1 +
-  IF-MIB::​ifDescr.3 = STRING: LAN2 +
-   +
-  $ snmpwalk -v 2c -c public 192.168.1.1 IF-MIB::​ifPhysAddress +
-  IF-MIB::​ifPhysAddress.1 = STRING: 8:​0:​27:​90:​7a:​75 +
-  IF-MIB::​ifPhysAddress.2 = STRING: 8:​0:​27:​90:​7a:​76 +
-  IF-MIB::​ifPhysAddress.3 = STRING: 8:​0:​27:​2b:​af:​9e +
- +
-And set SNMP OID to: ''​discovery[{#IFDESCR}, ifDescr, {#​IFPHYSADDRESS},​ ifPhysAddress]''​ +
- +
-Now this rule will discover entities with {#IFDESCR} macros set to **WAN**, **LAN1** and **LAN2**, {#​IFPHYSADDRESS} macros set to **8:​0:​27:​90:​7a:​75**,​ **8:​0:​27:​90:​7a:​76**,​ and **8:​0:​27:​2b:​af:​9e**,​ {#​SNMPINDEX} macros set to the discovered OIDs indexes **1**, **2** and **3**: +
-  { +
-      "​data":​ [ +
-          { +
-              "​{#​SNMPINDEX}":​ "​1",​ +
-              "​{#​IFDESCR}":​ "​WAN",​ +
-              "​{#​IFPHYSADDRESS}":​ "​8:​0:​27:​90:​7a:​75"​ +
-          }, +
-          { +
-              "​{#​SNMPINDEX}":​ "​2",​ +
-              "​{#​IFDESCR}":​ "​LAN1",​ +
-              "​{#​IFPHYSADDRESS}":​ "​8:​0:​27:​90:​7a:​76"​ +
-          }, +
-          { +
-              "​{#​SNMPINDEX}":​ "​3",​ +
-              "​{#​IFDESCR}":​ "​LAN2",​ +
-              "​{#​IFPHYSADDRESS}":​ "​8:​0:​27:​2b:​af:​9e"​ +
-          } +
-      ] +
-  } +
- +
-If an entity does not have the specified OID, then the corresponding macro will be omitted for this entity. For example if we have the following data: +
-  ifDescr.1 "​Interface #1" +
-  ifDescr.2 "​Interface #2" +
-  ifDescr.4 "​Interface #4" +
-   +
-  ifAlias.1 "​eth0"​ +
-  ifAlias.2 "​eth1"​ +
-  ifAlias.3 "​eth2"​ +
-  ifAlias.5 "​eth4"​ +
-  +
-Then in this case SNMP discovery ''​discovery[{#​IFDESCR},​ ifDescr, {#IFALIAS}, ifAlias]''​ will return the following structure:  +
-  { +
-      "​data":​ [ +
-          { +
-              "​{#​SNMPINDEX}":​ 1, +
-              "​{#​IFDESCR}":​ "​Interface #1", +
-              "​{#​IFALIAS}":​ "​eth0"​ +
-          }, +
-          { +
-              "​{#​SNMPINDEX}":​ 2, +
-              "​{#​IFDESCR}":​ "​Interface #2", +
-              "​{#​IFALIAS}":​ "​eth1"​ +
-          }, +
-          { +
-              "​{#​SNMPINDEX}":​ 3, +
-              "​{#​IFALIAS}":​ "​eth2"​ +
-          }, +
-          { +
-              "​{#​SNMPINDEX}":​ 4, +
-              "​{#​IFDESCR}":​ "​Interface #4" +
-          }, +
-          { +
-              "​{#​SNMPINDEX}":​ 5, +
-              "​{#​IFALIAS}":​ "​eth4"​ +
-          } +
-      ] +
-  }   +
- +
-{{manual:​discovery:​low_level_discovery:​lld_rule_snmp.png|}} +
- +
-The following screenshot illustrates how we can use these macros in item prototypes:​ +
- +
-{{manual:​discovery:​low_level_discovery:​item_prototype_snmp.png|}} +
- +
-Again, creating as many item prototypes as needed: +
- +
-{{manual:​discovery:​low_level_discovery:​item_prototypes_snmp.png|}} +
- +
-As well as trigger prototypes:​ +
- +
-{{manual:​discovery:​low_level_discovery:​trigger_prototype_snmp.png|}} +
- +
-{{manual:​discovery:​low_level_discovery:​trigger_prototypes_snmp.png|}} +
- +
-And graph prototypes:​ +
- +
-{{manual:​discovery:​low_level_discovery:​graph_prototype_snmp.png|}} +
- +
-{{manual:​discovery:​low_level_discovery:​graph_prototypes_snmp.png|}} +
- +
-A summary of our discovery rule: +
- +
-{{manual:​discovery:​low_level_discovery:​lld_rules_snmp.png|}} +
- +
-When server runs, it will create real items, triggers and graphs based on the values the SNMP discovery rule returns. In the host configuration they are prefixed with an orange link to a discovery rule they come from. +
- +
-{{manual:​discovery:​low_level_discovery:​discovered_items_snmp.png|}} +
- +
-{{manual:​discovery:​low_level_discovery:​discovered_triggers_snmp.png|}} +
- +
-{{manual:​discovery:​low_level_discovery:​discovered_graphs_snmp.png|}} +
- +
-=== - Discovery using ODBC SQL queries === +
- +
-This type of discovery is done using SQL queries, whose results get automatically transformed into a JSON object suitable for low-level discovery. SQL queries are performed using items of type "​Database monitor"​. Therefore, most of the instructions on [[:manual/config/​items/​itemtypes/​odbc_checks|ODBC monitoring]] page apply in order to get a working "​Database monitor"​ discovery rule, the only difference being that "​db.odbc.discovery[<​description>,<​dsn>​]"​ key should be used instead of "​db.odbc.select[<​description>,<​dsn>​]"​. +
- +
-As a practical example to illustrate how the SQL query is transformed into JSON, let us consider low-level discovery of Zabbix proxies by performing an ODBC query on Zabbix database. This is useful for automatic creation of "​zabbix[proxy,<​name>,​lastaccess]"​ [[:manual/config/items/​itemtypes/​internal|internal items]] to monitor which proxies are alive. +
- +
-Let us start with discovery rule configuration:​ +
- +
-{{manual:​discovery:​low_level_discovery:​discovery_rule_odbc.png}} +
- +
-Herethe following direct query on Zabbix database is used to select all Zabbix proxies, together with the number of hosts they are monitoring. The number of hosts can be used, for instance, to filter out empty proxies: +
- +
-<​code>​ +
-mysql> SELECT h1.host, COUNT(h2.host) AS count FROM hosts h1 LEFT JOIN hosts h2 ON h1.hostid = h2.proxy_hostid WHERE h1.status IN (5, 6) GROUP BY h1.host; +
-+---------+-------+ +
-| host    | count | +
-+---------+-------+ +
-| Japan 1 |     5 | +
-| Japan 2 |    12 | +
-| Latvia ​ |     3 | +
-+---------+-------+ +
-3 rows in set (0.01 sec) +
-</​code>​ +
- +
-By the internal workings of "​db.odbc.discovery[]" ​item, the result of this query gets automatically transformed into the following JSON: +
- +
-<code js> +
-+
-    "​data":​ [ +
-        { +
-            "​{#​HOST}":​ "Japan 1", +
-            "​{#​COUNT}":​ "​5"​ +
-        }, +
-        { +
-            "​{#​HOST}":​ "Japan 2", +
-            "​{#​COUNT}":​ "​12"​ +
-        }, +
-        { +
-            "​{#​HOST}":​ "​Latvia",​ +
-            "​{#​COUNT}":​ "​3"​ +
-        } +
-    ] +
-+
-</​code>​ +
- +
-It can be seen that column names become macro names and selected rows become the values of these macros. +
- +
-<​note>​ +
-If it is not obvious how a column name would be transformed into a macro name, it is suggested to use column aliases like "​COUNT(h2.host) AS count" ​in the example above. +
- +
-In case a column name cannot be converted into a valid macro name, the discovery ​rule becomes not supportedwith the error message detailing the offending column numberIf additional help is desired, the obtained column names are provided under DebugLevel=4 in Zabbix server log file: +
- +
-<​code>​ +
-$ grep db.odbc.discovery ​/​tmp/​zabbix_server.log +
- ... +
- ​23876:​20150114:​153410.856 In db_odbc_discovery() query:'​SELECT h1.host, COUNT(h2.host) FROM hosts h1 LEFT JOIN hosts h2 ON h1.hostid = h2.proxy_hostid WHERE h1.status IN (5, 6) GROUP BY h1.host;'​ +
- ​23876:​20150114:​153410.860 db_odbc_discovery() column[1]:'host' +
- ​23876:​20150114:​153410.860 db_odbc_discovery() column[2]:'COUNT(h2.host)' +
- ​23876:​20150114:​153410.860 End of db_odbc_discovery():​NOTSUPPORTED +
- ​23876:​20150114:​153410.860 Item [Zabbix server:db.odbc.discovery[proxies,​{$DSN}]] error: Cannot convert column #2 name to macro. +
-</​code>​ +
-</​note>​ +
- +
-Now that we understand how a SQL query is transformed into a JSON objectwe can use {#HOST} macro in item prototypes:​ +
- +
-{{manual:​discovery:​low_level_discovery:​item_prototype_odbc.png}} +
- +
-Once discovery is performed, an item will be created for each proxy: +
- +
-{{manual:​discovery:​low_level_discovery:​discovered_items_odbc.png}} +
- +
-=== - Discovery of Windows services === +
- +
-Windows service discovery is done in the same way as discovery of file systems. The key to use in the  discovery rule is "​service.discovery"​ and the following macros are supported for use in the [[#​discovery_of_file_systems|filter]] and item/​trigger/​graph prototypes:​ +
- +
-<​code>​ +
-{#​SERVICE.NAME} +
-{#​SERVICE.DISPLAYNAME} +
-{#​SERVICE.DESCRIPTION} +
-{#​SERVICE.STATE} +
-{#​SERVICE.STATENAME} +
-{#​SERVICE.PATH} +
-{#​SERVICE.USER} +
-{#​SERVICE.STARTUP} +
-{#​SERVICE.STARTUPNAME} +
-</​code>​ +
- +
-Based on Windows service discovery you may create an item prototype like "​service.info[{#​SERVICE.NAME},<​param>​]",​ where //param// accepts the following values: //state//, //​displayname//,​ //path//, //user//, //startup// or //​description//​. For example, to acquire the display name of a service you should use a "​service.info[{#​SERVICE.NAME},​displayname]"​ item. If //param// value is not specified ("​service.info[{#​SERVICE.NAME}]"​),​ the default parameter //state// is used. +
- +
-{#​SERVICE.STATE} and {#​SERVICE.STATENAME} macros return the same content, however, {#​SERVICE.STATE} returns a numerical value (0-7), while {#​SERVICE.STATENAME} returns text (//​running//,​ //paused//, //start pending//, //pause pending//, //continue pending//, //stop pending//, //stopped// or //​unknown//​). The same applies to {#​SERVICE.STARTUP} and {#​SERVICE.STARTUPNAME},​ where one returns a numerical value (0-4) while the other - text (//​automatic//,​ //automatic delayed//, //manual//, //​disabled//,​ //​unknown//​). +
- +
-=== - Discovery of host interfaces in Zabbix === +
- +
-It is possible to discover all configured interfaces of a host in Zabbix frontend by using the **zabbix[host,​discovery,​interfaces]** internal item.  +
- +
-This item returns a JSON with the description of interfaces, for example: +
- +
-  {"​data":​[{"​{#​IF.CONN}":"​192.168.3.1","​{#​IF.IP}":"​192.168.3.1","​{#​IF.DNS}":"","​{#​IF.PORT}":​“10050”,"​{#​IF.TYPE}":"​AGENT","​{#​IF.DEFAULT}":​1}]} ​  +
- +
-The following macros are supported for use in the [[#​discovery_of_file_systems|filter]] and item/​trigger/​graph prototypes:​ +
- +
-^Macro^Description^ +
-|//​{#​IF.CONN}// ​   |Interface IP address or DNS host name.  | +
-|//​{#​IF.IP}// ​     |Interface IP address. ​ | +
-|//​{#​IF.DNS}// ​    ​|Interface DNS host name.  | +
-|//​{#​IF.PORT}// ​   |Interface port number. ​ | +
-|//​{#​IF.TYPE}// ​   |Interface type (“AGENT”,​ “SNMP”, “JMX”,​“IPMI” or “UNKNOWN”). ​ | +
-|//​{#​IF.DEFAULT}//​ |Default status for the interface:​\\ 0 - not default interface\\ 1 - default interface) ​ | +
-|//​{#​IF.SNMPBULK}//​|SNMP bulk processing status for the interface:​\\ 0 - disabled\\ 1 - enabled)\\ This macro is returned only if interface type is “SNMP”. ​ | +
- +
-=== - Setting up multiple LLD rules for the same item === +
- +
-Since Zabbix agent version 3.2 it is possible to alter low-level discovery item keys using "​Alias"​ parameter in [[manual/​appendix/​config/​zabbix_agentd|zabbix_agentd.conf]] file to enable configuration of several LLD rules for the same item. +
- +
-=== Creating custom LLD rules ===+
  
 It is also possible to create a completely custom LLD rule, discovering any type of entities - for example, databases on a database server. It is also possible to create a completely custom LLD rule, discovering any type of entities - for example, databases on a database server.
Line 445: Line 220:
 <​note>​You don't have to use macro names FSNAME/​FSTYPE with custom LLD rules, you are free to use whatever names you like.</​note>​ <​note>​You don't have to use macro names FSNAME/​FSTYPE with custom LLD rules, you are free to use whatever names you like.</​note>​
  
-=== Using LLD macros in user macro contexts ===+Note that, if using a user parameter, the return value is limited to 512 KB. For more details, see [[:​manual/​discovery/​low_level_discovery#​data_limits_for_return_values|data limits for LLD return values]]. 
 + 
 +=== Using LLD macros in user macro contexts ===
  
 User macros [[:​manual/​config/​macros/​usermacros#​user_macro_context|with context]] can be used to accomplish more flexible thresholds in trigger expressions. Different thresholds may be defined on user macro level and then used in trigger constants depending on the discovered context. Discovered context appears when the [[:​manual/​config/​macros/​lld_macros|low-level discovery macros]] used in the macros are resolved to real values. User macros [[:​manual/​config/​macros/​usermacros#​user_macro_context|with context]] can be used to accomplish more flexible thresholds in trigger expressions. Different thresholds may be defined on user macro level and then used in trigger constants depending on the discovered context. Discovered context appears when the [[:​manual/​config/​macros/​lld_macros|low-level discovery macros]] used in the macros are resolved to real values.
Line 462: Line 239:
 Now, once the file systems are discovered, events will be generated if ''/'',​ ''/​usr''​ and ''/​var''​ filesystems have less than **10**% of free disk space, the ''/​home''​ filesystem - less than **20**% of free disk space or the ''/​tmp''​ filesystem - less than **50**% of free disk space. Now, once the file systems are discovered, events will be generated if ''/'',​ ''/​usr''​ and ''/​var''​ filesystems have less than **10**% of free disk space, the ''/​home''​ filesystem - less than **20**% of free disk space or the ''/​tmp''​ filesystem - less than **50**% of free disk space.
  
-<note important>​LLD macros are not supported inside of user macro contexts in [[manual:​config:​triggers:​expression#​function_parameters|trigger function parameters]].</​note>​+