3 Zabbix agent 2 protocol

Overview

This section provides information on:

Agent2 -> Server : active checks request
Server -> Agent2 : active checks response
Agent2 -> Server : agent data request
Server -> Agent2 : agent data response
Agent2 -> Server : heartbeat message

Active checks 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.

Field	Type	Mandatory	Value
request	string	yes	`active checks`
host	string	yes	Host name.
version	string	yes	The agent version: <major>.<minor>.
host_metadata	string	no	The configuration parameter HostMetadata or HostMetadataItem metric value.
interface	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.

Example:

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

Active checks response

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

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.
	itemid	number	no	Item identifier.
	delay	string	no	Item update interval.
	lastlogsize	number	no	Item lastlogsize.
	mtime	number	no	Item mtime.
	timeout	string	no	Item timeout.
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.
commands		array of objects	no	Remote commands to execute. Included if remote command execution has been triggered by an action operation or manual script execution. Note that remote command execution on an active agent is supported since Zabbix agent 7.0. Older active agents will ignore any remote commands included in the active checks server response.
	command	string	no	Remote command.
	id	number	no	Remote command identifier.
	wait	number	no	Remote command mode of execution ("0" (nowait) for commands from action operations; "1" (wait) for commands from manual script execution).
config_revision		number	no	Configuration identifier for incremental configuration sync. Omitted if host configuration is unchanged. Incremented if host configuration is changed.

Example:

{
         "response": "success",
         "data": [
           {
             "key": "log[/home/zabbix/logs/zabbix_agentd.log]",
             "itemid": 1234,
             "delay": "30s",
             "lastlogsize": 0,
             "mtime": 0
           },
           {
             "key": "agent.version",
             "itemid": 5678,
             "delay": "10m",
             "lastlogsize": 0,
             "mtime": 0,
             "timeout": "4s"
           }
         ],
         "commands": [
           {
             "command": "df -h --output=source,size / | awk 'NR>1 {print $2}'",
             "id": 1324,
             "wait": 1
           }
         ],
         "config_revision": 2
       }

Agent data request

The agent data request contains the gathered item values and the values for executed remote commands (if any).

Field		Type	Mandatory	Value
request		string	yes	`agent data`
host		string	yes	Host name.
version		string	yes	The agent version: <major>.<minor>.
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).
	itemid	number	yes	Item identifier.
	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.
commands		array of objects	no	Remote commands execution result. Note that remote command execution on an active agent is supported since Zabbix agent 7.0. Older active agents will ignore any remote commands included in the active checks server response.
	id	number	no	Remote command identifier.
	value	string	no	Remote command execution result if the execution was successful.
	error	string	no	Remote command execution error message if the execution failed.

Example:

{
         "request": "agent data",
         "data": [
           {
             "id": 1,
             "itemid": 5678,
             "value": "2.4.0",
             "clock": 1400675595,
             "ns": 76808644
           },
           {
             "id": 2,
             "itemid": 1234,
             "lastlogsize": 112,
             "value": " 19845:20140621:141708.521 Starting Zabbix Agent [<hostname>]. Zabbix 2.4.0 (revision 50000).",
             "clock": 1400675595,
             "ns": 77053975
           }
         ],
         "commands": [
           {
             "id": 1324,
             "value": "16G"
           }
         ],
         "host": "Zabbix server",
         "version": "7.0",
         "session": "1234456akdsjhfoui"
       }

Agent data response

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

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

Example:

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

Heartbeat message

The heartbeat message is sent by an active agent to Zabbix server/proxy every HeartbeatFrequency seconds (configured in the Zabbix agent 2 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).

Documentation

3 Zabbix agent 2 protocol

Overview

Active checks request

Active checks response

Agent data request

Agent data response

Heartbeat message