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

Docs/specs/ZBXNEXT-101

From Zabbix.org
Jump to: navigation, search

Runtime control of Zabbix processes

ZBXNEXT-101

Status: Initial draft, do not comment

Owner: Andris Zeila

Summary

Runtime control of Zabbix daemons (server, proxy and agent) is possible by starting the daemon with -R command line option. Currently it accepts the following values:

  • config_cache_reload - reload configuration cache
  • housekeeper_execute - force housekeeper to start housekeeping procedure
  • log_level_increase[=<scope>] - increase log level for processes in the specified scope
  • log_level_decrease[=<scope>] - decrease log level for processes in the specified scope

The -R command line option is available only on Unix like platforms supporting sigqueue() function.

Configuration cache reloading (config_cache_reload)

This option is available only for server and proxy daemons. It forces configuration syncer to reload configuration cache.

Starting housekeeping procedure (housekeeper_execute)

This option is available only for server and proxy daemons. It forces housekeeper to start housekeeping procedure without waiting the configured time period.

Log level changing (log_level_increase, log_level_decrease)

This option is available for all daemon types. It allows to increase or decrease log level for all the specified process, all processes of the specified process type or all processes started by daemon.

The scope can be specified as:

  • <no scope> - changes log level for all processes (for example -R log_level_increase)
  • <pid> - changes log level for the specified process (for example -R log_level_increase=1234)
  • <process type> - changes log level for all processes of the specified type (for example -R log_level_increase=trapper)
  • <process type>,<N> - changes log level for Nth process of the specified type (for example -R log_level_increase=trapper,2)

Specification

The runtime control is done by sending signal with data to the main daemon process which forwards it to the processes specified by scope. Because of that the runtime control is possible only on systems supporting sigqueue() function.

The signal data contains 4 bytes and is defined as follows:

[msg][   ][   ][   ]

where msg can be:
   1 - increase log level
   2 - decrease log level
   3 - execute housekeeping procedure
   8 - reload configuration cache

Increase/decrease log level (1, 2)
  The full message structure is:
    [ msg ][scope][    data    ]

  msg   - a single byte containing message code (1 or 2)
  scope - a single byte defining target scope
  data  - two bytes of additional data

  Target scope defines the target processes of log level increase/decrease
  messages:
    If the most significant bit is zero, then the 7 least significant bits specify
    the Zabbix process type (see ZBX_PROCESS_TYPE_* defines) and the two data bytes 
    contain the specific process number or 0 to target all Zabbix processes of the
    specified type. 
    For example 0x000002 will target the second poller process and 0x0a0000 will
    target all history syncer processes.
  
    If the most significant bit is one, then the 7 least significant bits specify
    the scope resolution with the following value defined:
       1 - target process by pid. The two data bytes contain either pid of target 
           process or 0 if the message has to be sent to all processes.
    For example 0x810000 will target all processes, while 0x814567 will target 
    process with pid 0x4567.

Execute housekeeping procedure (3)
  The msg byte contains the message code and the rest of bytes are undefined.
  This message is sent only to the housekeeper process.

Reload configuration cache (8)
  The msg byte contains the message code and the rest of bytes are undefined.
  This message is sent only to the configuration syncer process.