This is a translation of the original English documentation page. Help us make it better.

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

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 inervals.

Field Type Value
request string active checks
host string Host name.
version string The agent version: <major>.<minor>.
host_metadata string The configuration parameter HostMetadata or HostMetadataItem metric value (optional).
interface string The configuration parameter HostInterface or HostInterfaceItem metric value (optional).
ip string The configuration parameter ListenIP first IP if set (optional).
port number The configuration parameter ListenPort value if set and not default agent listening port (optional).

Example:

{
         "request": "active checks",
         "host": "Zabbix server",
         "version": "6.0",
         "host_metadata": "mysql,nginx",
         "hostinterface": "zabbix.server.lan",
         "ip": "159.168.1.1",
         "port": 12050
       }

Active checks response

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

Field Type Value
response string success | failed
info string Error information in the case of failure (optional).
data array of objects Active check items (optional).
key string Item key with expanded macros.
itemid number Item identifier.
delay string Item update interval.
lastlogsize number Item lastlogsize.
mtime number Item mtime.
refresh_unsupported number Unsupported item refresh interval (agent version < 5.4).
regexp array of objects Global regular expressions (optional).
name string Global regular expression name.
expression string Global regular expression.
expression_type number Global regular expression type.
exp_delimiter string Global regular expression delimiter.
case_sensitive number Global regular expression case sensitiviness setting.

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
           }
         ]
       }

Agent data request

The agent data request contains the gathered item values.

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

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
           }
         ],
         "host": "Zabbix server",
         "version": "6.0",
         "sessionid": "1234456akdsjhfoui"
       }

Agent data response

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

Field Type Value
response string success | failed
info string 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).