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

Docs/protocols/zabbix agent/3.0

From Zabbix.org
Jump to: navigation, search

Zabbix agent protocol

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 metadata to send, it is included in this request:

{
        "host": "Host name",
        "host_metadata": "apache|mysql|postfix",
        "request": "active checks"
}

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"
}
Meta information update

Log items (log, logrt and eventlog) may receive meta information update message from agent. In case "lastlogsize", "mtime" or "state" of the monitored item changes but there is no value, this information will still be sent to the server. Meta information is not visible in the frontend and is meant only for the server to update item parameters. Keeping this information on server allows agent restart as well as loosing data from proxy database at any time. An example of messages sent from agent to proxy or server (note meta information update messages are missing "value" tag, except for when item becomes unsupported):

// regular message
{
    "host":"Server 115",
    "key":"logrt[/var/log/.*messages,linux]",
    "value":"Jan 26 18:26:48 linux-h5fr dhcpcd[3410]: eth0: broadcasting for a lease",
    "lastlogsize":225,
    "mtime":1360297600,
    "clock":1360317696,
    "ns":103174218
}

// "lastlogsize" and "mtime" changed
{
    "host":"Server 115",
    "key":"logrt[/var/log/.*messages,linux]",
    "lastlogsize":375,
    "mtime":1360297610,
    "clock":1360317697,
    "ns":471824374
}

// "lastlogsize" changed
{
    "host":"Server 115",
    "key":"logrt[/var/log/.*messages,linux]",
    "lastlogsize":375,
    "clock":1360317697,
    "ns":471824374
}

// item became not supported
{
    "host":"Server 115",
    "key":"logrt[/var/log/.*messages,linux]",
    "value":"Cannot open file \"/var/log/messages\": [13] Permission denied",
    "lastlogsize":375,
    "mtime":1360297610,
    "clock":1360317712,
    "ns":44846123,
    "state":1
}

// item became supported
{
    "host":"Server 115",
    "key":"logrt[/var/log/.*messages,linux]",
    "lastlogsize":412,
    "mtime":1360297715,
    "clock":1360317718,
    "ns":536131222
}