Documentation
Table of Contents
Create a plugin (tutorial)
This is a step-by-step tutorial on how to create a simple loadable plugin for Zabbix agent 2.
You can also use the example repository as a template or guide for creating your own plugins.
What you'll create
This tutorial demonstrates how to create a new loadable plugin MyIP. The plugin will implement a single item key, myip, which returns the external IP address of the host where Zabbix agent 2 is running.
Step 1: Setup
- A plugin is a standard Go module. Start by initializing the
go.modfile in the plugin directory to track plugin dependencies:
- Install the mandatory dependency Zabbix Go SDK (
golang.zabbix.com/sdk):
Replace $LATEST_COMMIT_HASH with the latest HEAD commit hash from the golang.zabbix.com/sdk repository in the appropriate release branch. For example:
Note that golang.zabbix.com/sdk versioning is currently not supported, but this may change in the future.
Additional dependencies can be installed as needed using go get.
- Create an empty
main.gofile for the plugin source code:
Now the initial setup is complete, and the plugin is ready for development.
Step 2: Plugin structure
The golang.zabbix.com/sdk module, installed in the previous step, provides the necessary framework for plugin development and ensures all plugins have a consistent structure.
- Set up basic execution flow.
Start by defining the main execution flow of the plugin. Add the following code to main.go:
package main
func main() {
err := run()
if err != nil {
panic(err)
}
}
func run() error {
return nil
}This establishes the basic execution flow for the plugin. The run function will later contain the core logic of the plugin.
- Explore the plugin interfaces.
A Zabbix agent 2 plugin shall be represented by a struct that implements interfaces from the golang.zabbix.com/sdk/plugin package:
- Accessor - defines essential methods all plugins must implement, such as setting the plugin name and handling item key timeouts.
- One or more of the following functional plugin interfaces:
- Exporter - performs a poll and returns a value (or values), nothing, or an error; often used alongside the Collector interface.
- Collector - manages the periodic collection of data.
- Runner - defines plugin startup and shutdown procedures.
- Watcher - allows to implement independent metric polling, bypassing the agent's internal scheduler; useful for trap-based or event-driven monitoring.
- Configurator - defines how the plugin reads and applies its configuration settings.
You can either implement these interfaces yourself or use the default ones provided by the Zabbix Go SDK, modifying them as needed. This tutorial uses the default implementations.
- Create the plugin struct.
Now, import the plugin package and create a myIP struct that embeds the plugin.Base struct:
The myIP struct currently satisfies the Accessor interface. A method for implementing one of the functional plugin interfaces, the Exporter, will be added later in the tutorial.
Step 3: Define item keys
Your plugin needs the item keys to collect data and provide it to Zabbix server or proxy.
- Import errs package for error handling:
- Register item keys using the
plugin.RegisterMetrics()function within therun()function:
func run() error {
p := &myIP{}
// Register the `myip` item key.
err := plugin.RegisterMetrics(
p,
"MyIP", // Plugin name
"myip", // Item key name
"Returns the host's IP address.", // Item key description
)
if err != nil {
return errs.Wrap(err, "failed to register metrics")
}
return nil
}To register several item keys, repeat the parameters metric name and description for each metric. For example:
plugin.RegisterMetrics(&impl, "Myip", "metric.one", "Metric one description.", "metric.two", "Metric two description.")Step 4: Set up the handler
The handler facilitates communication between the agent and the plugin.
- Import the container package:
- Indise the
run()function add code to create and set up a handler:
func run() error {
p := &myIP{}
// Register the `myip` item key.
err := plugin.RegisterMetrics(
p,
"MyIP", // Plugin name
"myip", // Item key name
"Returns the host's IP address.", // Item key description
)
if err != nil {
return errs.Wrap(err, "failed to register metrics")
}
// Create a new handler.
h, err := container.NewHandler("MyIP") // Plugin name
if err != nil {
return errs.Wrap(err, "failed to create new handler")
}
// Setup logging to forward logs from the plugin to the agent.
// Available via p.Logger.Infof, p.Logger.Debugf, etc.
p.Logger = h
// Start plugin execution.
// Blocks until a termination request is received from the agent.
err = h.Execute()
if err != nil {
return errs.Wrap(err, "failed to execute plugin handler")
}
return nil
}Step 5: Implement data collection
Data collection is done via the Exporter interface, which describes the Export method:
func Export(
key string, // The item key to collect.
params []string, // Arguments passed to the item key (`myip[arg1, arg2]`).
context ContextProvider // Metadata about the item key data collection.
) (any, error)- Import the required packages for HTTP requests and response reading:
import (
"io"
"net/http"
)- Implement the
Exportmethod for themyIPstruct:
func (p *myIP) Export(
key string, params []string, context plugin.ContextProvider,
) (any, error) {
// The plugin can use different data collection logic based on the `key` parameter.
// This implementation only verifies that the provided `key` is supported.
if key != "myip" {
return nil, errs.Errorf("unknown item key %q", key)
}
// The log will get forwarded to the agent 2 log.
p.Infof(
"received request to handle %q key with %d parameters",
key,
len(params),
)
// Collect the data and return it.
resp, err := http.Get("https://api.ipify.org")
if err != nil {
return nil, errs.Wrap(err, "failed to get IP address")
}
defer resp.Body.Close()
body, err := io.ReadAll(resp.Body)
if err != nil {
return nil, errs.Wrap(err, "failed to read response body")
}
return string(body), nil
}Step 6: Build and configure the plugin
- To build the plugin, run:
This should create an executable myip in the current directory.
- Configure Zabbix agent 2 to use the plugin:
echo "Plugins.MyIP.System.Path=$PATH_TO_THE_MYIP_PLUGIN_EXECUTABLE" > /etc/zabbix_agent2.d/plugins.d/myip.confReplace $PATH_TO_THE_MYIP_PLUGIN_EXECUTABLE with the path to the myip created in step 5.
The plugin name in the configuration parameter name (MyIP in this tutorial) must match the plugin name defined in the plugin.RegisterMetrics() function.
- To test the plugin and its
myipitem, run:
The output should contain an external IP address of your host and look similar to this:
myip [s|192.0.2.0]With that, you have created a simple loadable plugin for Zabbix agent 2. Congrats!
Complete source code
package main
import (
"io"
"net/http"
"golang.zabbix.com/sdk/errs"
"golang.zabbix.com/sdk/plugin"
"golang.zabbix.com/sdk/plugin/container"
)
var _ plugin.Exporter = (*myIP)(nil)
type myIP struct {
plugin.Base
}
func main() {
err := run()
if err != nil {
panic(err)
}
}
func run() error {
p := &myIP{}
// Register the `myip` item key.
err := plugin.RegisterMetrics(
p,
"MyIP", // Plugin name
"myip", // Item key name
"Returns the host's IP address.", // Item key description
)
if err != nil {
return errs.Wrap(err, "failed to register metrics")
}
// Create a new handler.
h, err := container.NewHandler("MyIP") // Plugin name
if err != nil {
return errs.Wrap(err, "failed to create new handler")
}
// Setup logging to forward logs from the plugin to the agent.
// Available via p.Logger.Infof, p.Logger.Debugf, etc.
p.Logger = h
// Start plugin execution.
// Blocks until a termination request from the agent is received.
err = h.Execute()
if err != nil {
return errs.Wrap(err, "failed to execute plugin handler")
}
return nil
}
func (p *myIP) Export(
key string, params []string, context plugin.ContextProvider,
) (any, error) {
// The plugin can use different data collection logic based on the `key` parameter.
// This implementation only verifies that the provided `key` is supported.
if key != "myip" {
return nil, errs.Errorf("unknown item key %q", key)
}
// The log will get forwarded to the agent 2 log.
p.Infof(
"received request to handle %q key with %d parameters",
key,
len(params),
)
// Collect the data and return it.
resp, err := http.Get("https://api.ipify.org")
if err != nil {
return nil, errs.Wrap(err, "failed to get IP address")
}
defer resp.Body.Close()
body, err := io.ReadAll(resp.Body)
if err != nil {
return nil, errs.Wrap(err, "failed to read response body")
}
return string(body), nil
}