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, Configurator, Runner, Watcher).
Plugins are supported only by Zabbix agent 2. Since Zabbix 6.0 two types of Zabbix agent 2 plugins are supported:
To ensure that the plugin meets all the quality requirements, the guidelines given in corresponding sub pages for building loadable or built-in plugins should be followed.
Note that loadable plugins have an advantage compared to the built-in plugins, as the loadable ones do not require recompiling Zabbix agent while agent upgrading process.
Since Zabbix 6.0, all the built-in plugin configuration parameters are located in Zabbix agent 2 source code. All the configuration parameters for loadable plugins are located in a separate repository.
By default, plugins are inactive and activated only when a metric is provided by the plugin being monitored.
Built-in plugins are located in the plugin directory tree, grouped by meaning, for example plugins/system/uptime/uptime.go
.
The following plugin interfaces are available:
Exporter is the simplest interface that performs a poll and returns a value (values), nothing, or error. It accepts a preparsed item key, parameters and context. Exporter interface is the only interface that can be accessed concurrently. Access to all the other plugin interfaces 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 according to the requirements for each plugin.
Collector is used when a plugin needs to collect data at regular intervals. This interface is usually used together with the Exporter interface to export the collected data.
Configurator is used to provide a plugin its configuration parameters from the agent 2 configuration files.
Runner interface provides the means for 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.
Watcher allows a plugin to implement polling of its own metric, without using the agent's internal scheduler, for example in trap-based plugins.
Loadable Zabbix agent 2 plugins are supported since Zabbix 6.0.0. Such plugins are kept in a separate repository, but use a shared with Zabbix agent 2 package.
Loadable plugins need to be compiled and built separately. Plugin configuration shall be provided in a separate Zabbix agent 2 configuration file in the same way as it is provided for built-in plugins.
Loadable plugins support the following interfaces: - Exporter (except the ContextProvider parameter) - Runner - Configurator
Watcher and Collector interfaces are not supported.
Several loadable plugins are available in Zabbix source code and can be used as examples for development or testing.
To avoid creating duplicate plugins, make sure that a plugin does not already exist in Zabbix. Existing built-in plugins are available in Zabbix Git repository. Existing loadable pluginscan be checked here.
Zabbix agent 2 plugins are developed separately, but if changes in the Plugin Support library are required it is necessary to follow Plugin Support development guidelines.
When updating plugin-support (Zabbix agent 2 Plugins/Plugin Support) project, the go.mod
and go.sum
files in Zabbix repository of (Zabbix/Zabbix) project must be updated to reference the updated plugin-support version by commit hash:
go get git.zabbix.com/ap/[email protected]"plugin-support commit hash"
(this will update the required version in go.mod and go.sum) commit/push updated go.mod and go.sum in Zabbix development branchgo get git.zabbix.com/ap/[email protected]"plugin-support commit hash"
(this will update the required version in go.mod and go.sum)go get git.zabbix.com/ap/[email protected]"plugin-support commit hash"
(this will update the required version in go.mod and go.sum)The protocol is based on code, size and data model.
Code
Type | Size | Comments |
---|---|---|
Byte | 4 | Payload type, currently only JSON is supported. |
Size
Type | Size | Comments |
---|---|---|
Byte | 4 | Size of the current payload in bytes. |
Payload data
Type | Size | Comments |
---|---|---|
Byte | Defined by the Size field | JSON formatted data. |
Common data
These parameters are present in all requests/responses:
Name | Type | Comments |
---|---|---|
id | uint32 | For requests - the incrementing identifier used to link requests with responses. Unique within a request direction (i.e. from agent to plugin or from plugin to agent). For responses - ID of the corresponding request. |
type | uint32 | The request type. |
Log request
A request sent by a plugin to write a log message into the agent log file.
direction | plugin → agent |
response | no |
Parameters specific to log requests:
Name | Type | Comments |
---|---|---|
severity | uint32 | The message severity (log level). |
message | string | The message to log. |
Example:
Register request
A request sent by the agent during the agent startup phase to obtain provided metrics to register a plugin.
direction | agent → plugin |
response | yes |
Parameters specific to register requests:
Name | Type | Comments |
---|---|---|
version | string | The protocol version <major>.<minor> |
Example:
Register response
Plugin's response to the register request.
direction | plugin → agent |
response | n/a |
Parameters specific to register responses:
Name | Type | Comments |
---|---|---|
name | string | The plugin name. |
metrics | array of strings (optional) | The metrics with descriptions as used in the plugin. Returns RegisterMetrics(). Absent if error is returned. |
interfaces | uint32 (optional) | The bit mask of plugin's supported interfaces. Absent if error is returned. |
error | string (optional) | An error message returned if a plugin cannot be started. Absent, if metrics are returned. |
Examples:
or
Start request
A request to execute the Start function of the Runner interface.
direction | agent → plugin |
response | no |
The request doesn't have specific parameters, it only contains common data parameters.
Example:
Terminate request
A request sent by the agent to shutdown a plugin.
direction | agent → plugin |
response | no |
The request doesn't have specific parameters, it only contains common data parameters.
Example:
Export request
A request to execute the Export function of the Exporter interface.
direction | agent → plugin |
response | no |
Parameters specific to export requests:
Name | Type | Comments |
---|---|---|
key | string | The plugin key. |
parameters | array of strings (optional) | The parameters for Export function. |
Example:
Export response
Response from the Export function of the Exporter interface.
direction | plugin → agent |
response | n/a |
Parameters specific to export responses:
Name | Type | Comments |
---|---|---|
value | string (optional) | Response value from the Export function. Absent, if error is returned. |
error | string (optional) | Error message if the Export function has not been executed successfully. Absent, if value is returned. |
Examples:
or
Configure request
A request to execute the Configure function of the Configurator interface.
direction | agent → plugin |
response | n/a |
Parameters specific to Configure requests:
Name | Type | Comments |
---|---|---|
global_options | JSON object | JSON object containing global agent configuration options. |
private_options | JSON object (optional) | JSON object containing private plugin configuration options, if provided. |
Example:
Validate Request
A request to execute Validate function of the Configurator interface.
direction | agent → plugin |
response | yes |
Parameters specific to Validate requests:
Name | Type | Comments |
---|---|---|
private_options | JSON object (optional) | JSON object containing private plugin configuration options, if provided. |
Example:
Validate response
Response from Validate function of Configurator interface.
direction | plugin → agent |
response | n/a |
Parameters specific to Validate responses:
Name | Type | Comments |
---|---|---|
error | string (optional) | An error message returned if the Validate function is not executed successfully. Absent if executed successfully. |
Example:
or