2 Streaming to external systems

Overview

It is possible to stream item values and events from Zabbix to external systems over HTTP (see protocol details).

This feature currently has experimental status.

The tag filter can be used to stream subsets of item values or events.

Two Zabbix server processes are responsible for data streaming: connector manager and connector worker. A Zabbix internal item zabbix[connector_queue] allows to monitor the count of values enqueued in the connector queue.

Configuration

The following steps are required to configure data streaming to an external system:

1. Have a remote system set up for receiving data from Zabbix.

See the documentation of a simple receiver. The receiver currently logs the received information in events.ndjson and history.ndjson files.

2. Set the required number of connector workers in Zabbix (see StartConnectors in zabbix_server.conf). Restart the Zabbix server.

3. Configure a new connector in Zabbix (Administration -> General -> Connectors) and reload the server cache with “zabbix_server -R config_cache_reload”.

Mandatory fields are marked by an asterisk.

Protocol

Communication between the server and the receiver is done over HTTP using REST API, NDJSON, “Content-Type: application/x-ndjson”.

For more details, see newline-delimited JSON export protocol.

Server request

Example of sending item values:

POST /v1/history HTTP/1.1
       Host: localhost:8080
       Accept: */*
       Accept-Encoding: deflate, gzip, br, zstd
       Content-Length: 628
       Content-Type: application/x-ndjson
       {"host":{"host":"Zabbix server","name":"Zabbix server"},"groups":["Zabbix servers"],"item_tags":[{"tag":"foo","value":"test"}],"itemid":44457,"name":"foo","clock":1673454303,"ns":800155804,"value":0,"type":3}
       {"host":{"host":"Zabbix server","name":"Zabbix server"},"groups":["Zabbix servers"],"item_tags":[{"tag":"foo","value":"test"}],"itemid":44457,"name":"foo","clock":1673454303,"ns":832290669,"value":1,"type":3}
       {"host":{"host":"Zabbix server","name":"Zabbix server"},"groups":["Zabbix servers"],"item_tags":[{"tag":"bar","value":"test"}],"itemid":44458,"name":"bar","clock":1673454303,"ns":867770366,"value":123,"type":3}

Example of sending events:

POST /v1/events HTTP/1.1
       Host: localhost:8080
       Accept: */*
       Accept-Encoding: deflate, gzip, br, zstd
       Content-Length: 333
       Content-Type: application/x-ndjson
       {"clock":1673454303,"ns":800155804,"value":1,"eventid":5,"name":"trigger for foo being 0","severity":0,"hosts":[{"host":"Zabbix server","name":"Zabbix server"}],"groups":["Zabbix servers"],"tags":[{"tag":"foo_trig","value":"test"},{"tag":"foo","value":"test"}]}
       {"clock":1673454303,"ns":832290669,"value":0,"eventid":6,"p_eventid":5}

Receiver response

The response consists of the HTTP response status code and the JSON payload. The HTTP response status code must be “200” for requests that were handled successfully, other for failed requests.

Example of success:

localhost:8080/v1/history": HTTP/1.1 200 OK
       Date: Wed, 11 Jan 2023 16:40:30 GMT
       Content-Length: 0

Example with errors:

localhost:8080/v1/history": HTTP/1.1 422 Unprocessable Entity
       Content-Type: application/json
       Date: Wed, 11 Jan 2023 17:07:36 GMT
       Content-Length: 55
       {"error":"invalid character '{' after top-level value"}