14 Plugins

Plugins provide an option to extend the monitoring capabilities of Zabbix. The plugins are written in Go programming language and supported for Zabbix agent 2 only. They provide an alternative to loadable modules (written in C), and other methods for extending Zabbix functionality, such as user parameters (agent metrics), external checks (agent-less monitoring), and system.run[] Zabbix agent item .

The following features are specific to agent 2 and its plugins:

  • single configuration file (all plugin configuration parameters are located in the same file as parameters of the agent itself);

  • task queue management with respect to schedule and task concurrency;

  • plugin-level timeouts.

Plugins supplied out-of-the-box

All metrics supported for Zabbix agent 2 are collected by plugins. The following plugins for Zabbix agent 2 are available out-of-the-box:

Plugin nameDescriptionSupported item keysComments
AgentMetrics of the Zabbix agent being used.agent.hostname, agent.ping, agent.versionSupported keys have the same parameters as Zabbix agent keys.
CephCeph monitoring.ceph.df.details, ceph.osd.stats, ceph.osd.discovery, ceph.osd.dump,
ceph.ping, ceph.pool.discovery, ceph.status
Supported keys can be used with Zabbix agent 2 only.
CPUSystem CPU monitoring (number of CPUs/CPU cores, discovered CPUs, utilization percentage).system.cpu.discovery, system.cpu.num, system.cpu.utilSupported keys have the same parameters as Zabbix agent keys.
DockerMonitoring of Docker containers.docker.container_info, docker.container_stats, docker.containers, docker.containers.discovery,
docker.data_usage, docker.images, docker.images.discovery, docker.info, docker.ping
App Docker monitoring template is available.

Supported keys can be used with Zabbix agent 2 only.
FileFile metrics collection.vfs.file.cksum, vfs.file.contents, vfs.file.exists, vfs.file.md5sum,
vfs.file.regexp, vfs.file.regmatch, vfs.file.size, vfs.file.time
Supported keys have the same parameters as Zabbix agent keys.
KernelKernel monitoring.kernel.maxfiles, kernel.maxprocSupported keys have the same parameters as Zabbix agent keys.
LogLog file monitoring.log, log.count, logrt, logrt.countSupported keys have the same parameters as Zabbix agent keys.
MemcachedMemcached server monitoring.memcached.ping, memchached.statsApp Memchached monitoring template is available.

Supported keys can be used with Zabbix agent 2 only.
Mongo DBMonitoring of MongoDB servers and clusters (document-based, distributed database).mongodb.collection.stats, mongodb.collections.discovery, mongodb.collections.usage, mongodb.connpool.stats,
mongodb.db.stats, mongodb.db.discovery, mongodb.jumbo_chunks.count, mongodb.oplog.stats,
mongodb.ping, mongodb.rs.config, mongodb.rs.status, mongodb.server.status,
mongodb.sh.discovery
Supported MongoDB versions: 3.6, 4.0, 4.2, 4.4.

Requires a local read-only user in the admin database - follow the instructions for your configuration:
STANDALONE - create a user for each single MongoDB node;
REPLICASET - create a user on the primary node of the replica set;
SHARDING - create a user for each shard in the cluster (on the primary node of the replica set). Then, create the same user on a mongos router. It will be automatically passed to configuration servers.
  1. use admin
  2. db.auth(“admin”, “<ADMIN_PASSWORD>”)
  3. db.createUser({
  4. user”: zabbix”,
  5. pwd”: “<PASSWORD>”,
  6. roles”: [
  7. { role: readAnyDatabase”, db: admin },
  8. { role: clusterMonitor”, db: admin },
  9. ]
  10. })
Supported keys can be used with Zabbix agent 2 only.
Supported since 5.0.10
MySQLMonitoring of MySQL and its forks.mysql.db.discovery, mysql.db.size, mysql.get_status_variables,
mysql.ping, mysql.replication.discovery, mysql.replication.get_slave_status, mysql.version
DB MySQL by Zabbix agent 2 monitoring template is available.

Supported keys can be used with Zabbix agent 2 only.

Default configuration: URI=tcp://localhost:3306, username=root, password= .
NetIfMonitoring of network interfaces.net.if.collisions, net.if.discovery, net.if.in, net.if.out, net.if.totalSupported keys have the same parameters as Zabbix agent keys.
OracleOracle Database monitoring.oracle.diskgroups.stats, oracle.diskgroups.discovery, oracle.archive.info, oracle.archive.discovery,
oracle.cdb.info, oracle.custom.query, oracle.datafiles.stats, oracle.db.discovery,
oracle.fra.stats, oracle.instance.info, oracle.pdb.info, oracle.pdb.discovery,
oracle.pga.stats, oracle.ping, oracle.proc.stats, oracle.redolog.info,
oracle.sga.stats, oracle.sessions.stats, oracle.sys.metrics, oracle.sys.params,
oracle.ts.stats, oracle.ts.discovery, oracle.user.info
DB Oracle by Zabbix agent 2 monitoring template is available.

Install the Oracle Instant Client before using the plugin.

Supported keys can be used with Zabbix agent 2 only.

Default configuration: URI=tcp://localhost:1521, service=XE (service name).

Functionality of the plugin can be extended with custom user-defined queries - see plugin documentation for configuration examples.
PostgreSQLMonitoring of PostgreSQL and its forks.pgsql.ping, pgsql.db.discovery, pgsql.db.size, pgsql.db.age, pgsql.database.bloating_tables,
pgsql.replication_lag.sec, pgsql.replication_lag.b, pgsql.replication.count, pgsql.replication.status, pgsql.replication.recovery_role,
pgsql.cache.hit, pgsql.connections, pgsql.archive, pgsql.bgwriter, pgsql.dbstat.sum, pgsql.dbstat,
pgsql.wal.stat, pgsql.locks, pgsql.pgsql.oldest.xid, pgsql.uptime
DB PostgreSQL by Zabbix agent 2 monitoring template is available.

Supported keys can be used with Zabbix agent 2 only.
ProcProcess CPU utilization percentage.proc.cpu.utilSupported key has the same parameters as Zabbix agent key.
RedisRedis server monitoring.redis.config, redis.info, redis.ping, redis.slowlog.countDB Redis monitoring template is available.

Supported keys can be used with Zabbix agent 2 only.
SmartS.M.A.R.T. monitoring.smart.attribute.discovery, smart.disk.discovery, smart.disk.getSudo/root access rights to smartctl are required for the user executing Zabbix agent 2. The minimum required smartctl version is 7.1.

Supported keys can be used with Zabbix agent 2 only on Linux/Windows, both as a passive and active check.
Supported since Zabbix 5.0.9.
SwapSwap space size in bytes/percentage.system.swap.sizeSupported since Zabbix 5.0.5.
Supported key has the same parameters as Zabbix agent key.
SystemRunRuns specified command.system.runSupported key has the same parameters as Zabbix agent key.
SystemdMonitoring of systemd services.systemd.unit.discovery, systemd.unit.get, systemd.unit.infoSupported keys can be used with Zabbix agent 2 only.
TCPTCP connection availability check.net.tcp.portSupported key has the same parameters as Zabbix agent key.
UDPMonitoring of the UDP services avaiability and performance.net.udp.service, net.udp.service.perfSupported keys have the same parameters as Zabbix agent keys.
UnameRetrieval of information about the system.system.hostname, system.sw.arch, system.unameSupported keys have the same parameters as Zabbix agent keys.
UptimeSystem uptime metrics collection.system.uptimeSupported key has the same parameters as Zabbix agent key.
VFSDevVFS metrics collection.vfs.dev.discovery, vfs.dev.read, vfs.dev.writeSupported keys have the same parameters as Zabbix agent keys.
WebWeb page monitoring.web.page.get, web.page.perf, web.page.regexpSupported keys have the same parameters as Zabbix agent keys.
ZabbixAsyncAsynchronous metrics collection.net.tcp.listen, net.udp.listen, sensor, system.boottime, system.cpu.intr, system.cpu.load,
system.cpu.switches, system.hw.cpu, system.hw.macaddr, system.localtime, system.sw.os,
system.swap.in, system.swap.out, vfs.fs.discovery
Supported keys have the same parameters as Zabbix agent keys.
ZabbixStatsZabbix server/proxy internal metrics or number of delayed items in a queue.zabbix.statsSupported keys have the same parameters as Zabbix agent keys.
ZabbixSyncSynchronous metrics collection.net.dns, net.dns.record, net.tcp.service, net.tcp.service.perf, proc.mem,
proc.num, system.hw.chassis, system.hw.devices, system.sw.packages,
system.users.num, vfs.dir.count, vfs.dir.size, vfs.fs.get, vfs.fs.inode,
vfs.fs.size, vm.memory.size.
Supported keys have the same parameters as Zabbix agent keys.

Configuring plugins

Common configuration principles and best practices are described in this section.

For specific examples of plugin configuration see also:

All plugins are configured using Plugins.* parameter of the Zabbix agent 2 configuration file. Unlike other agent parameters, it is not a key/value type of parameter. It is a separate section where specific parameters of the plugin can be described. Each parameter should have the following structure:

Plugins.<PluginName>.<Parameter>=<Value>

Parameter names should adhere to the following requirements:

  • it is recommended to capitalize the names of your plugins;

  • the parameter should be capitalized;

  • special characters are not allowed;

  • nesting isn’t limited by a maximum level;

  • the number of parameters is not limited.

Named sessions

Named sessions represent an additional level of plugin parameters and can be used to define separate sets of authentication parameters for each of the instances being monitored. Each named session parameter should have the following structure:

Plugins.<PluginName>.<SessionName>.<Parameter>=<Value>

A session name can be used as a connString item key parameter instead of specifying a URI, username, and password separately. In item keys, the first parameter can be either a connString or a Uri. If the first key parameter matches a session name specified in the configuration file, the check will be executed using named session parameters. If the first key parameter doesn’t match any session name, it will be treated as a Uri.

Note, that:

  • when providing a connString (session name) in key parameters, key parameters for username and password must be empty;

  • passing embedded URI credentials is not supported, consider using named sessions instead;

  • in case an authentication parameter is not specified for the named session, a hardcoded default value will be used.

The list of available named session parameters depends on the plugin, see Zabbix agent 2 (UNIX) / Zabbix agent 2 (Windows) for details.

Example: Monitoring of two instances “MySQL1” and “MySQL2” can be configured in the following way:

  1. Plugins.Mysql.Sessions.MySQL1.Uri=tcp://127.0.0.1:3306
  2. Plugins.Mysql.Sessions.MySQL1.User=<UsernameForMySQL1>
  3. Plugins.Mysql.Sessions.MySQL1.Password=<PasswordForMySQL1>
  4. Plugins.Mysql.Sessions.MySQL2.Uri=tcp://127.0.0.1:3307
  5. Plugins.Mysql.Sessions.MySQL2.User=<UsernameForMySQL2>
  6. Plugins.Mysql.Sessions.MySQL2.Password=<PasswordForMySQL2>

Now, these names may be used as connStrings in keys instead of URIs:

  1. mysql.ping[MySQL1]
  2. mysql.ping[MySQL2]
Hardcoded defaults

If a parameter required for authentication is not provided in an item key or in the named session parameters, the plugin will use a hardcoded default value.

Connections

Some plugins support gathering metrics from multiple instances simultaneously. Both local and remote instances can be monitored. TCP and Unix-socket connections are supported.

It is recommended to configure plugins to keep connections to instances in an open state. The benefits are reduced network congestion, latency, and CPU and memory usage due to the lower number of connections. The client library takes care of this.

Time period for which unused connections should remain open can be determined by Plugins.<PluginName>.KeepAlive parameter.
Example: Plugins.Memcached.KeepAlive

Writing plugins

A plugin is a Go package that defines the structure and implements one or several plugin interfaces (Exporter, Collector, Runner, Watcher):

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

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

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

Implementation steps

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

  1. import "zabbix.com/pkg/plugin"

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

  1. type Plugin struct {
  2. plugin.Base
  3. }
  4. var impl Plugin

A plugin must implement one or several plugin interfaces.

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

A plugin must register itself during initialization.

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

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