Probe development guide
Last updated
Last updated
Any probe should gather metrics from a set of hosts and send them to a central zabbix server. As this is a straightforward process, some utility classes have been created in the zabbix-probes-common project
All probes should have some form of configuration, for example, under which credentials they are operating, what's the system path to some certificates or what's the URL to an authorization system. To easen this task, the class PropertiesManager will take care of:
Loading a configuration file that will reside in C:\zabbix folder for Windows hosts and /etc/zabbix folder for Linux ones. Calling PropertiesManager.loadProperties(fileName) method will try to read properties from either C:\\zabbix\fileName or /etc/zabbix/fileName
Loading a configuration file that will be somewhere else. To do so, use the overloaded method PropertiesManager.loadProperties(Reader confFile) that will accept a reader pointing to any stream
This method should be called just once upon initialization of the probe and after that, properties can be read with the operation PropertiesManager.getProperty(String property), PropertiesManager.getProperty(String property, String defaultValue) or PropertiesManager.getListProperty(String property) for properties that accept a list as a value. Talking about lists, this class will use so it will accept any format configuration file as defined
As the behavior of the zabbix probes has some components in common, some properties are expected to be provided in every configuration file:
zabbix.ip: IP to the central zabbix server
zabbix.port: This property is optional. If not present, the data will be sent to ${zabbix.ip}:10051, which is the default zabbix port
zabbix.wrapper.location: A URL with the location of the Zabbix Wrapper that the probe will use to register hosts dynamically.
Apart from that, every probe is free to define as much properties as they are needed.
The next step after reading the configuration is getting useful metrics from some host. To do so, there has to be an implementation of the class MetricsCollector. Please, notice that this is a very simple interface with just one method:
ZabbixMetrics getMetrics(): This method should communicate with the host to monitor, gather the required metrics and then return them.
ZabbixMetrics class should contain the metrics gathered from a single host. As such it has the following properties to fill:
String hostName: Name of the host in which the metrics were gathered. If the host name is not already registered in the server, it will be automatically registered under this name
Map<String, String> metrics: A key-value map with the metrics
long timestamp: The timestamp in which the metrics were gathered
Metrics collected by a collector will be sent to the configured central server by the class ZabbixClient. This class will do all the work by itself by:
Checking that the host is registered through the ZabbixWrapperClient class
If not, register it
Upon completion, it will return the result of the operation
State of the operation: if it has been successful or not
Number of processed elements
Number of failed elements
I'm sorry to not give much more information but Zabbix doesn't return anything else.
Zabbix probes are designed to be standalone Java applications running as a cron job. As such, for simple cases, ProbeThread class is offered to help in the development of new probes. This class is generic and it should be parametrized with a class that extends MetricsCollection. Extending this abstract class will force the implementation of the method
T createCollector(): Where T should implement MetricsCollector. This method is basically a way to initialize the collector, which will do the metrics collection job as its name implies. Note that your implementation may need some initialization upon creation so this is the place to do it.
Your class should contain a main method and this method should call SenderResult run(String propertiesFile) method that will read your configuration file, call the collector which will get the metrics and then send them to the central service.
Some probes will get metrics of a host by doing a series of actions that will spawn something in the host, then check that it's working and then destroying this test object. That object can be a container, a job, a virtual machine, etc. To help in the development of this situation, we offer the class LifecycleCollector. This class depend on the existence of a template with the following properties:
<op>.status: A boolean with the success status of the operation
<op>.result: With a code result of the operation. Usually this will be an HTTP result returned by the monitored host but it can be given any other meaning.
<op>.responseTime: With the time it took to execute the operation
To all this, <op> will be an operation of:
clear: This one is executed at the beginning of the cycle to clear any possible remaining of a previously run job
create: This operation will be responsible of creating the object
run: This operation is responsible of verifying that the object is being run
delete: This operation is responsible of deleting the object to finish its lifecycle
The operations will be run in sequential order and they depend one on another, so an unsuccessful create, for example, will mean that run and delete will not be run and will be returned as failed automatically.
All this is achieved by extending the LifecycleCollector class which will force the implementation of the above mentioned operations. Aditionally it will force the implementation of the method String getHostName() which should return the name of the host which is being monitored.
For some examples of how to implement this, please have a look at the classes ChronosCollector and MarathonCollector in the mesos-zabbix-probe project which implement collectors that manage the lifecycle of jobs and containers.
Once registered, send the data present in ZabbixMetrics by using so there is no need to install the zabbix agent on the same machine in which the probe is operating.
ProbeThread(String category, String group, String template): Notice that this class doesn't have a default empty constructor. That will force you to call the protected default constructor by passing the probe category, group and template under which it will operate. This properties will be used to register hosts dynamically with the Zabbix Wrapper. For more information about this, please see the
Much of the communication with external systems will be done by calling REST interfaces. To easily create REST clients, we can use . This framework uses annotated interfaces to easily create REST clients with minimal boilerplate code. For concrete examples, you can have a look at the and for concrete examples you can have a look at the MesosClient class in mesos-zabbix-probe project of ZabbixWrapperClient in the zabbix-probes-common project. As a helper to create simple clients that communicate with JSON objects, the class ProbeClientFactory provides a T getClient(Class<T> clientClass, String baseUrl) method that, given an annotated interface and a base URL, will return a fully functional REST client.