Zabbix Agent Plugin
Zabbix is an Open Source network monitoring solution for monitoring of millions of metrics. This type of software is commonly used in NOC:s in many companies to monitor servers, switches and other hardware.
This integration allows exporting values in realtime from the platform. The plugin utilizes the discovery mechanisms in Zabbix to add hosts ant items.
Usage
The integration is configured for objects in the platform using meta-data. The following table describes what keys are needed for the integration to work properly.
Please note that for a function to be exported to Zabbix zabbix.exported needs to be set on the device and installation above. Not only the metric but also metadata from all the objects below is included in the data sent to Zabbix and can be picked up by the template.
| Object | Key | Type | Description |
|---|---|---|---|
| Installation | zabbix.exported | Boolean | If the installation have items to export into Zabbix |
| Device | zabbix.exported | Boolean | If the device should be exported to Zabbix |
| Function | zabbix.exported | Boolean | If the function should be exported to Zabbix (device must be exported) |
The key zabbix.name can be set on functions and devices to override the name in Lynx sent to Zabbix. That is useful if another name convention is used in Zabbix.
About the Agent Plugin
Overview
Meta-keys
There are two different meta-data used by this plugin.
The key zabbix.exported with value true is set on installations, devices and functions that should be handled by the plugin. The key is expected to exist on all exported items. Meaning that an installation with the key set on devices but not on the installation will not be picked up.
The key zabbix.name with any value can be set on devices and functions to override the name used in discoveries in Zabbix.
Communication
The plugin communicates in four different ways. Using the Agent interface to
communicate with the Zabbix server, using the Agent interface to send Zabbix
Traps for new messages, using the IoT Open HTTP API and using the IoT Open
MQTT broker.
The agent interface is integrated using the provided functionality of the Zabbix Agent2. This is an outgoing TCP connection from the Zabbix server to the Agent. This is used for Zabbix Server to initiate discoveries and fetch agent values if passive check are used.
The plugin also sends new values as soon as they are received using an outgoing connection to the Zabbix server. The messages are formatted according to the Zabbix protocol specification for Trap items. Traps are handled in batch, either once every 5 seconds or when more than 10 messages has been received.
The IoT Open HTTP API is used in the discovery process to fetch lists of installations, devices and functions. It is also used on agent items to get the latest reported value. The status endpoint is used to fetch latest known value for a function.
The IoT Open MQTT broker is used with a persistent connection to listen for incoming messages for all exported installations. Once a message is received it is matched to the functions in Redis. If a match is found, a trap is created.
Redis Cache
A Redis database is used to store functions and monitored installations client-id. The cache uses a timeout for functions specified by the configuration file. This timeout for the cache needs to be bigger than the discover interval set in Zabbix. A discovery will refresh the time for all exported functions.
A function stored in the cache will be used instead of hitting the API on every received MQTT message for speed and redundancy. If no exported function is found in the cache the message is not delivered to Zabbix.
Discovery
This plugin supports discovery features in Zabbix by exposing objects as hosts and items. The discoveries are included in the template collection.
Discoveries are run once every 12h by default, but can be run as often as needed. Discoveries can be triggered manually using the agent host and the discovery action. The default lifetime for discovered objects are 24h.
There are two discovery keys available, lynx.device.discovery and lynx.function.discovery[<installation-id>.<device-id>]. A third discovery key lynx.server.discovery is also provided but only used to check that the plugin is working.
Devices -> Hosts
A device will be exported as a host. The host can optionally have a different name set by meta-data (see above). The default template also includes the installation name in the shown device name. The host is identified by the name lynx.<installation-id>.<device-id>. All hosts are added to two groups: IoT and Discovered Hosts. Discovered host are created with the Lynx Device Trap template that includes function discovery.
A device is only exported as a host if the installation is also marked as exported.
Functions -> Items
A function will be added as an item on the host. It is required for the function to have an exported device connected to it for the plugin to work. The key of the created item are lynx.function.stats[<installation-id,function-id>].
A function is only exported as an item if the device and installation is marked as exported.
Preparations
Before usage of this plugin some steps need to be done on the Zabbix server.
Import templates
The templates provided together with the plugin need to be imported into Zabbix prior to setting up the agent. Modifications to the templates can always be made after import. However, modified templates are not guaranteed to work correctly.
If you don't like the template examples that comes with the Agent, you can create your own to make the data suit your needs in Zabbix exactly like you want.
Create agent host
The agent host need to be added manually before any discover process can begin. Add a new host and select the Lynx Agent template. The interface should specify the hostname and port where the agent is exposed.
The name of the host must match the name set in the Zabbix Agent configuration.
Set up a redis server
Your IoT Open partner will help you with this part.
The agent needs the Redis server available on startup as described above.
Configuration
Your IoT Open partner will help you with this part.
The configuration is loaded by the Zabbix agent. The agent automatically loads configuration files stored in /etc/zabbix/zabbix_agent2.d/plugins.d/.
Configuration parameters
Your IoT Open partner will help you with this part.
The following parameters are needed for this plugin to work correctly.
| Key | Description |
|---|---|
| Plugins.Lynx.System.Path | File path for plugin binary |
| Plugins.Lynx.System.Capacity | Plugin capacity, see Zabbix docs |
| Plugins.Lynx.BaseURL | URL to the Lynx server |
| Plugins.Lynx.APIKey | API-Key to access the Lynx server |
| Plugins.Lynx.Redis.Host | Hostname and port to Redis cache |
| Plugins.Lynx.Redis.Database | Redis database number |
| Plugins.Lynx.Redis.FunctionTimeout | Redis timeout for function storage |
| Plugins.Lynx.MQTT.ClientID | ClientID for MQTT connection |
| Plugins.Lynx.MQTT.Username | Username for MQTT connection |
| Plugins.Lynx.MQTT.Broker | Broker URL including port |
| Plugins.Lynx.MQTT.CleanSession | To use clean session for connections |
| Plugins.Lynx.MQTT.SubscriptionQoS | QoS Level for subscriptions |
| Plugins.Lynx.Zabbix.URL | Hostname and port to Zabbix server where traps are sent |
Running
Your IoT Open partner or Zabbix expert can help you with this part.
This integration is distributed as a docker image. The image is based on the official Zabbix Agent2 image with the binary added. Releases should follow the version tagging of the base Zabbix Container.
Read more about the Zabbix Agent2 image here
Docker run
Please note that you need an account on hub.iotopen.se in order to pull the image. There are also docker-compose-files available if you prefer to run it in Docker Compose.
Example execution for the container as follows:
docker run --rm -ti \
-v $PWD/lynx-integration.conf:/etc/zabbix/zabbix_agent2.d/plugins.d/lynx-integration.conf \
-v $PWD/lynx-integration.log:/tmp/lynx-integration.log \
-p 10050:10050 \
--name lynx-agent2 \
--hostname lynx-agent2 \
-e ZBX_SERVER_HOST=zabbix-server \
-e ZBX_PASSIVESERVERS=0.0.0.0/0 \
hub.iotopen.se/integrations/zabbix-agent-plugin:latest
Volumes
The application will output log data separated from Zabbix Agent log into a file at /tmp/lynx-integration.log. This file can be mounted inside the container to create a persistent log.
Ports
The default port exported by Zabbix agent2 is 10050.