Documentation
Table of Contents
6 ローダブルモジュール
1 概要
ローダブルモジュールは、Zabbixの機能を拡張するためのパフォーマンス重視のオプションです。
Zabbixの機能を拡張する方法として、すでに以下のようなものがあります。
- user parameters (agent メトリクス)
- external checks(agent レス監視)
system.run[]Zabbix agent item.
これらは非常にうまく動作しますが、1つ大きな欠点があります。それはfork()です。
Zabbixはユーザメトリクスを処理するたびに新しいプロセスを fork する必要があり、これはパフォーマンスにとって良いことではありません。通常は大きな問題ではありませんが、組み込みシステムの監視、多数の監視パラメータ複雑なロジックや長い起動時間を持つ重いスクリプトを持つ場合、深刻な問題となる可能性があります。
ローダブルモジュールのサポートは、パフォーマンスを犠牲にすることなく、Zabbixエージェント、server 、proxy を拡張する方法を提供します。
ローダブルモジュールとは、基本的にZabbixデーモンが使用する共有ライブラリで、起動時にロードされます。ライブラリには特定の関数が含まれている必要があり、Zabbixプロセスはファイルが本当にロードして動作するモジュールであることを検出することができます。
ロード可能なモジュールには多くの利点があります。優れたパフォーマンスや任意のロジックを実装できることも非常に重要ですが、おそらく最も重要な利点は、Zabbixモジュールを開発、利用、共有できることです。これはトラブルのないメンテナンスに貢献し、Zabbixのコアコードベースから独立して、より簡単に新しい機能を提供するのに役立ちます。
モジュールのライセンスとバイナリ形式での配布はGPLライセンスに準拠します（モジュールはランタイムにZabbixとリンクし、Zabbixヘッダーを使用しています。）バイナリ互換性はZabbixによって保証されていません。
モジュールAPIの安定性はZabbix LTS(Long Term Support) releaseの1サイクルにおいて保証されます。
Zabbix APIの安定性は保証されていません(技術的にはモジュールからZabbix内部関数を呼び出すことは可能ですが、そのようなモジュールが動作する保証はありません)。
2 モジュールAPI
共有ライブラリをZabbixモジュールとして扱うには、いくつかの関数を実装し、エクスポートする必要があります。現在、ZabbixモジュールAPIには6つの関数があり、そのうち1つだけが必須で、他の5つはオプションです。
2.1 必須インターフェース
必須の関数は zbx_module_api_version() だけです。
この関数は、このモジュールが実装しているAPIバージョンを返し、モジュールをロードするためには、このバージョンがZabbixがサポートするモジュールAPIバージョンと一致する必要があります。Zabbix がサポートするモジュール API のバージョンは、ZBX_MODULE_API_VERSION. です。したがって、この関数はこの定数を返す必要があります。この目的で使用されていた古い定数ZBX_MODULE_API_VERSION_ONEは、ソースの互換性を保つためにZBX_MODULE_API_VERSIONと同じに定義されていますが、この使用は推奨されません。
2.2 オプションのインターフェース
オプションのインターフェースは、 以下の通りです。 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 は起動しません。
この関数は、モジュールがサポートする item のリストを返す必要があります。 各項目は ZBX_METRIC 構造体で定義されます。リストの最後には、"key "フィールドがNULLのZBX_METRIC構造体を返します。
モジュールが zbx_module_item_list() をエクスポートしている場合、この関数はZabbixによって使用されます。モジュールが実装する item チェックが従うべきタイムアウト設定をZabbix設定ファイルで指定するために使用されます。ここで、"timeout "パラメータは秒単位です。
この関数は、Zabbix サーバが異なるデータ型の history をエクスポートする際に使用するコールバック関数を返します。コールバック関数はZBX_HISTORY_WRITE_CBS構造体のフィールドとして提供され、モジュールが特定のタイプの history に興味がない場合、フィールドはNULLにすることが可能です。
この関数は、割り当てられたリソースの解放、ファイルディスクリプタのクローズなど、必要な初期化を行います。
すべての関数は、Zabbix起動時にモジュールがロードされると一度だけ呼び出されます。 zbx_module_uninit() は Zabbix のシャットダウン時にモジュールがアンロードされると一度だけ呼び出されます。
2.3 item の定義
各 item は、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 }
}アイテムを実装する各関数は、2 つのポインタ パラメータを受け入れる必要があります。最初のパラメータは AGENT_REQUEST 型、2 番目のパラメータは AGENT_RESULT 型です。
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 に情報を設定する方法の詳細については、以下の「ダミー」モジュールの例を参照してください。
2.4 history のエクスポートコールバックを提供する
Zabbix 4.0.0 以降、モジュール経由のヒストリのエクスポートは Zabbix プロキシではサポートされなくなりました。
モジュールは、数値(浮動小数)、数値(整数)、文字、テキスト、ログなどのデータ型毎に監視データをエクスポートする関数を指定できます。
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のデータベースに保存され、valueキャッシュに展開された後、history syncerプロセスによってコールバックが使用されます。
ヒストリのエクスポートモジュールで内部エラーが発生した場合、回復するまで監視全体をブロックするのではなく、代わりにデータを破棄してZabbixサーバの実行を継続させるようにモジュールを記述することを推奨します。
2.5 モジュールのビルド
現在、モジュールはZabbixのソースツリー内でビルドされることになっています。なぜなら、モジュールAPIはZabbixヘッダで定義されているいくつかのデータ構造に依存しているからです。
ロード可能なモジュールにとって最も重要なヘッダーは、これらのデータ構造を定義しているinclude/module.hです。include/module.hが正しく動作するために必要な他のシステムヘッダは、stdlib.hとstdint.hです。
この情報を頭に入れれば、モジュールをビルドするための準備はすべて整ったことになります。モジュールは、stdlib.h、stdint.h、module.h が含まれている必要があり、ビルドスクリプトは、これらのファイルがインクルードパスにあることを確認する必要があります。詳細については、以下の "ダミー" モジュールの例を参照してください。
このヘッダには、ロギングとデバッグに使用できる zabbix_log() 関数が定義されています。
3 設定パラメータ
Zabbix agent、server、proxyは、モジュールを処理するために2つのparametersをサポートしています。
- 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 モジュールをロードし、
/usr/local/lib/zabbix からは dummy.so をロードします。モジュールが見つからない場合、不正なパーミッションの場合、共有ライブラリがZabbixモジュールでない場合、失敗します。
4 フロントエンドの設定
ローダブルモジュールはZabbix agent、server、proxyでサポートされているため、Zabbixフロントエンドの アイテムのタイプはモジュールがロードされる場所に依存します。モジュールが agent にロードされている場合、アイテムのタイプは"Zabbixエージェント" または "Zabbixエージェント(アクティブ)" になります。モジュールが server または proxy にロードされている場合、アイテムのタイプは "シンプルチェック" になります。
Zabbixモジュールによるヒストリのエクスポートには、フロントエンドの設定は必要ありません。 モジュールが server に正常にロードされ、少なくとも1つの非NULLコールバック関数を返す zbx_module_history_write_cbs() 関数を提供する場合、ヒストリのエクスポートが自動的に有効化されます。
5 ダミーモジュール
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]- 1番目のパラメータをそのまま返します。 例えばdummy.echo[ABC]は ABC を返します。dummy.random[param1, param2]- 1番目の引数と2番目の引数の間の任意の整数を返します。例えばdummy.random[1,1000000]
6 制限事項
ローダブルモジュールのサポートは、Unix プラットフォームにのみ実装されています。つまり、Windows agent では動作しません。
場合によっては、モジュールに関連する設定パラメータをzabbix_agentd.confから読み込む必要があります。現在、これはサポートされていません。モジュールで設定パラメータを使用する必要がある場合は、モジュール固有の設定ファイルのパース を実装する必要があります。