Documentation
Table of Contents
1 Loadable modules
Overzicht
Laadmodule bieden een prestatiegerichte optie om Zabbix-functionaliteit uit te breiden.
U kunt de functionaliteit van Zabbix op verschillende manieren uitbreiden, bijvoorbeeld met gebruikersparameters, externe controles en system.run[] Zabbix agentitems. Deze werken zeer goed, maar hebben één groot nadeel, namelijk fork(). Zabbix moet telkens wanneer het een gebruikersmeting verwerkt een nieuw proces fork(), wat niet goed is voor de prestaties. Dit is normaal gesproken geen groot probleem, maar het kan een ernstige kwestie zijn bij het monitoren van ingebedde systemen, bij een groot aantal gemonitorde parameters of bij zware scripts met complexe logica of een lange opstarttijd.
De ondersteuning van laadmodules biedt manieren om Zabbix-agent, server en proxy uit te breiden zonder de prestaties op te offeren.
Een laadmodule is in feite een gedeelde bibliotheek die wordt gebruikt door de Zabbix-daemon en bij het opstarten wordt geladen. De bibliotheek moet bepaalde functies bevatten, zodat een Zabbix-proces kan detecteren dat het bestand inderdaad een module is die het kan laden en waarmee het kan werken.
Laadmodules hebben een aantal voordelen. Geweldige prestaties en de mogelijkheid om elke logica te implementeren zijn erg belangrijk, maar misschien wel het belangrijkste voordeel is de mogelijkheid om Zabbix-modules te ontwikkelen, te gebruiken en te delen. Dit draagt bij aan probleemloos onderhoud en helpt om nieuwe functionaliteit gemakkelijker te leveren, onafhankelijk van de Zabbix-kerncode.
De licentie en distributie van modules in binaire vorm vallen onder de GPL-licentie (modules worden tijdens runtime met Zabbix gekoppeld en maken gebruik van Zabbix-headers; momenteel valt de hele Zabbix-code onder de GPL-licentie). Binaire compatibiliteit wordt niet gegarandeerd door Zabbix.
De stabiliteit van de module-API wordt gegarandeerd tijdens één Zabbix LTS (Long Term Support) release-cyclus. De stabiliteit van de Zabbix API wordt niet gegarandeerd (technisch gezien is het mogelijk om Zabbix-interne functies vanuit een module aan te roepen, maar er is geen garantie dat dergelijke modules zullen werken).
Module-API
Om ervoor te zorgen dat een gedeelde bibliotheek als een Zabbix-module wordt behandeld, moet deze verschillende functies implementeren en exporteren. Momenteel zijn er zes functies in de Zabbix-module-API, waarvan er slechts één verplicht is en de andere vijf optioneel zijn.
Verplichte interface
De enige verplichte functie is zbx_module_api_version():
Deze functie moet de API-versie retourneren die door deze module wordt geïmplementeerd. Om de module te laden, moet deze versie overeenkomen met de module-API-versie die door Zabbix wordt ondersteund. De versie van de module-API die door Zabbix wordt ondersteund, is ZBX_MODULE_API_VERSION. Daarom moet deze functie deze constante retourneren. De oude constante ZBX_MODULE_API_VERSION_ONE die voor dit doel werd gebruikt, is nu gedefinieerd als gelijk aan ZBX_MODULE_API_VERSION om broncompatibiliteit te behouden, maar het gebruik ervan wordt niet aanbevolen.
Optionele interface
De optionele functies zijn zbx_module_init(), zbx_module_item_list(), zbx_module_item_timeout(), zbx_module_history_write_cbs() en zbx_module_uninit():
Deze functie moet de nodige initialisatie voor de module uitvoeren (indien nodig). Als dit succesvol is, moet het ZBX_MODULE_OK retourneren. Anders moet het ZBX_MODULE_FAIL retourneren. In het laatste geval zal Zabbix niet starten.
Deze functie moet een lijst retourneren van items die door de module worden ondersteund. Elk item is gedefinieerd in een ZBX_METRIC-structuur, zie de onderstaande sectie voor details. De lijst wordt beëindigd door een ZBX_METRIC-structuur met een "key"-veld van NULL.
Als de module zbx_module_item_list() exporteert, wordt deze functie door Zabbix gebruikt om de time-outinstellingen in het Zabbix-configuratiebestand te specificeren waaraan de itemcontroles die door de module zijn geïmplementeerd, moeten voldoen. Hierbij is de parameter "timeout" in seconden.
Deze functie moet terugroeproutines retourneren die door de Zabbix-server worden gebruikt om de geschiedenis van verschillende gegevenstypen te exporteren. Terugroeproutines worden geleverd als velden van de ZBX_HISTORY_WRITE_CBS-structuur, velden kunnen NULL zijn als de module niet geïnteresseerd is in de geschiedenis van bepaald type.
Deze functie moet de nodige oninitialisatie uitvoeren (indien nodig), zoals het vrijgeven van toegewezen bronnen, het sluiten van bestandsdescriptoren, enzovoort.
Alle functies worden één keer opgeroepen bij het opstarten van Zabbix wanneer de module wordt geladen, met uitzondering van zbx_module_uninit(), die één keer wordt opgeroepen bij het afsluiten van Zabbix wanneer de module wordt gelost.
Definiëren van items
Elk item wordt gedefinieerd in een ZBX_METRIC-structuur:
Hierbij is key de item sleutel (bijv. "dummy.random"), flags is ofwel CF_HAVEPARAMS of 0 (afhankelijk of het item parameters accepteert of niet), function is een C-functie die het item implementeert (bijv. "zbx_module_dummy_random"), en test_param is de parameterlijst die moet worden gebruikt wanneer de Zabbix-agent wordt gestart met de "-p" vlag (bijv. "1,1000", kan NULL zijn). Een voorbeelddefinitie kan er als volgt uitzien:
static ZBX_METRIC keys[] =
{
{ "dummy.random", CF_HAVEPARAMS, zbx_module_dummy_random, "1,1000" },
{ NULL }
}Elke functie die een item implementeert, moet twee pointerparameters accepteren, de eerste van het type AGENT_REQUEST en de tweede van het type 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;
}Deze functies moeten SYSINFO_RET_OK retourneren als de itemwaarde succesvol is verkregen. Anders moeten ze SYSINFO_RET_FAIL retourneren. Zie het onderstaande voorbeeld van de "dummy"-module voor details over het verkrijgen van informatie uit AGENT_REQUEST en het instellen van informatie in AGENT_RESULT.
Leveren van terugroeproutines voor geschiedenisexport
Sinds Zabbix 4.0.0 wordt geschiedenisexport via module niet langer ondersteund door de Zabbix-proxy.
Een module kan functies opgeven om geschiedenisgegevens per type te exporteren: Numeriek (float), Numeriek (ongesigneerd), Tekst en Log:
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;Elk van deze functies moet een "history"-array van "history_num" elementen als argumenten aannemen. Afhankelijk van het gegevenstype van de geschiedenis dat moet worden geëxporteerd, is "history" respectievelijk een array van de volgende structuren:
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;Deze terugroeproutines worden gebruikt door Zabbix-servergeschiedenissyncer-processen aan het einde van de geschiedenissync-procedure, nadat de gegevens in de Zabbix-database zijn geschreven en opgeslagen in de waardecache.
In geval van interne fout in de geschiedenisexportmodule wordt aanbevolen de module zodanig te schrijven dat deze de hele monitoring niet blokkeert totdat deze herstelt, maar in plaats daarvan gegevens negeert en Zabbix-server toestaat om door te blijven draaien.
Modules bouwen
Modules zijn momenteel bedoeld om te worden gebouwd binnen de Zabbix-bronboom, omdat de module-API afhankelijk is van bepaalde gegevensstructuren die zijn gedefinieerd in Zabbix-headers.
De belangrijkste header voor laadmodules is include/module.h, die deze gegevensstructuren definieert. Andere noodzakelijke systeemheaders die include/module.h helpen om correct te werken, zijn stdlib.h en stdint.h.
Met deze informatie in gedachten is alles gereed om de module te bouwen. De module moet stdlib.h, stdint.h en module.h bevatten, en het buildscript moet ervoor zorgen dat deze bestanden zich in het include-pad bevinden. Zie het onderstaande voorbeeld van de "dummy"-module voor details.
Een andere handige header is include/log.h, die de functie zabbix_log() definieert, die kan worden gebruikt voor loggen en debuggen.
Configuratieparameters
Zabbix-agent, -server en -proxy ondersteunen twee parameters om met modules om te gaan:
- LoadModulePath - het volledige pad naar de locatie van laadmodules
- LoadModule - module(s) om bij het opstarten te laden. De modules moeten zich bevinden in een map die is opgegeven door LoadModulePath of het pad moet voorafgaan aan de modulenaam. Als het voorafgaande pad absoluut is (begint met '/'), wordt LoadModulePath genegeerd. Het is toegestaan om meerdere LoadModule parameters op te nemen.
Bijvoorbeeld, om de Zabbix-agent uit te breiden, kunnen we de volgende parameters toevoegen:
LoadModulePath=/usr/local/lib/zabbix/agent/
LoadModule=mariadb.so
LoadModule=apache.so
LoadModule=kernel.so
LoadModule=/usr/local/lib/zabbix/dummy.soBij het starten van de agent zal deze de modules mariadb.so, apache.so en kernel.so laden vanuit de map /usr/local/lib/zabbix/agent, terwijl dummy.so wordt geladen vanuit /usr/local/lib/zabbix. De agent zal niet kunnen starten als een module ontbreekt, in het geval van onjuiste machtigingen of als een gedeelde bibliotheek geen Zabbix-module is.
Front-endconfiguratie
Laadmodules worden ondersteund door Zabbix-agent, -server en -proxy. Daarom hangt het type item in de Zabbix-frontend af van waar de module is geladen. Als de module in de agent wordt geladen, moet het itemtype "Zabbix-agent" of "Zabbix-agent (actief)" zijn. Als de module in de server of proxy wordt geladen, moet het itemtype "Eenvoudige controle" zijn.
Geschiedenisexport via Zabbix-modules vereist geen front-endconfiguratie. Als de module met succes door de server wordt geladen en de functie zbx_module_history_write_cbs() levert ten minste één niet-NULL-terugroeproutine op, wordt geschiedenisexport automatisch ingeschakeld.
Voorbeeldmodule "Dummy"
Zabbix bevat een voorbeeldmodule die is geschreven in de C-taal. De module bevindt zich onder src/modules/dummy:
alex@alex:~trunk/src/modules/dummy$ ls -l
-rw-rw-r-- 1 alex alex 9019 24 apr 17:54 dummy.c
-rw-rw-r-- 1 alex alex 67 24 apr 17:54 Makefile
-rw-rw-r-- 1 alex alex 245 24 apr 17:54 READMEDe module is goed gedocumenteerd en kan als sjabloon worden gebruikt voor uw eigen modules.
Nadat ./configure is uitgevoerd in de hoofdmap van de Zabbix-bronboom zoals hierboven beschreven, voert u eenvoudigweg make uit om dummy.so te bouwen.
/*
** 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"
/* de variabele bewaart de time-outinstelling voor het verwerken van items */
static int item_timeout = 0;
/* de module MOET interne functies definiëren als statisch en een andere naamgevingsindeling gebruiken dan Zabbix interne symbolen (zbx_*) en laadbare module-API-functies (zbx_module_*) om conflicten te vermijden */
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}
};
/******************************************************************************
* *
* Functie: zbx_module_api_version *
* *
* Doel: geeft het versienummer van de module-interface terug *
* *
* Returnwaarde: ZBX_MODULE_API_VERSION - versie van module.h module is *
* gecompileerd met, om de module met succes te laden, moet *
* Zabbix zijn gecompileerd met dezelfde versie van deze *
* koptekst *
* *
******************************************************************************/
int zbx_module_api_version(void)
{
return ZBX_MODULE_API_VERSION;
}
/******************************************************************************
* *
* Functie: zbx_module_item_timeout *
* *
* Doel: stelt time-outwaarde in voor verwerking van items *
* *
* Parameters: timeout - time-out in seconden, 0 - geen time-out ingesteld *
* *
******************************************************************************/
void zbx_module_item_timeout(int timeout)
{
item_timeout = timeout;
}
/******************************************************************************
* *
* Functie: zbx_module_item_list *
* *
* Doel: geeft een lijst terug van item-sleutels die door de module worden *
* ondersteund *
* *
* Returnwaarde: lijst van item-sleutels *
* *
******************************************************************************/
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)
{
/* optionele foutmelding instellen */
SET_MSG_RESULT(result, strdup("Ongeldig aantal parameters."));
return SYSINFO_RET_FAIL;
}
param = get_rparam(request, 0);
SET_STR_RESULT(result, strdup(param));
return SYSINFO_RET_OK;
}
/******************************************************************************
* *
* Functie: dummy_random *
* *
* Doel: een hoofdentiteitspunt voor verwerking van een item *
* *
* Parameters: aanvraag - structuur die item-sleutel en parameters bevat *
* aanvraag->key - item-sleutel zonder parameters *
* aanvraag->nparam - aantal parameters *
* aanvraag->params[N-1] - pointers naar parameters van item-sleutels *
* aanvraag->types[N-1] - typen parameters van item-sleutels: *
* REQUEST_PARAMETER_TYPE_UNDEFINED (sleutelparameter is leeg) *
* REQUEST_PARAMETER_TYPE_ARRAY (array) *
* REQUEST_PARAMETER_TYPE_STRING (aangehaalde of niet-gekoppelde tekenreeks) *
* *
* resultaat - structuur die het resultaat zal bevatten *
* *
* Returnwaarde: SYSINFO_RET_FAIL - functie mislukt, item wordt gemarkeerd als *
* niet ondersteund door zabbix *
* SYSINFO_RET_OK - succes *
* *
* Opmerking: get_rparam(request, N-1) kan worden gebruikt om een pointer te *
* verkrijgen naar de Nde parameter, te beginnen bij 0 (eerste parameter). Zorg ervoor dat deze bestaat *
* door de waarde van request->nparam te controleren. *
* Op dezelfde manier kan get
_rparam_type(request, N-1) worden gebruikt om een parameterstype te krijgen. *
* *
******************************************************************************/
static int dummy_random(AGENT_REQUEST *request, AGENT_RESULT *result)
{
char *param1, *param2;
int from, to;
if (2 != request->nparam)
{
/* optionele foutmelding instellen */
SET_MSG_RESULT(result, strdup("Ongeldig aantal parameters."));
return SYSINFO_RET_FAIL;
}
param1 = get_rparam(request, 0);
param2 = get_rparam(request, 1);
/* er is geen strikte validatie van parameters en typen voor eenvoud */
from = atoi(param1);
to = atoi(param2);
if (from > to)
{
SET_MSG_RESULT(result, strdup("Ongeldige reeks opgegeven."));
return SYSINFO_RET_FAIL;
}
SET_UI64_RESULT(result, from + rand() % (to - from + 1));
return SYSINFO_RET_OK;
}
/******************************************************************************
* *
* Functie: zbx_module_init *
* *
* Doel: de functie wordt op agentstart opgeroepen *
* Het moet worden gebruikt om eventuele initialisatieroutines aan te roepen *
* *
* Returnwaarde: ZBX_MODULE_OK - succes *
* ZBX_MODULE_FAIL - initialisatie van module is mislukt *
* *
* Opmerking: de module wordt niet geladen in geval van ZBX_MODULE_FAIL *
* *
******************************************************************************/
int zbx_module_init(void)
{
/* initialisatie voor dummy.random */
srand(time(NULL));
return ZBX_MODULE_OK;
}
/******************************************************************************
* *
* Functie: zbx_module_uninit *
* *
* Doel: de functie wordt op agent-afsluiten opgeroepen *
* Het moet worden gebruikt om gebruikte bronnen op te schonen als die er zijn *
* *
* Returnwaarde: ZBX_MODULE_OK - succes *
* ZBX_MODULE_FAIL - functie is mislukt *
* *
******************************************************************************/
int zbx_module_uninit(void)
{
return ZBX_MODULE_OK;
}
/******************************************************************************
* *
* Functies: dummy_history_float_cb *
* dummy_history_integer_cb *
* dummy_history_string_cb *
* dummy_history_text_cb *
* dummy_history_log_cb *
* *
* Doel: terugbelingsfuncties voor het opslaan van historische gegevens van typen float, *
* integer, string, text en log respectievelijk in externe opslag *
* *
* Parameters: geschiedenis - reeks historische gegevens *
* history_num - aantal elementen in de geschiedenisarray *
* *
******************************************************************************/
static void dummy_history_float_cb(const ZBX_HISTORY_FLOAT *history, int history_num)
{
int i;
for (i = 0; i < history_num; i++)
{
/* doe iets met 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++)
{
/* doe iets met 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++)
{
/* doe iets met 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++)
{
/* doe iets met 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++)
{
/* doe iets met history[i].itemid, history[i].clock, history[i].ns, history[i].value, ... */
}
}
/******************************************************************************
* *
* Functie: zbx_module_history_write_cbs *
* *
* Doel: geeft een set modulefuncties terug die Zabbix zal oproepen om verschillende typen *
* historische gegevens te exporteren *
* *
* Returnwaarde: structuur met terugroepfunctie-aanwijzers (kan NULL zijn als *
* module geen gegevens van be
paalde typen interesseert) *
* *
******************************************************************************/
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;
}De module exporteert drie nieuwe items:
dummy.ping- retourneert altijd '1'dummy.echo[param1]- retourneert de eerste parameter zoals deze is, bijvoorbeelddummy.echo[ABC]zal ABC retournerendummy.random[param1, param2]- retourneert een willekeurig getal binnen het bereik van param1-param2, bijvoorbeelddummy.random[1,1000000]
Beperkingen
Ondersteuning van laadbare modules is alleen geïmplementeerd voor het Unix-platform. Dit betekent dat het niet werkt voor Windows-agents.
In sommige gevallen heeft een module mogelijk configuratieparameters nodig die gerelateerd zijn aan de module, afkomstig uit zabbix_agentd.conf. Dit wordt momenteel niet ondersteund. Als je wilt dat je module bepaalde configuratieparameters gebruikt, moet je waarschijnlijk de parsing van een specifiek configuratiebestand voor de module implementeren.