Table of Contents
1 ローダブルモジュール
概要
ロード可能なモジュールは、Zabbixの機能を拡張するためのパフォーマンス重視のオプションを提供します。
Zabbixの機能は、ユーザーパラメータ、外部チェック、system.run Zabbixエージェントアイテムなど、さまざまな方法で拡張できます。これらは非常によく機能しますが、主な欠点はfork()です。Zabbixはユーザーメトリックを処理するたびに新しいプロセスをforkする必要があり、これはパフォーマンスにとって良くありません。通常は大きな問題ではありませんが、組み込みシステムの監視や、多数の監視パラメータ、複雑なロジックや起動時間の長い重いスクリプトを使用する場合には深刻な問題となる可能性があります。
ロード可能なモジュールのサポートにより、パフォーマンスを犠牲にすることなく、Zabbixエージェント、サーバー、プロキシの拡張が可能になります。
ロード可能なモジュールは基本的にZabbixデーモンによって使用され、起動時にロードされる共有ライブラリです。このライブラリには特定の関数が含まれている必要があり、Zabbixプロセスがそのファイルが実際にロードして動作できるモジュールであることを検出できるようになっています。
ロード可能なモジュールには多くの利点があります。優れたパフォーマンスや任意のロジックを実装できる能力も非常に重要ですが、おそらく最も重要な利点は、Zabbixモジュールを開発、利用、共有できることです。これにより、トラブルのないメンテナンスが可能となり、Zabbixのコアコードベースとは独立して新しい機能をより簡単に提供できるようになります。
モジュールのライセンスおよびバイナリ形式での配布はAGPL-3.0ライセンスによって規定されています（モジュールは実行時にZabbixとリンクし、Zabbixヘッダーを使用します。Zabbixの全コードはZabbix 7.0以降AGPL-3.0ライセンスで提供されています）。バイナリ互換性はZabbixによって保証されません。
モジュールAPIの安定性は、1つのZabbix LTS（長期サポート）リリースサイクルの間保証されます。Zabbix APIの安定性は保証されません（技術的にはモジュールからZabbixの内部関数を呼び出すことは可能ですが、そのようなモジュールが動作する保証はありません）。
モジュールAPI
共有ライブラリをZabbixモジュールとして扱うためには、いくつかの関数を実装してエクスポートする必要があります。現在、ZabbixモジュールAPIには6つの関数があり、そのうち1つだけが必須で、他の5つはオプションです。
必須インターフェース
唯一必須の関数は zbx_module_api_version() です:
この関数は、このモジュールで実装されているAPIバージョンを返す必要があり、モジュールがロードされるためには、このバージョンがZabbixでサポートされているモジュールAPIバージョンと一致している必要があります。ZabbixでサポートされているモジュールAPIのバージョンはZBX_MODULE_API_VERSIONです。したがって、この関数はこの定数を返す必要があります。この目的で使用されていた古い定数ZBX_MODULE_API_VERSION_ONEは、ソース互換性を維持するためにZBX_MODULE_API_VERSIONと等しく定義されていますが、使用は推奨されません。
オプションインターフェース
オプションの関数は zbx_module_init()、zbx_module_item_list()、zbx_module_item_timeout()、zbx_module_history_write_cbs()、zbx_module_uninit() です:
この関数は、モジュールに必要な初期化処理(必要な場合)を実行する必要があります。成功した場合はZBX_MODULE_OKを返す必要があります。失敗した場合はZBX_MODULE_FAILを返す必要があります。後者の場合、Zabbixは起動しません。
この関数は、モジュールがサポートするアイテムのリストを返す必要があります。各アイテムはZBX_METRIC構造体で定義されます。詳細は下記のセクションを参照してください。リストは、"key"フィールドがNULLのZBX_METRIC構造体で終了します。
モジュールが zbx_module_item_list() をエクスポートしている場合、この関数はZabbixによって、モジュールが実装するアイテムチェックが従うべきZabbix設定ファイルのタイムアウト設定を指定するために使用されます。ここで、"timeout"パラメータは秒単位です。
この関数は、Zabbixサーバーがさまざまなデータ型の履歴をエクスポートするために使用するコールバック関数を返す必要があります。コールバック関数はZBX_HISTORY_WRITE_CBS構造体のフィールドとして提供され、モジュールが特定の型の履歴に関心がない場合はフィールドをNULLにできます。
この関数は、割り当てられたリソースの解放やファイルディスクリプタのクローズなど、必要な後処理(必要な場合)を実行する必要があります。
すべての関数は、モジュールがロードされたときにZabbixの起動時に1回呼び出されます。ただし、zbx_module_uninit()のみは、モジュールがアンロードされたときにZabbixのシャットダウン時に1回呼び出されます。
アイテムの定義
各アイテムはZBX_METRIC構造体で定義されます:
ここで、keyはアイテムキー（例："dummy.random"）、flagsはCF_HAVEPARAMSまたは0（アイテムがパラメータを受け入れるかどうかによる）、functionはアイテムを実装するC関数（例："zbx_module_dummy_random"）、test_paramはZabbixエージェントが"-p"フラグで起動されたときに使用するパラメータリスト（例："1,1000"、NULLも可）です。定義例は次のようになります:
static ZBX_METRIC keys[] =
{
{ "dummy.random", CF_HAVEPARAMS, zbx_module_dummy_random, "1,1000" },
{ NULL }
}アイテムを実装する各関数は、最初のパラメータがAGENT_REQUEST型、2番目のパラメータがAGENT_RESULT型の2つのポインタパラメータを受け取る必要があります:
int zbx_module_dummy_random(AGENT_REQUEST *request, AGENT_RESULT *result)
{
...
SET_UI64_RESULT(result, from + rand() % (to - from + 1));
return SYSINFO_RET_OK;
}これらの関数は、アイテム値が正常に取得できた場合はSYSINFO_RET_OKを返す必要があります。そうでない場合はSYSINFO_RET_FAILを返す必要があります。AGENT_REQUESTから情報を取得する方法やAGENT_RESULTに情報を設定する方法の詳細については、以下の"dummy"モジュールの例を参照してください。
履歴エクスポートコールバックの提供
モジュールによる履歴エクスポートは、Zabbixプロキシでは サポートされなくなりました。
モジュールは、型ごとに履歴データをエクスポートする関数を指定できます: 数値 (float)、数値(unsigned)、文字列、テキスト、ログ:
typedef struct
{
void (*history_float_cb)(const ZBX_HISTORY_FLOAT *history, int history_num);
void (*history_integer_cb)(const ZBX_HISTORY_INTEGER *history, int history_num);
void (*history_string_cb)(const ZBX_HISTORY_STRING *history, int history_num);
void (*history_text_cb)(const ZBX_HISTORY_TEXT *history, int history_num);
void (*history_log_cb)(const ZBX_HISTORY_LOG *history, int history_num);
}
ZBX_HISTORY_WRITE_CBS;それぞれの関数は、"history_num"個の要素からなる"history"配列を 引数として受け取る必要があります。エクスポートする履歴データの型に応じて、 "history"はそれぞれ以下の構造体の配列となります:
typedef struct
{
zbx_uint64_t itemid;
int clock;
int ns;
double value;
}
ZBX_HISTORY_FLOAT;
typedef struct
{
zbx_uint64_t itemid;
int clock;
int ns;
zbx_uint64_t value;
}
ZBX_HISTORY_INTEGER;
typedef struct
{
zbx_uint64_t itemid;
int clock;
int ns;
const char *value;
}
ZBX_HISTORY_STRING;
typedef struct
{
zbx_uint64_t itemid;
int clock;
int ns;
const char *value;
}
ZBX_HISTORY_TEXT;
typedef struct
{
zbx_uint64_t itemid;
int clock;
int ns;
const char *value;
const char *source;
int timestamp;
int logeventid;
int severity;
}
ZBX_HISTORY_LOG;コールバックは、Zabbixサーバーの履歴同期プロセスによって、 履歴同期処理の最後に、データがZabbixデータベースに書き込まれ、 値キャッシュに保存された後に使用されます。
履歴エクスポートモジュールで内部エラーが発生した場合、モジュールは 全体の監視をブロックせず、データを破棄してZabbixサーバーの 動作を継続できるように記述することを推奨します。
モジュールのビルド
モジュールは現在、Zabbixのソースツリー内でビルドすることを想定しています。なぜなら、モジュールAPIがZabbixヘッダで定義されているいくつかのデータ構造に依存しているためです。
ロード可能なモジュールにとって最も重要なヘッダは include/module.h であり、これがこれらのデータ構造を定義しています。include/module.h が正しく動作するために必要な他のシステムヘッダは stdlib.h と stdint.h です。
この情報を踏まえれば、モジュールをビルドする準備は整っています。モジュールは stdlib.h、stdint.h、module.h をインクルードし、ビルドスクリプトはこれらのファイルがインクルードパスにあることを確認する必要があります。詳細については、下記の「ダミー」モジュールの例を参照してください。
もう1つ便利なヘッダは include/zbxcommon.h で、これはログ記録やデバッグ目的で使用できる zabbix_log() 関数を定義しています。
設定パラメータ
Zabbixエージェント、サーバー、プロキシは、モジュールを扱うために2つのパラメータをサポートしています。
- LoadModulePath – ロード可能なモジュールの場所へのフルパス
- LoadModule – 起動時にロードするモジュール。モジュールはLoadModulePathで指定されたディレクトリに配置するか、パスをモジュール名の前に付ける必要があります。前置されたパスが絶対パス（'/'で始まる）である場合、LoadModulePathは無視されます。複数のLoadModuleパラメータを含めることができます。
例えば、Zabbixエージェントを拡張するために、以下のパラメータを追加できます。
LoadModulePath=/usr/local/lib/zabbix/agent/
LoadModule=mariadb.so
LoadModule=apache.so
LoadModule=kernel.so
LoadModule=/usr/local/lib/zabbix/dummy.soエージェントの起動時に、/usr/local/lib/zabbix/agentディレクトリからmariadb.so、apache.so、kernel.soモジュールがロードされ、dummy.soは/usr/local/lib/zabbixからロードされます。モジュールが存在しない場合、不適切なパーミッションの場合、または共有ライブラリがZabbixモジュールでない場合、エージェントは起動に失敗します。
フロントエンドの設定
Zabbixエージェント、サーバー、プロキシはロード可能なモジュールをサポートしています。 したがって、Zabbixフロントエンドでのアイテムタイプは、モジュールがどこにロードされているかによって異なります。 モジュールがエージェントにロードされている場合、アイテムタイプは「Zabbixエージェント」または「Zabbixエージェント（アクティブ）」である必要があります。 モジュールがサーバーまたはプロキシにロードされている場合、アイテムタイプは「シンプルチェック」である必要があります。
Zabbixモジュールによる履歴エクスポートには、フロントエンドの設定は必要ありません。 サーバーがモジュールのロードに成功し、zbx_module_history_write_cbs() 関数が少なくとも1つのNULL以外のコールバック関数を返す場合、履歴エクスポートは自動的に有効になります。
ダミーモジュール
ZabbixにはC言語で書かれたサンプルモジュールが含まれています。モジュールはsrc/modules/dummyにあります。
alex@alex:~trunk/src/modules/dummy$ ls -l
-rw-rw-r-- 1 alex alex 9019 Apr 24 17:54 dummy.c
-rw-rw-r-- 1 alex alex 67 Apr 24 17:54 Makefile
-rw-rw-r-- 1 alex alex 245 Apr 24 17:54 READMEこのモジュールは十分にドキュメント化されており、独自のモジュールのテンプレートとして使用できます。
上記のようにZabbixソースツリーのルートで./configureを実行した後、makeを実行するだけでdummy.soがビルドされます。
/*
** Zabbix
** Copyright (C) 2001-2020 Zabbix SIA
**
** This program is free software; you can redistribute it and/or modify
** it under the terms of the GNU General Public License as published by
** the Free Software Foundation; either version 2 of the License, or
** (at your option) any later version.
**
** This program is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
** GNU General Public License for more details.
**
** You should have received a copy of the GNU General Public License
** along with this program; if not, write to the Free Software
** Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
**/
#include <stdlib.h>
#include <string.h>
#include <time.h>
#include <stdint.h>
#include "module.h"
/* the variable keeps timeout setting for item processing */
static int item_timeout = 0;
/* module SHOULD define internal functions as static and use a naming pattern different from Zabbix internal */
/* symbols (zbx_*) and loadable module API functions (zbx_module_*) to avoid conflicts */
static int dummy_ping(AGENT_REQUEST *request, AGENT_RESULT *result);
static int dummy_echo(AGENT_REQUEST *request, AGENT_RESULT *result);
static int dummy_random(AGENT_REQUEST *request, AGENT_RESULT *result);
static ZBX_METRIC keys[] =
/* KEY FLAG FUNCTION TEST PARAMETERS */
{
{"dummy.ping", 0, dummy_ping, NULL},
{"dummy.echo", CF_HAVEPARAMS, dummy_echo, "a message"},
{"dummy.random", CF_HAVEPARAMS, dummy_random, "1,1000"},
{NULL}
};
/******************************************************************************
* *
* Function: zbx_module_api_version *
* *
* Purpose: returns version number of the module interface *
* *
* Return value: ZBX_MODULE_API_VERSION - version of module.h module is *
* compiled with, in order to load module successfully Zabbix *
* MUST be compiled with the same version of this header file *
* *
******************************************************************************/
int zbx_module_api_version(void)
{
return ZBX_MODULE_API_VERSION;
}
/******************************************************************************
* *
* Function: zbx_module_item_timeout *
* *
* Purpose: set timeout value for processing of items *
* *
* Parameters: timeout - timeout in seconds, 0 - no timeout set *
* *
******************************************************************************/
void zbx_module_item_timeout(int timeout)
{
item_timeout = timeout;
}
/******************************************************************************
* *
* Function: zbx_module_item_list *
* *
* Purpose: returns list of item keys supported by the module *
* *
* Return value: list of item keys *
* *
******************************************************************************/
ZBX_METRIC *zbx_module_item_list(void)
{
return keys;
}
static int dummy_ping(AGENT_REQUEST *request, AGENT_RESULT *result)
{
SET_UI64_RESULT(result, 1);
return SYSINFO_RET_OK;
}
static int dummy_echo(AGENT_REQUEST *request, AGENT_RESULT *result)
{
char *param;
if (1 != request->nparam)
{
/* set optional error message */
SET_MSG_RESULT(result, strdup("Invalid number of parameters."));
return SYSINFO_RET_FAIL;
}
param = get_rparam(request, 0);
SET_STR_RESULT(result, strdup(param));
return SYSINFO_RET_OK;
}
/******************************************************************************
* *
* Function: dummy_random *
* *
* Purpose: a main entry point for processing of an item *
* *
* Parameters: request - structure that contains item key and parameters *
* request->key - item key without parameters *
* request->nparam - number of parameters *
* request->params[N-1] - pointers to item key parameters *
* request->types[N-1] - item key parameters types: *
* REQUEST_PARAMETER_TYPE_UNDEFINED (key parameter is empty) *
* REQUEST_PARAMETER_TYPE_ARRAY (array) *
* REQUEST_PARAMETER_TYPE_STRING (quoted or unquoted string) *
* *
* result - structure that will contain result *
* *
* Return value: SYSINFO_RET_FAIL - function failed, item will be marked *
* as not supported by zabbix *
* SYSINFO_RET_OK - success *
* *
* Comment: get_rparam(request, N-1) can be used to get a pointer to the Nth *
* parameter starting from 0 (first parameter). Make sure it exists *
* by checking value of request->nparam. *
* In the same manner get_rparam_type(request, N-1) can be used to *
* get a parameter type. *
* *
******************************************************************************/
static int dummy_random(AGENT_REQUEST *request, AGENT_RESULT *result)
{
char *param1, *param2;
int from, to;
if (2 != request->nparam)
{
/* set optional error message */
SET_MSG_RESULT(result, strdup("Invalid number of parameters."));
return SYSINFO_RET_FAIL;
}
param1 = get_rparam(request, 0);
param2 = get_rparam(request, 1);
/* there is no strict validation of parameters and types for simplicity sake */
from = atoi(param1);
to = atoi(param2);
if (from > to)
{
SET_MSG_RESULT(result, strdup("Invalid range specified."));
return SYSINFO_RET_FAIL;
}
SET_UI64_RESULT(result, from + rand() % (to - from + 1));
return SYSINFO_RET_OK;
}
/******************************************************************************
* *
* Function: zbx_module_init *
* *
* Purpose: the function is called on agent startup *
* It should be used to call any initialization routines *
* *
* Return value: ZBX_MODULE_OK - success *
* ZBX_MODULE_FAIL - module initialization failed *
* *
* Comment: the module won't be loaded in case of ZBX_MODULE_FAIL *
* *
******************************************************************************/
int zbx_module_init(void)
{
/* initialization for dummy.random */
srand(time(NULL));
return ZBX_MODULE_OK;
}
/******************************************************************************
* *
* Function: zbx_module_uninit *
* *
* Purpose: the function is called on agent shutdown *
* It should be used to cleanup used resources if there are any *
* *
* Return value: ZBX_MODULE_OK - success *
* ZBX_MODULE_FAIL - function failed *
* *
******************************************************************************/
int zbx_module_uninit(void)
{
return ZBX_MODULE_OK;
}
/******************************************************************************
* *
* Functions: dummy_history_float_cb *
* dummy_history_integer_cb *
* dummy_history_string_cb *
* dummy_history_text_cb *
* dummy_history_log_cb *
* *
* Purpose: callback functions for storing historical data of types float, *
* integer, string, text and log respectively in external storage *
* *
* Parameters: history - array of historical data *
* history_num - number of elements in history array *
* *
******************************************************************************/
static void dummy_history_float_cb(const ZBX_HISTORY_FLOAT *history, int history_num)
{
int i;
for (i = 0; i < history_num; i++)
{
/* do something with history[i].itemid, history[i].clock, history[i].ns, history[i].value, ... */
}
}
static void dummy_history_integer_cb(const ZBX_HISTORY_INTEGER *history, int history_num)
{
int i;
for (i = 0; i < history_num; i++)
{
/* do something with history[i].itemid, history[i].clock, history[i].ns, history[i].value, ... */
}
}
static void dummy_history_string_cb(const ZBX_HISTORY_STRING *history, int history_num)
{
int i;
for (i = 0; i < history_num; i++)
{
/* do something with history[i].itemid, history[i].clock, history[i].ns, history[i].value, ... */
}
}
static void dummy_history_text_cb(const ZBX_HISTORY_TEXT *history, int history_num)
{
int i;
for (i = 0; i < history_num; i++)
{
/* do something with history[i].itemid, history[i].clock, history[i].ns, history[i].value, ... */
}
}
static void dummy_history_log_cb(const ZBX_HISTORY_LOG *history, int history_num)
{
int i;
for (i = 0; i < history_num; i++)
{
/* do something with history[i].itemid, history[i].clock, history[i].ns, history[i].value, ... */
}
}
/******************************************************************************
* *
* Function: zbx_module_history_write_cbs *
* *
* Purpose: returns a set of module functions Zabbix will call to export *
* different types of historical data *
* *
* Return value: structure with callback function pointers (can be NULL if *
* module is not interested in data of certain types) *
* *
******************************************************************************/
ZBX_HISTORY_WRITE_CBS zbx_module_history_write_cbs(void)
{
static ZBX_HISTORY_WRITE_CBS dummy_callbacks =
{
dummy_history_float_cb,
dummy_history_integer_cb,
dummy_history_string_cb,
dummy_history_text_cb,
dummy_history_log_cb,
};
return dummy_callbacks;
}このモジュールは3つの新しいアイテムをエクスポートします。
dummy.ping- 常に'1'を返しますdummy.echo[param1]- 最初のパラメータをそのまま返します。例えば、dummy.echo[ABC]はABCを返しますdummy.random[param1, param2]- param1-param2の範囲内のランダムな数値を返します。例えば、dummy.random[1,1000000]
制限事項
ロード可能なモジュールのサポートはUnixプラットフォームのみで実装されています。 つまり、Windowsエージェントでは動作しません。
場合によっては、モジュールがzabbix_agentd.confからモジュール関連の設定パラメータを読み取る必要があるかもしれません。 これは現在サポートされていません。モジュールでいくつかの設定パラメータを使用する必要がある場合は、モジュール固有の設定ファイルの解析を実装する必要があるでしょう。