14 Плагины

Плагины дают возможность расширить функционал Zabbix. Они написаны на языке Go и поддерживаются только для Zabbix агента 2. Они предоставляют альтернативу загружаемые модули (пишутся на C) и другим методам расширения функциональности Zabbix, таким как пользовательские параметры (метрики агента), внешие проверки (мониторинг без агента) и элементу данных Zabbix агента system.run []. Следующие функции относятся к агенту 2 и его плагинам:

• один файл конфигурации (все параметры конфигурации плагина находятся в одном файле с параметрами самого агента);
• управление очередью задач c учетом расписания и возможностей параллельного запуска задач;
• тайм-ауты на уровне плагинов.

Готовые плагины

Все метрики, поддерживаемые для Zabbix агента 2, собираются с помощью плагинов. Zabbix предоставляет ряд готовых плагинов для Zabbix агента 2:

Настройка плагинов

Общие принципы настройки и рекомендации описаны в этом разделе.

Для конкретных примеров конфигурации плагина смотрите также:

• Memcached
• MySQL
• Redis

Все настройки плагинов задаются с использованием параметра Plugins.* файла конфигурации Zabbix агента 2 . В отличие от других параметров агента, это не тип ключа / значения параметра. Это отдельный раздел, где могут быть описаны конкретные параметры плагина. Каждый параметр должен иметь следующую структуру:

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

Написание плагинов

Плагин - Go пакет, который определяет структуру и реализует один или несколько интерфейсов плагина (Exporter, Collector, Configurator, Runner, Watcher):

• plugin.Exporter

Exporter - простейший интерфейс, который выполняет опрос и возвращает значение (значения), ничего, ошибку. Он принимает предварительно обработанные ключ элемента данных, параметры и контекст. Интерфейс Exporter является единственным интерфейсом, к которому можно получить доступ на конкурентной основе. Доступ ко всем остальным интерфейсам плагина эксклюзивный и нельзя вызвать никакой метод, когда плагин уже выполняет какую-нибудь задачу. Также имеется ограничение в 100 максимальных параллельных вызовов Export() на каждый плагин, это значение можно уменьшить, по мере необходимости, каждому плагину отдельно.

• plugin.Collector

Collector используется, когда плагину требуется сбор данных на основе регулярных интервалов. Этот интерфейс обычно используется совместно с Exporter интерфейсом для экспорта собранных данных.

• plugin.Configurator

Конфигуратор используется для предоставления плагину его параметров из файла конфигурации агента 2 .

• plugin.Runner

Интерфейс Runner предоставляет средства для выполнения некоторой инициализации, когда плагин запущен (активирован), и деинициализации, когда плагин остановлен (деактивирован). Например, плагин может запускать/останавливать некоторые фоновые процедуры, реализуя интерфейс Runner.

• plugin.Watcher

Watcher позволяет плагину самостоятельно запрашивать метрики, без использования внутреннего планировщика агента, например в плагинах, использующих трапы.

Плагины по умолчанию неактивны и активируются только при мониторинге метрик, предоставляемых плагином.

Плагины расположены в дереве каталогов плагинов, сгруппированные по значению, например 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 следующие:

• Указатель на реализацию плагина
• Имя плагина (в формате UpperCamelCase - без пробелов, каждое слово с заглавной буквы)
• Имя метрики #1 (ключ элемента данных)
• Описание метрики #1 (начиная с заглавной буквы и заканчивая точкой)
• Имя метрики #2 (ключ элемента данных) (не обязательно)
• Описание метрики #2 (начиная с заглавной буквы и заканчивая точкой) (не обязательно)
• ...

Если необходимо делать записи в журнал, плагин должен использовать функциональность журнаирования, предоставляемую plugin.Base (см. Пример выше). По сути, это оболочка для стандартного ведения журнала, но к сообщениям журнала добавляется префикс [<имя плагина>].