Zabbix Code Guidelines

Sidebar

plugins

Plugins

Zabbix plugin development guidelines

Plugins provide an option to extend monitoring capabilities of Zabbix. A plugin is a Go package that defines the structure and implements one or several plugin interfaces (Exporter, Collector, Runner, Watcher). To ensure that the plugin meets all the quality requirements, the following guidelines should be used.

Plugins are supported by Zabbix agent 2 only. All plugin configuration parameters are located in the same file as parameters of the agent 2 itself.

By default, plugins are inactive and activated only when a metric is provided by the plugin being monitored.

Plugins are located in the plugin directory tree, grouped by meaning, for example plugins/system/uptime/uptime.go.

Plugin interfaces

The following plugin interfaces are available:

  • plugin.Exporter

Exporter is the simplest interface that performs a poll and returns a value (values), nothing, error. It accepts a preparsed item key, parameters and context. Exporter interface is the only interface that can be accessed concurrently. All other plugin interface access is exclusive and no method can be called when a plugin is already performing some task. Also, there is a limit of 100 maximum concurrent Export() calls per plugin, which can be reduced as necessary for each plugin.

  • plugin.Collector

Collector is used when a plugin needs to collect data at regular intervals. This interface usually is used together with the Exporter interface to export the collected data.

  • plugin.Configurator

Configurator is used to provide plugin its configuration parameters from the agent 2 configuration file.

  • plugin.Runner

Runner interface provides the means of performing some initialization when a plugin is started (activated) and deinitialization when a plugin is stopped (deactivated). For example, a plugin could start/stop some background goroutine by implementing the Runner interface.

  • plugin.Watcher

Watcher allows the plugin to implement its own metric polling, without using the agent's internal scheduler, for example in trap-based plugins.

Implementation steps

A plugin must import the zabbix.com/pkg/plugin package.

import "zabbix.com/pkg/plugin"

A plugin must define the structure and embed the plugin.Base structure.

type Plugin struct {
    plugin.Base
}
var impl Plugin

A plugin must implement one or several plugin interfaces.

func (p *Plugin) Export(key string, params []string, ctx plugin.ContextProvider) (result interface{}, err error) {
    if len(params) > 0 {
        p.Debugf("received %d parameters while expected none", len(params))
        return nil, errors.New("Too many parameters")
    }
    return time.Now().Format(time.RFC3339)
}

A plugin must register itself during initialization.

func init() {
    plugin.RegisterMetrics(&impl, "Time", "system.time", "Returns time string in RFC 3999 format.")
}

where RegisterMetrics parameters are:

  • Pointer to the plugin implementation
  • Plugin name (upper camel case)
  • Metric #1 name (item key)
  • Metric #1 description (starting with an uppercase character and ending with a dot)
  • Metric #2 name (item key) (optional)
  • Metric #2 description (starting with an uppercase character and ending with a dot) (optional)

If logging is necessary the plugin must use the logging functionality provided by plugin.Base (see the example above). It's basically a wrapper around standard logging, but it will prefix log messages with [<plugin name>].

Documentation

The last (but not the least) step of creating a good plugin is to create a Readme file containing the following information:

  • A short description of the plugin.
  • Plugin configuration parameters and steps required for configuring connection with the system being monitored.
  • A list of supported keys.
  • Known limitations/problems (if any).

Existing plugins

To avoid creating duplicate plugins, make sure that a plugin doesn't already exist in Zabbix. Existing plugins are available in Zabbix Git repository