Documentation

You are viewing documentation for the development version, it may be incomplete.
Join our translation project and help translate Zabbix documentation into your native language.

Sidebar

Zabbix Summit 2022
Register for Zabbix Summit 2022

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": "6.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.
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 sensitiviness setting.
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
           }
         ],
         "config_revision": 2
       }

Agent data request

The agent data request contains the gathered item values.

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.

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",
         "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).