3 Low-level discovery

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 the actual results of periodically performed discovery.

A user can define their own types of discovery, provided they follow a particular JSON protocol.

The general architecture of the discovery process is as follows.

First, a user creates a discovery rule in Data collection → Templates, in the Discovery column. A discovery rule consists of (1) an item that discovers the necessary entities (for instance, file systems or network interfaces) and (2) prototypes of items, triggers, and graphs that should be created based on the value of that item.

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

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 options for using LLD macros.

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

Note that since Zabbix 4.2, the format of the JSON returned by low-level discovery rules has been changed. It is no longer expected that the JSON will contain the "data" object. Low-level discovery will now accept a normal JSON containing an array, in order to support new features such as the item value preprocessing and custom paths to low-level discovery macro values in a JSON document.

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

See also: Discovered entities

Configureren van low-level discovery

We zullen low-level discovery illustreren aan de hand van een voorbeeld van bestandssysteemontdekking.

Om de ontdekking te configureren, volg deze stappen:

• Ga naar: Gegevensverzameling → Templates of Hosts
• Klik op Ontdekking in de rij van een geschikt template/host

• Klik op Maak ontdekkingsregel in de rechterbovenhoek van het scherm
• Vul het formulier voor de ontdekkingsregel in met de vereiste gegevens

Discovery rule

The discovery rule form contains five tabs, representing, from left to right, the data flow during discovery:

• Discovery rule - specifies, most importantly, the built-in item or custom script to retrieve discovery data
• Preprocessing - applies some preprocessing to the discovered data
• LLD macros - allows to extract some macro values to use in discovered items, triggers, etc
• Filters - allows to filter the discovered values
• Overrides - allows to modify items, triggers, graphs or host prototypes when applying to specific discovered objects

The Discovery rule tab contains the item key to use for discovery (as well as some general discovery rule attributes):

All mandatory input fields are marked with a red asterisk.

Voorbewerking

Het tabblad Voorbewerking maakt het mogelijk om transformatieregels te definiëren die worden toegepast op het resultaat van ontdekking. In deze stap zijn één of meerdere transformaties mogelijk. Transformaties worden uitgevoerd in de volgorde waarin ze zijn gedefinieerd. Alle voorbewerking wordt uitgevoerd door de Zabbix-server.

Zie ook:

• Details voorbewerking
• Testen van voorbewerking

• markeert, wordt het item niet onbeschikbaar als de voorbewerkingsstap mislukt, en het is mogelijk om aangepaste foutafhandelingsopties op te geven: de waarde negeren, een gespecificeerde waarde instellen of een gespecificeerd foutbericht instellen.| | |SNMP-wandelen naar JSON|Converteer SNMP-waarden naar JSON. Specificeer een veldnaam in JSON en het overeenkomstige SNMP-OID-pad. Veldwaarden worden ingevuld met waarden in het gespecificeerde SNMP-OID-pad.
  U kunt deze voorbewerkingsstap gebruiken voor SNMP OID-ontdekking.
  Vergelijkbare opmaakopties als in de stap SNMP-wandelwaarde zijn beschikbaar.
  Als u het selectievakje Aangepast bij mislukken markeert, wordt het item niet onbeschikbaar als de voorbewerkingsstap mislukt, en het is mogelijk om aangepaste foutafhandelingsopties op te geven: de waarde negeren, een gespecificeerde waarde instellen of een gespecificeerd foutbericht instellen.| |Aangepaste scripts|<|<| |<|JavaScript|Voer JavaScript-code in in het blok dat verschijnt wanneer u op het parameter-veld klikt of op het potloodpictogram.
  Merk op dat de beschikbare lengte van JavaScript afhankelijk is van de gebruikte database.
  Zie voor meer informatie: JavaScript voorbewerking| |Validatie|<|<| |<|Komt niet overeen met reguliere expressie|Geef een reguliere expressie op waaraan een waarde niet mag voldoen.
  Bijv. Error:(.*?)\.
  Als u het selectievakje Aangepast bij mislukken markeert, is het mogelijk om aangepaste foutafhandelingsopties op te geven: de waarde negeren, een gespecificeerde waarde instellen of een gespecificeerd foutbericht instellen.| |^|Controleer op fout in JSON|Controleer op een foutbericht op toepassingsniveau op de JSONPath-locatie. Stop met verwerken als dit slaagt en het bericht niet leeg is; anders ga verder met de waarde die voor deze voorbewerkingsstap was. Houd er rekening mee dat deze externe servicefouten aan de gebruiker worden gemeld zoals ze zijn, zonder extra informatie van de voorbewerkingsstap toe te voegen.
  Bijv. $.errors. Als een JSON zoals {"errors":"e1"} wordt ontvangen, wordt de volgende voorbewerkingsstap niet uitgevoerd.
  Als u het selectievakje Aangepast bij mislukken markeert, is het mogelijk om aangepaste foutafhandelingsopties op te geven: de waarde negeren, een gespecificeerde waarde instellen of een gespecificeerd foutbericht instellen.| |^|Controleer op fout in XML|Controleer op een foutbericht op toepassingsniveau op de xpath-locatie. Stop met verwerken als dit slaagt en het bericht niet leeg is; anders ga verder met de waarde die voor deze voorbewerkingsstap was. Houd er rekening mee dat deze externe servicefouten aan de gebruiker worden gemeld zoals ze zijn, zonder extra informatie van de voorbewerkingsstap toe te voegen.
  Er wordt geen fout gemeld in geval van mislukken bij het parseren van ongeldige XML.
  Ondersteund sinds 4.4.0.
  Als u het selectievakje Aangepast bij mislukken markeert, is het mogelijk om aangepaste foutafhandelingsopties op te geven: de waarde negeren, een gespecificeerde waarde instellen of een gespecificeerd foutbericht instellen.| |Vertraging|<|<| |<|Niet gewijzigd met heartbeat|Verwijder een waarde als deze niet is gewijzigd binnen de gedefinieerde tijdsperiode (in seconden).
  Positieve gehele getallen worden ondersteund om de seconden op te geven (minimaal - 1 seconde). Tijdsuffixen kunnen worden gebruikt in dit veld (bijv. 30s, 1m, 2u, 1d). Gebruikersmacro's en lage-niveaumontdekking macro's kunnen in dit veld worden gebruikt.<brSlechts één vertragingsoptie kan worden gespecificeerd voor een ontdekkingsitem.
  Bijv. 1m. Als dezelfde tekst twee keer in deze regel wordt doorgegeven binnen 60 seconden, wordt deze verwijderd.
  Opmerking: Het wijzigen van itemprototypen reset de vertraging niet. Vertraging wordt alleen gereset wanneer de voorbewerkingsstappen worden gewijzigd.| |Prometheus|<|<| |<|Prometheus naar JSON|Converteer vereiste Prometheus-metrics naar JSON.
  Zie Prometheus-controles voor meer details.|

Let op dat als de ontdekkingsregel op de host is toegepast via een template, de inhoud van dit tabblad alleen-lezen is.

Aangepaste macros

Het tabblad LLD macros maakt het mogelijk om aangepaste low-level discovery macros te specificeren.

Aangepaste macros zijn nuttig in gevallen waarin de geretourneerde JSON de benodigde macros nog niet heeft gedefinieerd. Bijvoorbeeld:

• De native sleutel vfs.fs.discovery voor het ontdekken van bestandssystemen retourneert een JSON met enkele vooraf gedefinieerde LLD-macros zoals {#FSNAME}, {#FSTYPE}. Deze macros kunnen direct worden gebruikt in item- en triggervoorbeelden (zie volgende secties van de pagina); het definiëren van aangepaste macros is niet nodig;
• Het agentitem vfs.fs.get retourneert ook een JSON met bestandssysteemgegevens, maar zonder enige vooraf gedefinieerde LLD-macros. In dit geval kunt u de macros zelf definiëren en ze toewijzen aan de waarden in de JSON met behulp van JSONPath:

De geëxtraheerde waarden kunnen worden gebruikt in ontdekte items, triggers, enz. Let op dat waarden worden geëxtraheerd uit het resultaat van de ontdekking en eventuele voorbewerkingen tot nu toe.

Filter

A filter can be used to generate real items, triggers, and graphs only for entities that match the criteria. The Filters tab contains discovery rule filter definitions allowing to filter discovery values:

Override

Het tabblad Override maakt het mogelijk om regels in te stellen om de lijst van item-, trigger-, grafiek- en host-prototypes of hun eigenschappen aan te passen voor ontdekte objecten die aan bepaalde criteria voldoen.

Overlays (indien aanwezig) worden weergegeven in een herordenable sleep-en-plaats lijst en worden uitgevoerd in de volgorde waarin ze zijn gedefinieerd. Om de details van een nieuwe overlay te configureren, klikt u op in het blok Overrides. Om een bestaande overlay te bewerken, klikt u op de naam van de overlay. Een pop-up venster wordt geopend waarmee u de details van de overlay-regel kunt bewerken.

Alle verplichte parameters zijn gemarkeerd met rode asterisken.

Configuratie van een operatie

Om de details van een nieuwe operatie te configureren, klikt u op in het blok Operaties. Om een bestaande operatie te bewerken, klikt u op naast de operatie. Er wordt een pop-up venster geopend waarin u de details van de operatie kunt bewerken.

These are the available form buttons and their respective operations:

• Add a discovery rule: Click this button to add a new discovery rule. This option is only available when creating new discovery rules.

• Update: Click this button to update the properties of an existing discovery rule. This button is visible when you're editing an existing discovery rule.

• Clone: Click this button to create a new discovery rule with the same properties as the current one. This can be useful if you want to create a similar discovery rule without starting from scratch.

• Check Now: Click this button to trigger the discovery process immediately based on the current discovery rule. This option is available for existing discovery rules. Keep in mind that using this option won't update the configuration cache, so recent changes to the discovery rule configuration might not be reflected immediately.

• Delete: Click this button to delete the discovery rule.

• Cancel: Click this button to cancel the editing of discovery rule properties. This can be used if you decide not to save any changes you've made.

The provided information discusses how discovered entities are managed and displayed in Zabbix, especially in relation to low-level discovery rules. Here's a breakdown of the key points:

1. Discovered Items, Triggers, and Graphs: The screenshots illustrate how discovered items, triggers, and graphs appear in the host's configuration. These entities are prefixed with an orange link that points back to the specific discovery rule that generated them.

   

2. Handling Duplicate Entities: If there are already existing entities with the same uniqueness criteria (e.g., a duplicate item key or graph name), Zabbix will not create new entities. An error message is displayed in such cases, indicating that certain entities could not be created. However, this won't affect the overall status of the discovery rule, and Zabbix will continue creating/updating other entities.

3. Automatic Deletion of Entities: Items, triggers, and graphs created by a low-level discovery rule will be automatically deleted if the discovered entity (e.g., file system, interface) stops being discovered or no longer meets the filter criteria. These entities are removed after a defined number of days specified in the "Keep lost resources period" field.

4. Lifetime Indicator for 'Not Discovered Anymore': When discovered entities are no longer being discovered, a lifetime indicator is shown in the item list. Hovering over this indicator displays a message indicating the number of days left until the item is deleted.

   

5. Delayed Deletion: If entities are marked for deletion but weren't deleted as expected (due to a disabled discovery rule or item host), they will be deleted the next time the discovery rule is processed.

6. Entities Containing Others: Entities that contain other entities (e.g., triggers containing items) won't update if they include items that are marked for deletion. For instance, if a low-level discovery-based trigger contains items set for deletion, the trigger won't update.

   

This information provides an overview of how Zabbix handles discovered entities generated through low-level discovery rules and how automatic deletion and maintenance of these entities work.

The provided information gives you pointers to other types of out-of-the-box discovery available in Zabbix and where you can find more detailed information about each type. Here's a summary of the different types of discovery mentioned:

1. Network Interfaces Discovery: Learn about discovering network interfaces and how to configure it in Zabbix: Network Interfaces Discovery.

2. CPUs and CPU Cores Discovery: Discover CPUs and CPU cores using Zabbix's low-level discovery: CPUs and CPU Cores Discovery.

3. SNMP OIDs Discovery: Discover SNMP OIDs and configure SNMP-based discovery in Zabbix: SNMP OIDs Discovery.

4. JMX Objects Discovery: Learn how to discover JMX objects and set up JMX-based discovery: JMX Objects Discovery.

5. ODBC SQL Queries Discovery: Discover using ODBC SQL queries and implement SQL-based discovery: ODBC SQL Queries Discovery.

6. Windows Services Discovery: Discover Windows services and configure service-based discovery: Windows Services Discovery.

7. Host Interfaces Discovery: Learn about discovering host interfaces in Zabbix: Host Interfaces Discovery.

Additionally, you can find more details about the JSON format for discovery items and an example of creating a custom file system discoverer as a Perl script in the section: Creating Custom Low-Level Discovery Rules.

This information provides an overview of the different types of out-of-the-box discovery available in Zabbix and directs you to specific sections for more detailed information on each type.

To create a custom low-level discovery (LLD) rule in Zabbix, you can follow these steps:

1. Create a Custom Item that Returns JSON: Write a script or command that outputs JSON with the information you want to discover. The JSON should follow a specific format with macro names and their corresponding values. For example, you can create a script that discovers databases on a server and outputs JSON like this:

   [
              { "{#DBNAME}": "database1", "{#DBTYPE}": "MySQL" },
              { "{#DBNAME}": "database2", "{#DBTYPE}": "PostgreSQL" }
          ]

2. Define LLD Macros: In your JSON output, use macro names surrounded by curly braces ({}) to represent the discovered values. In the example above, {#DBNAME} and {#DBTYPE} are macros that represent the discovered database name and type.

3. Create a Discovery Rule: In the Zabbix web interface, navigate to Configuration > Discovery and create a new discovery rule. Specify the name, type of discovery, and set the Key field to a unique identifier for your custom discovery.

4. Add LLD Macros to Discovery Rule: In the discovery rule configuration, add LLD macros for the properties you want to discover. For example, add {#DBNAME} and {#DBTYPE} macros to match the macros in your JSON output.

5. Configure the Discovery Filter: Define the regular expressions or conditions in the Filter field to match the discovered values against specific criteria. This ensures that only the relevant entities are created based on your custom LLD.

6. Create Prototypes: Create prototypes for items, triggers, and other entities based on the discovered values. Use the LLD macros in the prototype configuration to dynamically populate values from the discovered entities.

7. Apply and Monitor: Once your custom LLD rule is configured and prototypes are created, apply the rule to a host. Zabbix will execute the custom script, discover entities, and create items, triggers, and other entities based on the discovered information.

Remember to ensure that the JSON format and macro names in your custom script match the LLD macros you define in your discovery rule and prototype configurations. Custom LLD rules allow you to discover any type of entities and configure Zabbix to monitor them effectively.