Documentation
Table of Contents
#6 Módulos cargables
1 Visión general
Los módulos cargables ofrecen una opción orientada al rendimiento para ampliar Zabbix funcionalidad.
Ya hay formas de extender la funcionalidad de Zabbix a través de:
- parámetros de usuario (métricas de agente)
- verificaciones externas (supervisión sin agente)
sistema.ejecutar[]Zabbix agente artículo.
Funcionan muy bien, pero tienen un gran inconveniente, a saber, fork(). Zabbix tiene que bifurcar un nuevo proceso cada vez que maneja una métrica de usuario, que es no es bueno para el rendimiento. No es un gran problema normalmente, sin embargo, podría ser un problema grave al monitorear sistemas integrados, tener un gran cantidad de parámetros monitoreados o scripts pesados con lógica compleja o largo tiempo de arranque.
El soporte de módulos cargables ofrece formas de extender el agente Zabbix, servidor y proxy sin sacrificar el rendimiento.
Un módulo cargable es básicamente una biblioteca compartida utilizada por el demonio Zabbix y cargado en el arranque. La biblioteca debe contener ciertas funciones, por lo que que un proceso Zabbix puede detectar que el archivo es de hecho un módulo que puede cargar y trabajar con.
Los módulos cargables tienen una serie de beneficios. Gran rendimiento y capacidad de implementar cualquier lógica son muy importantes, pero quizás lo más ventaja importante es la capacidad de desarrollar, usar y compartir Zabbix módulos. Contribuye a un mantenimiento sin problemas y ayuda a entregar nueva funcionalidad más fácil e independiente de la base de código central de Zabbix.
La licencia y distribución de módulos en forma binaria se rige por la GPL licencia (los módulos se vinculan con Zabbix en tiempo de ejecución y usan Zabbix encabezados; actualmente todo el código de Zabbix está bajo licencia GPL). Zabbix no garantiza la compatibilidad binaria.
La estabilidad de la API del módulo está garantizada durante un Zabbix LTS (Long Term soporte) [lanzamiento] (http://www.zabbix.com/life_cycle_and_release_policy) ciclo. La estabilidad de la API de Zabbix no está garantizada (técnicamente es posible llamar a las funciones internas de Zabbix desde un módulo, pero hay ninguna garantía de que dichos módulos funcionen).
2 Módulo API
Para que una biblioteca compartida sea tratada como un módulo Zabbix, debe implementar y exportar varias funciones. Actualmente hay seis funciones en la API del módulo Zabbix, solo una de las cuales es obligatoria y los otros cinco son opcionales.
2.1 Interfaz obligatoria
La única función obligatoria es zbx_module_api_version():
Esta función debería devolver la versión de la API implementada por este módulo y para que el módulo se cargue, esta versión debe coincidir con el módulo Versión de API compatible con Zabbix. Versión de la API del módulo compatible con Zabbix es ZBX_MODULE_API_VERSION. Entonces esta función debería devolver esto constante. Antigua constante ZBX_MODULE_API_VERSION_ONE utilizada para esto El propósito ahora está definido para ser igual a ZBX_MODULE_API_VERSION para preservar compatibilidad de fuentes, pero no se recomienda su uso.
2.2 Interfaz opcional
Las funciones opcionales son zbx_module_init(), zbx_módulo_elemento_lista(), zbx_módulo_elemento_tiempo de espera(), zbx_module_history_write_cbs() y zbx_module_uninit():
Esta función debe realizar la inicialización necesaria para el módulo. (Si alguna). Si tiene éxito, debería devolver ZBX_MODULE_OK. De lo contrario debe devolver ZBX_MODULE_FAIL. En este último caso, Zabbix no comienzo.
Esta función debería devolver una lista de elementos admitidos por el módulo. Cada elemento se define en una estructura ZBX_METRIC, consulte la sección a continuación para detalles. La lista termina con una estructura ZBX_METRIC con campo "clave" de NULL.
Si el módulo exporta zbx_module_item_list() entonces esta función es utilizado por Zabbix para especificar la configuración de tiempo de espera en la configuración de Zabbix archivo que deben obedecer las comprobaciones de elementos implementadas por el módulo. Aquí, el parámetro "tiempo de espera" está en segundos.
Esta función debería devolver las funciones de devolución de llamada que el servidor Zabbix usará para historial de exportación de diferentes tipos de datos. Se proporcionan funciones de devolución de llamada como campos de la estructura ZBX_HISTORY_WRITE_CBS, los campos pueden ser NULL si módulo no está interesado en la historia de cierto tipo.
Esta función debe realizar la desinicialización necesaria (si corresponde) como liberar recursos asignados, cerrar descriptores de archivos, etc.
Todas las funciones se llaman una vez en el inicio de Zabbix cuando el módulo está cargado, con la excepción de zbx_module_uninit(), que se llama una vez en el apagado de Zabbix cuando se descarga el módulo.
2.3 Definición de elementos
Cada elemento se define en una estructura ZBX_METRIC:
estructura typedef
{
carácter *clave;
banderas sin firmar;
int(*función)();
char *parámetro_prueba;
}
ZBX_METRICO;Aquí, clave es la clave del elemento (por ejemplo, "dummy.random"), flags es ya sea CF_HAVEPARAMS o 0 (dependiendo de si el elemento acepta parámetros o no), función es una función C que implementa el elemento (por ejemplo, "zbx_module_dummy_random"), y test_param es el lista de parámetros que se usará cuando el agente Zabbix se inicie con "-p" bandera (por ejemplo, "1,1000", puede ser NULL). Una definición de ejemplo puede verse como este:
teclas estáticas ZBX_METRIC[] =
{
{ "ficticio.aleatorio", CF_HAVEPARAMS, zbx_module_dummy_random, "1,1000" },
{ NULO }
}Cada función que implementa un elemento debe aceptar dos punteros parámetros, el primero de tipo AGENT_REQUEST y el segundo de escriba AGENTE_RESULTADO:
int zbx_module_dummy_random(AGENT_REQUEST *solicitud, AGENT_RESULT *resultado)
{
...
SET_UI64_RESULT(resultado, de + rand() % (a - de + 1));
devolver SYSINFO_RET_OK;
}Estas funciones deberían devolver SYSINFO_RET_OK, si el valor del elemento era obtenido con éxito. De lo contrario, deberían devolver SYSINFO_RET_FAIL. Consulte el módulo "ficticio" de ejemplo a continuación para obtener detalles sobre cómo obtener información de AGENT_REQUEST y cómo configurar la información en AGENTE_RESULTADO.
2.4 Proporcionar devoluciones de llamada de exportación de historial
Ya no se admite la exportación de historial a través del módulo por proxy Zabbix desde Zabbix 4.0.0.
El módulo puede especificar funciones para exportar datos históricos por tipo: Numérico (flotante), numérico (sin signo), carácter, texto y registro:
estructura typedef
{
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_HISTORIA_ESCRIBIR_CBS;Cada uno de ellos debe tomar la matriz "historial" de elementos "historia_num" como argumentos Según el tipo de datos de historial que se exportará, "historial" es una matriz de las siguientes estructuras, respectivamente:
estructura typedef
{
zbx_uint64_t id del artículo;
reloj interno;
int ns;
doble valor;
}
ZBX_HISTORIA_FLOTANTE;
estructura typedef
{
zbx_uint64_t id del elemento;
reloj interno;
int ns;
valor zbx_uint64_t;
}
ZBX_HISTORIA_INTEGER;
estructura typedef
{
zbx_uint64_t id del elemento;
reloj interno;
int ns;
const char *valor;
}
ZBX_HISTORIA_STRING;
estructura typedef
{
zbx_uint64_t id del elemento;
reloj interno;
int ns;
const char *valor;
}
ZBX_HISTORIA_TEXTO;
estructura typedef
{
zbx_uint64_t id del artículo;
reloj interno;
int ns;
const char *valor;
const char *fuente;
marca de tiempo int;
int logeventid;
severidad int;
}
ZBX_HISTORIAL_REGISTRO;Las devoluciones de llamada serán utilizadas por los procesos sincronizadores del historial del servidor Zabbix en el fin del procedimiento de sincronización del historial después de escribir los datos en la base de datos de Zabbix y guardado en caché de valor.
En caso de error interno en el módulo de exportación de historial, se recomienda que el módulo esté escrito de tal manera que no bloquee el monitoreo completo hasta que se recupere, sino que descarte los datos y permita que el servidor Zabbix continúe ejecutándose.
2.5 Módulos de construcción
Actualmente, los módulos están destinados a construirse dentro del árbol de fuentes de Zabbix, porque la API del módulo depende de algunas estructuras de datos que se definen en los encabezados de Zabbix.
El encabezado más importante para módulos cargables es include/module.h, que define estas estructuras de datos. Otros encabezados del sistema necesarios que ayudan a include/module.h a funcionar correctamente son stdlib.h y stdint.h.
Con esta información en mente, todo está listo para que el módulo sea construido. El módulo debe incluir stdlib.h, stdint.h y module.h, y el script de compilación debe asegurarse de que estos archivos estén en la ruta de inclusión. Consulte el módulo "ficticio" de ejemplo a continuación para obtener más detalles.
Otro encabezado útil es include/log.h, que define Función zabbix_log(), que se puede usar para iniciar sesión y depurar propósitos
3 Parámetros de configuración
El agente, el servidor y el proxy de Zabbix son compatibles con dos parámetros para tratar módulos:
- LoadModulePath: ruta completa a la ubicación de los módulos cargables
- LoadModule: módulo(s) para cargar al inicio. Los módulos deben ser ubicado en un directorio especificado por LoadModulePath o la ruta debe preceda al nombre del módulo. Si la ruta anterior es absoluta (comienza con '/'), entonces se ignora LoadModulePath. Se permite incluir varios parámetros de LoadModule.
Por ejemplo, para extender el agente de Zabbix podríamos agregar lo siguiente parámetros:
LoadModulePath=/usr/local/lib/zabbix/agent/
LoadModule=mariadb.so
LoadModule=apache.so
LoadModule=kernel.so
LoadModule=/usr/local/lib/zabbix/dummy.soAl iniciar el agente, cargará mariadb.so, apache.so y kernel.so módulos del directorio /usr/local/lib/zabbix/agent mientras dummy.so se cargará desde /usr/local/lib/zabbix. Fallará si un módulo es falta, en caso de permisos incorrectos o si una biblioteca compartida no es un Módulo Zabbix.
4 Configuración de interfaz
Los módulos cargables son compatibles con el agente, el servidor y el proxy de Zabbix. Por lo tanto, el tipo de elemento en la interfaz de Zabbix depende de dónde esté el módulo cargado. Si el módulo se carga en el agente, el tipo de elemento debe ser "agente Zabbix" o "agente Zabbix (activo)". Si el módulo es cargado en el servidor o proxy, entonces el tipo de elemento debe ser "Simple controlar".
La exportación de historial a través de los módulos Zabbix no necesita ninguna interfaz configuración. Si el servidor carga correctamente el módulo y proporciona la función zbx_module_history_write_cbs() que devuelve al menos una función de devolución de llamada no NULL, entonces la exportación del historial será habilitado automáticamente.
5 Dummy module
Zabbix includes a sample module written in C language. The module is located under 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 READMEThe module is well documented, it can be used as a template for your own modules.
After ./configure has been run in the root of Zabbix source tree as described above, just run make in order to build 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;
}The module exports three new items:
dummy.ping- always returns '1'dummy.echo[param1]- returns the first parameter as it is, for example,dummy.echo[ABC]will return ABCdummy.random[param1, param2]- returns a random number within the range of param1-param2, for example,dummy.random[1,1000000]
6 Limitaciones
El soporte de módulos cargables se implementa solo para la plataforma Unix. Significa que no funciona para los agentes de Windows.
En algunos casos, un módulo puede necesitar leer la configuración relacionada con el módulo parámetros de zabbix_agentd.conf. Actualmente no es compatible. Si necesita que su módulo use algunos parámetros de configuración que debe probablemente implemente el análisis de un archivo de configuración específico del módulo.