14 插件

插件扩展了Zabbix监控功能。这些插件是用Go编程语言编写的，只支持Zabbix agent2。它们提供了可加载模块（用C编写）和其它扩展Zabbix功能的方法，例如用户参数（agent指标），外部检查（无agent监控）和system.run[] Zabbix agent监控项 。

以下是agent2及其插件功能：

*单个配置文件（所有插件配置参数与agent本身的参数位于同一个文件中)；
       *基于调度和任务并发的任务队列管理；
       *插件级超时。

开箱即用的插件

所有支持Zabbix agent2的指标都由插件收集。以下是Zabbix agent2可直接使用插件：

配置插件

本节介绍了常见的配置原则和最佳实践。

有关插件配置的具体示例，请参见：

• Ceph
• Memcached
• MySQL
• Oracle
• PostgreSQL
• Redis

所有插件都是使用Zabbix agent2的plugins.*参数配置文件配置的。与其它agent参数不同，它不是参数的键/值类型。它是一个单独的部分，可以描述插件的特定参数。每个参数应具有以下结构：

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

参数名称应符合以下要求：

• 建议将插件的名称大写；
• 参数应大写；
• 不允许使用特殊字符；
• 嵌套不受最大级别的限制；
• 参数的数量不受限制。

Default values

Since Zabbix 5.0.35, you can set default values for the connection-related parameters (URI, username, password, etc.) in the configuration file in the format:

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

For example, Plugins.Mysql.Default.Username=zabbix, Plugins.MongoDB.Default.Uri=tcp://127.0.0.1:27017, etc.

If a value for such parameter is not provided in an item key or in the named session parameters, the plugin will use the default value. If a default parameter is also undefined, hardcoded defaults will be used.

Named sessions

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

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

A session name can be used as a connString item key parameter instead of specifying a URI, username, and/or password separately.

In item keys, the first parameter can be either a connString or a URI. If the first key parameter doesn't match any session name, it will be treated as a URI. Note that embedding credentials into a URI is not supported, use named session parameters instead.

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

In Zabbix versions before 5.0.34, when providing a connString (session name) in key parameters, item key parameters for username and password must be empty. The values will be taken from the session parameters. If an authentication parameter is not specified for the named session, a hardcoded default value will be used.

Since Zabbix 5.0.34, it is possible to override session parameters by specifying new values in the item key parameters (see example).

Since Zabbix 5.0.35, if a parameter is not defined for the named session, Zabbix agent 2 will use the value defined in the default plugin parameter.

Parameter priority

Since version 5.0.34, Zabbix agent 2 plugins search for connection-related parameter values in the following order:

1. The first item key parameter is compared to session names. If no match is found it is treated as an actual value; in this case, step 3 will be skipped. If a match is found, the parameter value (usually, a URI) must be defined in the named session.
2. Other parameters will be taken from the item key if defined.
3. If an item key parameter (for example, password) is empty, plugin will look for the corresponding named session parameter.
4. If the session parameter is also not specified, the value defined in the corresponding default parameter will be used.
5. If all else fails, the plugin will use the hardcoded default value.

Example 1

Monitoring of two instances “MySQL1” and “MySQL2”.

Configuration parameters:

Plugins.Mysql.Sessions.MySQL1.Uri=tcp://127.0.0.1:3306
       Plugins.Mysql.Sessions.MySQL1.User=mysql1_user
       Plugins.Mysql.Sessions.MySQL1.Password=unique_password
       Plugins.Mysql.Sessions.MySQL2.Uri=tcp://192.0.2.0:3306
       Plugins.Mysql.Sessions.MySQL2.User=mysql2_user
       Plugins.Mysql.Sessions.MySQL2.Password=different_password

Item keys: mysql.ping[MySQL1], mysql.ping[MySQL2]

Example 2

Providing some of the parameters in the item key (supported since Zabbix 5.0.34).

Configuration parameters:

Plugins.Postgres.Sessions.Session1.Uri=tcp://192.0.2.234:5432
       Plugins.Postgres.Sessions.Session1.User=old_username
       Plugins.Postgres.Sessions.Session1.Password=session_password

Item key: pgsql.ping[session1,new_username,,postgres]

As a result of this configuration, the agent will connect to PostgreSQL using the following parameters:

• URI from session parameter: 192.0.2.234:5432
• Username from the item key: new_username
• Password from session parameter (since it is omitted in the item key): session_password
• Database name from the item key: postgres

Example 3

Collecting a metric using default configuration parameters.

Configuration parameters:

Plugins.Postgres.Default.Uri=tcp://192.0.2.234:5432
       Plugins.Postgres.Default.User=zabbix
       Plugins.Postgres.Default.Password=password

Item key: pgsql.ping[,,,postgres]

As a result of this configuration, the agent will connect to PostgreSQL using the parameters:

• Default URI: 192.0.2.234:5432
• Default username: zabbix
• Default password: password
• Database name from the item key: postgres

连接

一些插件支持同时从多个实例收集度量。可以监视本地和远程实例。支持TCP和Unix套接字连接。

建议配置插件，使实例的连接保持在打开状态。这样做的好处是减少了网络拥塞、延迟以及由于连接数较少而导致的CPU和内存使用。客户端库负责这个。

编写插件

插件是定义结构并实现一个或多个插件接口（Exporter、Collector、Runner、Watcher）的Go包：

• 插件导出器 plugin.Exporter

Exporter是执行轮询并返回值（values）、nothing和error的最简单接口。它接受预先准备好的项键、参数和上下文。Exporter接口是唯一可以同时访问的接口。所有其它插件接口访问都是独占的，当插件已经在执行某些任务时，不能调用任何方法。此外，每个插件最多只能调用100个concurrent Export（），可以根据需要减少每个插件的调用次数。

• 插件收集器 plugin.Collector

收集器用于插件需要定期收集数据时。此接口通常与导出器接口一起用于导出收集的数据。

• 插件配置器 plugin.Configurator

Configurator用于从agent2配置文件向插件提供配置参数。

• 插件运行器 plugin.Runner

Runner接口提供了在插件启动（激活）时执行一些初始化，在插件停止（停用）时执行取消初始化的方法。例如，插件可以通过实现Runner接口来启动/停止一些后台goroutine。

• 插件.观察者 plugin.Watcher

Watcher允许插件实现自己的度量轮询，而不使用agent的内部调度程序，例如在基于陷阱的插件中。

默认情况下，插件处于非活动状态，只有在监视插件提供的度量时才会激活。

插件位于插件目录树中，按含义分组，例如plugins/system/uptime/uptime.go.

实施步骤

插件必须导入zabbix.com/pkg/plugin包。

import "zabbix.com/pkg/plugin"

插件必须定义结构并嵌入plugin.Base结构。

type Plugin struct {
           plugin.Base
       }
       var impl Plugin

一个插件必须实现一个或多个插件接口。

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)
       }

插件必须在初始化期间注册自身。

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

其中RegisterMetrics 参数为：

• 指向插件实现的指针
• 插件名称（大写）
• 指标#1名称（项目键）
• 指标#1描述（以大写字符开始，以点结束）
• 指标#2名称（项目键）（可选）
• 指标#2描述（以大写字符开始，以点结束）（可选）
• ...

如果需要日志记录，插件必须使用 plugin.Base 提供的日志记录功能（见上面的例子）。它基本上是一个标准日志的包装器，但是它会在日志信息前面加上[<plugin name>]。