See www.zabbix.com for the official Zabbix site.

Docs/specs/ZBXNEXT-1550

From Zabbix.org
Jump to: navigation, search

Support of loadable modules to extend functionality of Zabbix agents, also simple checks for Server and Proxy.

ZBXNEXT-1550

Status: v1.1

Owner: Alexei, Sasha

Summary

User parameters are quite heavy since they require a fork(). Loadable modules implemented as dynamic libraries may solve this problem and will also enable exchange of modules written by Zabbix community.

Specification

Zabbix agent (both daemon and standalone versions), server and proxy will support two additional configuration parameters

  • LoadModulePath
    • Description: full path to directory where the modules are located
    • Default value is {$libdir}/modules/
  • LoadModule
    • Description: module name to load. For example: LoadModule=smart.so
    • It is allowed to include multiple LoadModule parameters

All items supported by the modules will become available for use as normal agent items (if loaded by the agent) or as new simple checks for server and proxy.

All modules will be loaded when Zabbix process starts.

Functionality of modules

A module exports the following functions:

Initizalization and cleanup

  • int zbx_module_api_version();
    • The function returns module api version number. It is called once on process startup.
    • Return value: ZBX_MODULE_API_VERSION_ONE (it is defined as integer 1). For example:
 int zbx_module_api_version()
 {
         return ZBX_MODULE_API_VERSION_ONE;
 }


  • int zbx_module_init();
    • The function will be called when a module is loaded and may contain optional initialization routines. It is called once on agent startup.
    • Return value: ZBX_MODULE_OK - success, ZBX_MODULE_FAIL - failure
  • int zbx_module_uninit();
    • The function will be called just before unloading a module and may contain freeing allocated resources, closing file descriptors, etc. It is called only once on agent shutdown.
    • Return value: ZBX_MODULE_OK - success, ZBX_MODULE_FAIL - failure

Support of new items

  • ZBX_METRIC *zbx_module_item_list()
    • Return list of items supported by the module. The function is optional.
    • Return value: array of metrics, for example:
 static ZBX_METRIC keys[] =
 /*      KEY                     FLAG            FUNCTION                TEST PARAMETERS */
 {
         {"dummy.ping",          0,              zbx_module_dummy_ping,  NULL},
         {"dummy.echo",          CF_HAVEPARAMS,  zbx_module_dummy_echo,  "a message"},
         {"dummy.random",        CF_HAVEPARAMS,  zbx_module_dummy_random,"1,1000"},
         {NULL}
 };
 ZBX_METRIC *zbx_module_item_list()
 {
         return keys;
 }


    • KEY - item key
    • FLAG - CF_HAVEPARAMS means that the item accepts parameters
    • TEST PARAMETERS - test parameters, used when executing zabbix_agentd with -t or -p flag
    • FUNCTION - function exported by the module, for example:
 /******************************************************************************
  *                                                                            *
  * Function: zbx_module_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->timeout - processing should not take longer than     *
  *                                 this number of seconds                     *
  *              request->params[N-1] - pointers to item key parameters        *
  *                                                                            *
  *             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_param(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.                             *
  *                                                                            *
  ******************************************************************************/
 int zbx_module_dummy_random(AGENT_REQUEST *request, AGENT_RESULT *result)
 {
         int     from, to;
 
         if (request->nparam != 2)
         {
                 /* set optional error message */
                 SET_MSG_RESULT(result, strdup("Incorrect number of parameters, expected two parameters."));
                 return SYSINFO_RET_FAIL;
         }
 
         /* there is no strict validation of parameters for simplicity sake */
         from = atoi(get_rparam(request, 0));
         to = atoi(get_rparam(request, 1));
 
         if (from > to)
         {
                 SET_MSG_RESULT(result, strdup("Incorrect range given."));
                 return SYSINFO_RET_FAIL;
         }
 
         SET_UI64_RESULT(result, from + rand() % (to - from+1));
 
         return  SYSINFO_RET_OK;
 }

Error handling

Zabbix process may stop with one of the following error message:

  • Loading module failed due to various reasons: 'cannot load module "<module_name>": <dlerror>'
  • Missing module any function: 'cannot find "<function_name()>" function in module <module_name>: <dlerror>'
  • Incompatible module version: 'unsupported module "<module_name>" version: <version>'
  • Initialization function returned failure: 'cannot initialize module "<module_name>"'

Also it will stop if:

  • Item key already known to Zabbix
    • Item key loading order: standard parameters, modules, user parameters
    • Error message: 'cannot load module "<module_name>": key "<key>" already exists'

Zabbix process won't stop if:

  • Missing timeout function
  • Missing item list function
  • Missing uninit function or it failed

Timeout handling

It is a responsibility of module functions to handle timeouts in a proper way. Zabbix processes will set timeout value by executing function:

  • void zbx_module_item_timout(int timeout);
    • Set timeout for processing of module items, the function is called on startup.

The function is optional it may not exist for a module.

Agent items

Agent items will use same C API as for module items:

 int METRIC(AGENT_REQUEST *request, AGENT_RESULT *result)

Dummy module

A sample (dummy) module has to be included into the Zabbix distribution along with a Makefile.

  • dummy.c and Makefile will be located under src/modules/dummy/

Documentation

  • What's new
  • Zabbix Manual 2.2

Test cases

  • Loading of modules
    • Missing module functions
    • Wrong version number
    • Missing library
  • -t and -p parameters must be tested with module items
  • Items with and without parameters should work fine

Known limitations

  • No Windows support
  • The modules will not support configuration parameters set in zabbix configuration files.

ChangeLog

  • 1.1 updated error messages in section "Error handling"