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

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. For this purpose, the following tools are available:

• An example of a simple receiver that logs the received information in events.ndjson and history.ndjson files.
• Kafka connector for Zabbix server - a lightweight server written in Go, designed to forward item values and events from a Zabbix server to a Kafka broker.

2. Set the required number of connector workers in Zabbix by adjusting the StartConnectors parameter in zabbix_server.conf. The number of connector workers should match (or exceed if concurrent sessions are more than 1) the configured connector count in Zabbix frontend. Then, restart Zabbix server.

3. Configure a new connector in Zabbix frontend (Administration → General → Connectors) and reload the server cache with the zabbix_server -R config_cache_reload command.

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 streaming 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 streaming 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", "201", "202", "203", or "204" 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"}