1 Export to files

Overview

It is possible to configure real-time exporting of trigger events, item values and trends in a newline-delimited JSON format.

Exporting is done into files, where each line of the export file is a JSON object. Value mappings are not applied.

In case of errors (data cannot be written to the export file or the export file cannot be renamed or a new one cannot be created after renaming it), the data item is dropped and never written to the export file. It is written only in the Zabbix database. Writing data to the export file is resumed when the writing problem is resolved.

The export file is created with read-write permissions for the file owner only. Additionally the file is readable by the owner group. All other permissions are denied.

Note that host/item can have no metadata (host groups, host name, item name) if the host/item was removed after the data was received, but before server exported data.

Configuration

Real-time export of trigger events, item values and trends is configured by specifying a directory for the export files - see the ExportDir parameter in server configuration.

Two other parameters are available:

  • ExportFileSize may be used to set the maximum allowed size of an individual export file. When a process needs to write to a file it checks the size of the file first. If it exceeds the configured size limit, the file is renamed by appending .old to its name and a new file with the original name is created.

A file will be created per each process that will write data (i.e. approximately 4-30 files). As the default size per export file is 1G, keeping large export files may drain the disk space fast.

  • ExportType allows to specify which entity types (events, history, trends) will be exported.

Newline-delimited JSON export protocol

This section presents details of the export protocol in a newline-delimited JSON format, used in:

All files have an .ndjson extension. Each line of the export file is a JSON object.

Trigger event export

The following information is exported for a problem event:

Field Type Description
clock number Number of seconds since Epoch to the moment when problem was detected (integer part).
ns number Number of nanoseconds to be added to clock to get a precise problem detection time.
value number 1 (always).
eventid number Problem event ID.
name string Problem event name.
severity number Problem event severity (0 - Not classified, 1 - Information, 2 - Warning, 3 - Average, 4 - High, 5 - Disaster).
hosts array List of hosts involved in the trigger expression; there should be at least one element in array.
- object
host string Host name.
name string Visible host name.
groups array List of host groups of all hosts involved in the trigger expression; there should be at least one element in array.
- string Host group name.
tags array List of problem tags (can be empty).
- object
tag string Tag name.
value string Tag value (can be empty).

The following information is exported for a recovery event:

Field Type Description
clock number Number of seconds since Epoch to the moment when problem was resolved (integer part).
ns number Number of nanoseconds to be added to clock to get a precise problem resolution time.
value number 0 (always).
eventid number Recovery event ID.
p_eventid number Problem event ID.
Trigger event export examples

Problem:

{"clock":1519304285,"ns":123456789,"value":1,"name":"Either Zabbix agent is unreachable on Host B or pollers are too busy on Zabbix Server","severity":3,"eventid":42, "hosts":[{"host":"Host B", "name":"Host B visible"},{"host":"Zabbix Server","name":"Zabbix Server visible"}],"groups":["Group X","Group Y","Group Z","Zabbix servers"],"tags":[{"tag":"availability","value":""},{"tag":"data center","value":"Riga"}]}

Recovery:

{"clock":1519304345,"ns":987654321,"value":0,"eventid":43,"p_eventid":42}

Problem (multiple problem event generation):

{"clock":1519304286,"ns":123456789,"value":1,"eventid":43,"name":"Either Zabbix agent is unreachable on Host B or pollers are too busy on Zabbix Server","severity":3,"hosts":[{"host":"Host B", "name":"Host B visible"},{"host":"Zabbix Server","name":"Zabbix Server visible"}],"groups":["Group X","Group Y","Group Z","Zabbix servers"],"tags":[{"tag":"availability","value":""},{"tag":"data center","value":"Riga"}]}

{"clock":1519304286,"ns":123456789,"value":1,"eventid":43,"name":"Either Zabbix agent is unreachable on Host B or pollers are too busy on Zabbix Server","severity":3,"hosts":[{"host":"Host B", "name":"Host B visible"},{"host":"Zabbix Server","name":"Zabbix Server visible"}],"groups":["Group X","Group Y","Group Z","Zabbix servers"],"tags":[{"tag":"availability","value":""},{"tag":"data center","value":"Riga"}]}

Recovery:

{"clock":1519304346,"ns":987654321,"value":0,"eventid":44,"p_eventid":43}

{"clock":1519304346,"ns":987654321,"value":0,"eventid":44,"p_eventid":42}

Item value export

The following information is exported for a collected item value:

Field Type Description
host object Host name of the item host.
host string Host name.
name string Visible host name.
groups array List of host groups of the item host; there should be at least one element in array.
- string Host group name.
item_tags array List of item tags (can be empty).
- object
tag string Tag name.
value string Tag value (can be empty).
itemid number Item ID.
name string Visible item name.
clock number Number of seconds since Epoch to the moment when value was collected (integer part).
ns number Number of nanoseconds to be added to clock to get a precise value collection time.
timestamp
(Log only)		 number 0 if not available.
source
(Log only)		 string Empty string if not available.
severity
(Log only)		 number 0 if not available.
eventid
(Log only)		 number 0 if not available.
value number (for numeric items) or
string (for text items)		 Collected item value.
type number Collected value type:
0 - numeric float, 1 - character, 2 - log, 3 - numeric unsigned, 4 - text, 5 - binary, 6 - JSON
Item value export example

Numeric (unsigned) value:

{"host":{"host":"Host B","name":"Host B visible"},"groups":["Group X","Group Y","Group Z"],"item_tags":[{"tag":"foo","value":"test"}],"itemid":3,"name":"Agent availability","clock":1519304285,"ns":123456789,"value":1,"type":3}

Numeric (float) value:

{"host":{"host":"Host B","name":"Host B visible"},"groups":["Group X","Group Y","Group Z"],"item_tags":[{"tag":"foo","value":"test"}],"itemid":4,"name":"CPU Load","clock":1519304285,"ns":123456789,"value":0.1,"type":0}

Character, text value:

{"host":{"host":"Host B","name":"Host B visible"},"groups":["Group X","Group Y","Group Z"],"item_tags":[{"tag":"foo","value":"test"}],"itemid":2,"name":"Agent version","clock":1519304285,"ns":123456789,"value":"3.4.4","type":4}

Log value:

{"host":{"host":"Host A","name":"Host A visible"},"groups":["Group X","Group Y","Group Z"],"item_tags":[{"tag":"foo","value":"test"}],"itemid":1,"name":"Messages in log file","clock":1519304285,"ns":123456789,"timestamp":1519304285,"source":"","severity":0,"eventid":0,"value":"log file message","type":2}

The following information is exported for a calculated trend value:

Field Type Description
host object Host name of the item host.
host string Host name.
name string Visible host name.
groups array List of host groups of the item host; there should be at least one element in array.
- string Host group name.
item_tags array List of item tags (can be empty).
- object
tag string Tag name.
value string Tag value (can be empty).
itemid number Item ID.
name string Visible item name.
clock number Number of seconds since Epoch to the moment when value was collected (integer part).
count number Number of values collected for a given hour.
min number Minimum item value for a given hour.
avg number Average item value for a given hour.
max number Maximum item value for a given hour.
type number Value type:
0 - numeric float, 3 - numeric unsigned

Numeric (unsigned) value:

{"host":{"host":"Host B","name":"Host B visible"},"groups":["Group X","Group Y","Group Z"],"item_tags":[{"tag":"foo","value":"test"}],"itemid":3,"name":"Agent availability","clock":1519311600,"count":60,"min":1,"avg":1,"max":1,"type":3}

Numeric (float) value:

{"host":{"host":"Host B","name":"Host B visible"},"groups":["Group X","Group Y","Group Z"],"item_tags":[{"tag":"foo","value":"test"}],"itemid":4,"name":"CPU Load","clock":1519311600,"count":60,"min":0.01,"avg":0.15,"max":1.5,"type":0}