2 Passive and active agent checks

Overview

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

Zabbix uses a JSON-based communication protocol for communicating with the agents.

Zabbix agent and Zabbix agent 2 protocols have been unified since Zabbix 7.0. The difference between Zabbix agent and Zabbix agent 2 requests/responses is expressed by the "variant" tag value.

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.

Passive checks are executed asynchronously - it is not required to receive the response to one request before other checks are started. DNS resolving is asynchronous as well.

The maximum concurrency of asynchronous checks is 1000 (defined by MaxConcurrentChecksPerPoller).

The number of asynchronous agent pollers is defined by the StartAgentPollers parameter.

Server request

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

{
         "request": "passive checks",
         "data": [
           {
             "key": "agent.version",
             "timeout": 3
           }
         ]
       }

Agent response

{
         "version": "7.2.0",
         "variant": 2,
         "data": [
           {
             "value": "7.2.0"
           }
         ]
       }

For example, for supported items:

1. Server opens a TCP connection
2. Server sends <HEADER><DATALEN>{"request":"passive checks","data":[{"key":"agent.ping","timeout":3}]}
3. Agent reads the request and responds with <HEADER><DATALEN>{"version":"7.2.0","variant":2,"data":[{"value":1}]}
4. Server processes data to get the value, '1' in our case
5. TCP connection is closed

For not supported items:

1. Server opens a TCP connection
2. Server sends <HEADER><DATALEN>{"request":"passive checks","data":[{"key":"vfs.fs.size[/nono]","timeout":3}]}
3. Agent reads the request and responds with <HEADER><DATALEN>{"version":"7.2.0","variant":2,"data":[{"error":"Unsupported item key."}]}
4. Server processes data, changes item state to not supported with the specified error message
5. TCP connection is closed

Failover to old protocol

To make sure that Zabbix server or proxy can work with agents from pre-7.2 versions, which have plaintext protocol, a failover to the old protocol is implemented.

Passive checks are performed using the JSON protocol (7.2 and later) after restart or when the interface configuration is changed. If no valid JSON is received in response (agent sent "ZBX_NOTSUPPORTED"), Zabbix will cache the interface as old protocol and retry the check by sending only the item key.

Note that every hour Zabbix server/proxy will again try working with the new protocol with all interfaces, falling back to the old protocol if required.

Active checks

Active checks require more complex processing. The agent must first retrieve from the server/proxy a list of items and/or remote commands for independent processing.

The servers/proxies 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.

The agent then periodically sends the new values to the server(s). If the agent received any remote commands to execute, the execution result will also be sent. Note that remote command execution on an active agent is supported since Zabbix agent 7.0.

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,
         "version": "7.2.0",
         "variant": 2,
         "config_revision": 1,
         "session": "e3dcbd9ace2c9694e1d7bbd030eeef6e"
       }

Server response

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

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

The server must respond with success.

For example:

1. Agent opens a TCP connection
2. Agent asks for the list of checks
3. Server responds with a list of items and remote commands to execute
4. Agent parses the response
5. TCP connection is closed
6. Agent starts periodical collection of data and executes remote commands (supported since Zabbix agent 7.0)

Sending in collected data

Agent sends

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

{
         "request": "agent data",
         "data": [
           {
             "id": 1,
             "itemid": 5678,
             "value": "7.0.0",
             "clock": 1712830783,
             "ns": 76808644
           },
           {
             "id": 2,
             "itemid": 1234,
             "value": "69672",
             "clock": 1712830783,
             "ns": 77053975
           }
         ],
         "commands": [
           {
             "id": 1324,
             "value": "16G"
           }
         ],
         "session": "1234456akdsjhfoui",
         "host": "Zabbix server",
         "version": "7.2.0",
         "variant": 2
       }

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 the agent after processing the agent data request.

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

For example:

1. Agent opens a TCP connection
2. Agent sends a list of values
3. Server processes the data and sends the status back
4. 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.

Heartbeat message

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

It is used to monitor the availability of active checks.

{
         "request": "active check heartbeat",
         "host": "Zabbix server",
         "heartbeat_freq": 60,
         "version": "7.2.0",
         "variant": 2
       }

Older XML protocol