Áú»¢¶Ä²©

Creating plugins

Áú»¢¶Ä²© plugin development guidelines

Plugins provide an option to extend monitoring capabilities of Áú»¢¶Ä²©. 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 Áú»¢¶Ä²© agent 2. Since Áú»¢¶Ä²© 6.0 two types of Áú»¢¶Ä²© agent 2 plugins are supported:

• built-in plugins
• loadable plugins

Since Áú»¢¶Ä²© 6.0, all the built-in plugin configuration parameters are located in . All the configuration parameters for , including an example repository, , 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.

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

• plugin.Collector

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.

• plugin.Configurator

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

• plugin.Runner

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.

• plugin.Watcher

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

Existing plugins

Loadable Áú»¢¶Ä²© agent 2 plugins are supported since Áú»¢¶Ä²© 6.0.0. Such plugins are kept in a separate repository, but use a shared with Áú»¢¶Ä²© agent 2 package.

Loadable plugins need to be compiled and built separately. Plugin configuration shall be provided in a separate Áú»¢¶Ä²© 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

To avoid creating duplicate plugins, make sure that a plugin does not already exist in Áú»¢¶Ä²©. Existing built-in plugins are available in Áú»¢¶Ä²© . Existing can be checked here.

Development guidelines

Plugin development guidelines

Áú»¢¶Ä²© 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.

Plugin Support development guidelines

When updating plugin-support (Áú»¢¶Ä²© agent 2 Plugins/Plugin Support) project, the go.mod and go.sum files in must be updated to reference the updated plugin-support version by commit hash:

• Create a corresponding development branch for Áú»¢¶Ä²©, even if only a plugin-support project will be changed.
• Update go.mod and go.sum files in the corresponding Áú»¢¶Ä²© development branch:
  • Development process:
    • push changes to plugin-support development branch
    • navigate to Áú»¢¶Ä²© development branch src/go directory
    • do go get git.zabbix.com/ap/plugin-support@"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 Áú»¢¶Ä²© development branch
  • Merging development branch into upstream:
    • merge plugin-support development branch
    • navigate to Áú»¢¶Ä²© development branch src/go directory
    • do go get git.zabbix.com/ap/plugin-support@"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 Áú»¢¶Ä²© development branch
    • merge Áú»¢¶Ä²© development branch
  • Cherry-picking merge commit into other version branches:
    • cherry-pick plugin-support merge commit into other version
    • cherry-pick Áú»¢¶Ä²© merge commit into other version
    • navigate to Áú»¢¶Ä²© version branch src/go directory
    • do go get git.zabbix.com/ap/plugin-support@"plugin-support commit hash" (this will update the required version in go.mod and go.sum)
    • amend the cherry-pick by adding updated go.mod and go.sum
    • push the changes to Áú»¢¶Ä²© project