See www.zabbix.com for the official Zabbix site.

Docs/protocols/zabbix agent/2.0

From Zabbix.org
Jump to: navigation, search

Zabbix agent protocol

Passive checks


Note: zabbix_get uses the agent protocol. In Zabbix 1.3.5 it changed from the basic protocol to the new one with the full ZBXD header.

The agent listens for connections on the configured agent port (default is 10050) and waits for Zabbix to connect. After connecting, Zabbix will send the following request:

 itemkey[param1,param2,param3]\n

\n means a linefeed character, byte value 0x0A (dec 10).

The agent must then respond with the value of the data item as follows:

Field Description Value
Header Fixed value ZBXD
Version Byte containing the protocol version 0x01
Data length 64 bit integer in little-endian byte order Length of the data field in bytes
Data The response to the request (base 10) Item value

All messages from the Zabbix 1.4 agent to the server are expected to use the same protocol header described above. It will simply be called "Protocol header" below. The Zabbix 1.4 server will *not* send the header in messages to the agent.

Example request:

 queue.messages.Count[DomainManager,MgmtBroker,SampleQ1]\n

Response bytes:

 5a 42 58 44 01 03 00 00 00 00 00 00 00 31 31 30
Bytes Meaning
5a 42 58 44 ZBXD
01 Protocol version 1
03 00 00 00 00 00 00 00 Data length: 3 bytes
31 31 30 110 (data value)

This protocol supports multiple requests and responses over a single TCP connection. This doesn't seem to be implemented in Zabbix yet, it might be later. After sending the result, the agent should check for more incoming request data and close the connection if there is none. This will allow future Zabbix versions to send multiple requests without having to change the agent code.

When the agent receives a request for an item it doesn't support, it should return ZBX_NOTSUPPORTED in the data value field, the response structure stays the same. The server will then disable the item and not ask for it again for some time. When the server has been configured to retry unsupported items (default after 10 minutes), it will request that data item again.

The agent is also allowed to return ZBX_ERROR for recoverable errors. The Zabbix server should then poll the agent again whenever it wants to retrieve the item value.

Note: This feature is currently broken - see ZBX-12050.

Active agents

When an active agent starts, it connects to the server to ask for any item it should be monitoring:

{
        "request":"active checks",
        "host":"Host name"
}

If host has non-default listen IP or port set, they are included in this request:

{
    "host": "Host name",
    "ip": "127.0.0.1",
    "port": 10055,
    "request": "active checks"
}
Items to be monitored exist

If the host is monitored and there are active items on it, agent will receive list of those items:

{
        "response":"success",
        "data":[
                {
                        "key":"mysql.queries[delete]",
                        "delay":30,
                        "lastlogsize":0,
                        "mtime":0},
                {
                        "key":"mysql.queries[insert]",
                        "delay":30,
                        "lastlogsize":0,
                        "mtime":0},
                {
                        "key":"mysql.queries[select]",
                        "delay":30,
                        "lastlogsize":0,
                        "mtime":0},
                {
                        "key":"log[\/var\/log\/localmessages,@errors]",
                        "delay":1,
                        "lastlogsize":12169,
                        "mtime":0},
                {
                        "key":"logrt[\/var\/log\/.*messages]",
                        "delay":1,
                        "lastlogsize":0,
                        "mtime":0},

                {
                        "key":"mysql.queries[update]",
                        "key_orig":"mysql.queries[{$UPDATE}]",
                        "delay":30,
                        "lastlogsize":0,
                        "mtime":0}],
        "regexp":[
                {
                        "name":"errors",
                        "expression":"error",
                        "expression_type":0,
                        "exp_delimiter":",",
                        "case_sensitive":1},
                {
                        "name":"errors",
                        "expression":"problem",
                        "expression_type":0,
                        "exp_delimiter":",",
                        "case_sensitive":0},
                {
                        "name":"errors",
                        "expression":"^Failed",
                        "expression_type":3,
                        "exp_delimiter":",",
                        "case_sensitive":1}]}

Things to pay attention to:

  • Although lastlogsize is only needed for log and logrt items, it has to be sent for all items as older agent versions expect that.
  • Although mtime is only needed for logrt items, it has to be sent for all items as older agent versions expect that.
  • If a valid global regular expression is used, it is sent in the regexp section.
  • If a user macro is used, key is resolved, and the original key (with literar user macro name) is sent as key_orig.

Agent will disconnect and collect some data. Once data is collected, it will connect to the server again and send it. Multiple values may be sent in one connection.

{
        "request":"agent data",
        "data":[
                {
                        "host":"Host name",
                        "key":"mysql.queries[insert]",
                        "value":"492508",
                        "clock":1360150944,
                        "ns":386084028},
                {
                        "host":"Host name",
                        "key":"mysql.queries[select]",
                        "value":"2611786",
                        "clock":1360150944,
                        "ns":397846705},
                {
                        "host":"Server 115",
                        "key":"mysql.queries[{$UPDATE}]",
                        "value":"2689218",
                        "clock":1360316924,
                        "ns":714401905},
                {
                        "host":"Server 115",
                        "key":"log[\/var\/log\/localmessages]",
                        "value":"Jan 30 18:26:44 linux-h5fr dhcpcd[3782]: eth0: adding default route via 192.168.5.1 metric 0",
                        "lastlogsize":4315,
                        "clock":1360314499,
                        "ns":699351525},
                {
                        "host":"Server 115",
                        "key":"logrt[\/var\/log\/.*messages]",
                        "value":"Jan 26 18:26:48 linux-h5fr dhcpcd[3410]: eth0: broadcasting for a lease",
                        "lastlogsize":225,
                        "mtime":1360297600,
                        "clock":1360317696,
                        "ns":103174218}

        ],
        "clock":1360150949,
        "ns":412904960
}

Things to pay attention to:

  • When sending data back for item that used user macro, key_orig is used as the key.
  • For log item, additionally lastlogsize is sent.
  • For logrt item, additionally mtime is sent.

Server will respond with a summary:

{
        "response":"success",
        "info":"Processed 3 Failed 0 Total 3 Seconds spent 0.000110"
}

It is also possible that some of the values could not be accepted for some reason. They are not identified in the response.

Note: A feature request to identify failed items: ZBXNEXT-246
Note: A feature request to make the output more readable: ZBXNEXT-935
{
        "response":"success",
        "info":"Processed 2 Failed 1 Total 3 Seconds spent 0.000113"
}
No active items

If host exists and is monitored, but has no active items, agent will receive empty data set:

{
        "response":"success",
        "data":[]
}
Host does not exist
{
        "response":"failed",
        "info":"host [Host name] not found"
}
Host not monitored

Host exists, but is disabled:

{
        "response":"failed",
        "info":"host [Host name] not monitored"
}