Table of Contents

2 Passive and active agent checks

2 Passive and active agent checks

Overview

This section provides details on passive and active checks performed by Zabbix agent.

Zabbix uses a JSON based communication protocol for communicating with Zabbix agent.

See also: Zabbix agent 2 protocol details.

Passive checks

A passive check is a simple data request. Zabbix server or proxy asks for some data (for example, CPU load) and Zabbix agent sends back the result to the server.

Server request

For definition of header and data length please refer to protocol details.

<item key>

Agent response

<DATA>[\0<ERROR>]

Above, the part in square brackets is optional and is only sent for not supported items.

For example, for supported items:

Server opens a TCP connection
Server sends <HEADER><DATALEN>agent.ping
Agent reads the request and responds with <HEADER><DATALEN>1
Server processes data to get the value, '1' in our case
TCP connection is closed

For not supported items:

Server opens a TCP connection
Server sends <HEADER><DATALEN>vfs.fs.size[/nono]
Agent reads the request and responds with <HEADER><DATALEN>ZBX_NOTSUPPORTED\0Cannot obtain filesystem information: [2] No such file or directory
Server processes data, changes item state to not supported with the specified error message
TCP connection is closed

Active checks

Active checks require more complex processing. The agent must first retrieve from the server(s) a list of items for independent processing.

The servers to get the active checks from are listed in the 'ServerActive' parameter of the agent configuration file. The frequency of asking for these checks is set by the 'RefreshActiveChecks' parameter in the same configuration file. However, if refreshing active checks fails, it is retried after hardcoded 60 seconds.

In order to decrease network traffic and resources usage Zabbix server or Zabbix proxy will provide configuration only if Zabbix agent still hasn't received configuration or if something has changed in host configuration, global macros or global regular expressions.

The agent then periodically sends the new values to the server(s).

If an agent is behind the firewall you might consider using only Active checks because in this case you wouldn't need to modify the firewall to allow initial incoming connections.

Getting the list of items

Agent request

The active checks request is used to obtain the active checks to be processed by agent. This request is sent by the agent upon start and then with RefreshActiveChecks intervals.

{
         "request": "active checks",
         "host": "Zabbix server",
         "host_metadata": "mysql,nginx",
         "hostinterface": "zabbix.server.lan",
         "ip": "159.168.1.1",
         "port": 12050,
         "config_revision": 1,
         "session": "e3dcbd9ace2c9694e1d7bbd030eeef6e"
       }

Field	Type	Mandatory	Value
request	string	yes	`active checks`
host	string	yes	Host name.
host_metadata	string	no	The configuration parameter HostMetadata or HostMetadataItem metric value.
hostinterface	string	no	The configuration parameter HostInterface or HostInterfaceItem metric value.
ip	string	no	The configuration parameter ListenIP first IP if set.
port	number	no	The configuration parameter ListenPort value if set and not default agent listening port.
config_revision	number	no	Configuration identifier for incremental configuration sync.
session	string	no	Session identifier for incremental configuration sync.

Server response

The active checks response is sent by the server back to agent after processing the active checks request.

{
         "response": "success",
         "data": [
           {
             "key": "log[/home/zabbix/logs/zabbix_agentd.log]",
             "key_orig": "log[/home/zabbix/logs/zabbix_agentd.log]",
             "itemid": 1234,
             "delay": "30s",
             "lastlogsize": 0,
             "mtime": 0
           },
           {
             "key": "agent.version",
             "key_orig": "agent.version",
             "itemid": 5678,
             "delay": "10m",
             "lastlogsize": 0,
             "mtime": 0
           }
         ],
         "config_revision": 2
       }

Field		Type	Mandatory	Value
response		string	yes	`success` \| `failed`
info		string	no	Error information in the case of failure.
data		array of objects	no	Active check items. Omitted if host configuration is unchanged.
	key	string	no	Item key with expanded macros.
	key_orig	string	no	Item key without expanded macros.
	itemid	number	no	Item identifier.
	delay	string	no	Item update interval.
	lastlogsize	number	no	Item lastlogsize.
	mtime	number	no	Item mtime.
refresh_unsupported		number	no	Unsupported item refresh interval.
regexp		array of objects	no	Global regular expressions.
	name	string	no	Global regular expression name.
	expression	string	no	Global regular expression.
	expression_type	number	no	Global regular expression type.
	exp_delimiter	string	no	Global regular expression delimiter.
	case_sensitive	number	no	Global regular expression case sensitivity setting.
config_revision		number	no	Configuration identifier for incremental configuration sync. Omitted if host configuration is unchanged. Incremented if host configuration is changed.

The server must respond with success.

For example:

Agent opens a TCP connection
Agent asks for the list of checks
Server responds with a list of items (item key, delay)
Agent parses the response
TCP connection is closed
Agent starts periodical collection of data

Note that (sensitive) configuration data may become available to parties having access to the Zabbix server trapper port when using an active check. This is possible because anyone may pretend to be an active agent and request item configuration data; authentication does not take place unless you use encryption options.

Sending in collected data

Agent sends

The agent data request contains the gathered item values.

{
         "request": "agent data",
         "data": [
           {
             "host": "Zabbix server",
             "key": "agent.version",
             "value": "2.4.0",
             "clock": 1400675595,
             "ns": 76808644
           },
           {
             "host": "Zabbix server",
             "key": "log[/home/zabbix/logs/zabbix_agentd.log]",
             "lastlogsize": 112,
             "value": " 19845:20140621:141708.521 Starting Zabbix Agent [<hostname>]. Zabbix 2.4.0 (revision 50000).",
             "clock": 1400675595,
             "ns": 77053975
           }
         ],
         "session": "1234456akdsjhfoui"
       }

Field		Type	Mandatory	Value
request		string	yes	`agent data`
session		string	yes	Unique session identifier generated each time when agent is started.
data		array of objects	yes	Item values.
	id	number	yes	The value identifier (incremental counter used for checking duplicated values in the case of network problems).
	host	string	yes	Host name.
	key	string	yes	The item key.
	value	string	no	The item value.
	lastlogsize	number	no	The item lastlogsize.
	mtime	number	no	The item mtime.
	state	number	no	The item state.
	source	string	no	The value event log source.
	eventid	number	no	The value event log eventid.
	severity	number	no	The value event log severity.
	timestamp	number	no	The value event log timestamp.
	clock	number	yes	The value timestamp (seconds since Epoch).
	ns	number	yes	The value timestamp nanoseconds.

A virtual ID is assigned to each value. Value ID is a simple ascending counter, unique within one data session (identified by the session token). This ID is used to discard duplicate values that might be sent in poor connectivity environments.

Server response

The agent data response is sent by the server back to agent after processing the agent data request.

{
         "response": "success",
         "info": "processed: 2; failed: 0; total: 2; seconds spent: 0.003534"
       }

Field	Type	Mandatory	Value
response	string	yes	`success` \| `failed`
info	string	yes	Item processing results.

If sending of some values fails on the server (for example, because host or item has been disabled or deleted), agent will not retry sending of those values.

For example:

Agent opens a TCP connection
Agent sends a list of values
Server processes the data and sends the status back
TCP connection is closed

Note how in the example above the not supported status for vfs.fs.size[/nono] is indicated by the "state" value of 1 and the error message in "value" property.

Error message will be trimmed to 2048 symbols on server side.

Heartbeat message

The heartbeat message is sent by an active agent to Zabbix server/proxy every HeartbeatFrequency seconds (configured in the Zabbix agent configuration file).

It is used to monitor the availability of active checks.

{
         "request": "active check heartbeat",
         "host": "Zabbix server",
         "heartbeat_freq": 60
       }

Field	Type	Mandatory	Value
request	string	yes	`active check heartbeat`
host	string	yes	The host name.
heartbeat_freq	number	yes	The agent heartbeat frequency (HeartbeatFrequency configuration parameter).

Older XML protocol

Zabbix will take up to 16 MB of XML Base64-encoded data, but a single decoded value should be no longer than 64 KB otherwise it will be truncated to 64 KB while decoding.

Documentation