Skip to content

Events / problems real-time export (legacy Zabbix behaviour)

This document describes how file-based real-time export of trigger events (problems and recoveries) worked in the original Zabbix code that Glaber inherited, how it is switched on/off, the NDJSON record shapes, and what is broken in the current Glaber tree.

Official upstream references (for comparison):

Note: Zabbix also exports history and trends through the same ExportDir machinery. This document focuses on events (ExportType=events), which are written into files named problems-*.ndjson.


Status in Glaber (why it is broken)

Layer Status
Config (ExportDir / ExportType / ExportFileSize) Still present and parsed in server.c
Export library (src/libs/zbxexport/export.c) Intact
Opening problems-*.ndjson files in history syncer / task manager / main Still done when events export is enabled
zbx_export_events() serialization Commented out in src/zabbix_server/glb_events.c
Call site after history sync Commented out in src/libs/zbxcachehistory/dbcache.c
In-memory event/recovery buffers used by export Event processing moved toward problems keeper; old export path no longer fed

So with ExportDir set and ExportType including events, Glaber may still create empty (or never written) problems-*.ndjson files, but it will not write problem/recovery records anymore.


How to switch export on / off

Configured in zabbix_server.conf (see conf/zabbix_server.conf.full).

ExportDir

  • Directory for real-time NDJSON export.
  • If unset (default): export is off for all types.
  • If set: export is enabled (subject to ExportType).
  • Directory must exist, be a directory, and be readable/writable by the server process. Startup fails otherwise (zbx_init_library_export()).

ExportType

  • Comma-separated list of types: events, history, trends.
  • Valid only if ExportDir is set.
  • Default when ExportDir is set and ExportType is omitted: all three (events,history,trends).
  • Events export is active when the type mask includes ZBX_FLAG_EXPTYPE_EVENTS (1), i.e. when events is listed (or all types are defaulted).

Examples:

# off
# ExportDir=

# export only trigger events/problems
ExportDir=/var/lib/zabbix/export
ExportType=events

# export events + history
ExportDir=/var/lib/zabbix/export
ExportType=events,history

ExportFileSize

  • Max size of a single export file before rotation.
  • Used only when ExportDir is set.
  • Range: 1M–1G, default 1G.

Architecture (old working path)

history values / trigger timers
        │
        ▼
history syncer (dbsyncer)
  zbx_sync_history_cache()          [dbcache.c]
        │
        ├─ evaluate triggers, create/recover events
        ├─ zbx_process_events()     → fills static `events` + `event_recovery`
        │
        └─ if events export enabled:
              zbx_export_events()   → builds JSON, writes NDJSON
              zbx_problems_export_write() / flush()
        │
        ▼
zbx_clean_events()

Key source locations

Piece Path
Config options src/zabbix_server/server.c (ExportDir, ExportType, ExportFileSize)
Export library src/libs/zbxexport/export.c, include/zbxexport.h
History syncer opens/closes problem files src/zabbix_server/dbsyncer/dbsyncer.c
Task manager also opens problem files src/zabbix_server/taskmanager/taskmanager.c (manual close-problem path in classic Zabbix)
Event → JSON export historically events.c → now commented in src/zabbix_server/glb_events.c as zbx_export_events()
Call after sync historically dbcache.c after successful processing; call commented out in Glaber

Processes that open problems-*.ndjson

When zbx_is_export_enabled(ZBX_FLAG_EXPTYPE_EVENTS) succeeds, each interested process registers a per-process export file via zbx_problems_export_init():

Process Typical file name
History syncer #N problems-history-syncer-N.ndjson
Task manager #N problems-task-manager-N.ndjson
Main process problems-main-process-0.ndjson

Full path pattern:

{ExportDir}/problems-{process_name}-{process_num}.ndjson

(process_type prefix for events is hard-coded as "problems" in zbx_problems_export_init().)

In classic Zabbix the history syncer was the primary writer: it exported events created while syncing history/triggers. The task manager opened the same export channel so manually closed problems (close-problem tasks) could emit recovery records through the same zbx_export_events() / write helpers.


File format and rotation

  • Format: newline-delimited JSON (NDJSON).
  • Extension: .ndjson.
  • Each write appends one JSON object and a trailing \n.
  • On write, if current_offset + record_size + 1 > ExportFileSize:
  • remove existing {file}.old if present;
  • close current file;
  • rename current file to {file}.old;
  • open a new file with the original name.
  • On I/O errors the record is dropped (not retried to the file); logging is rate-limited. Database persistence of the problem/event is independent of export success.

When a record was exported

Export consumed the in-memory buffers filled by zbx_process_events() / recovery correlation for the current sync batch.

Problem records

Emitted for each buffered event that matched all of:

  1. event->source == EVENT_SOURCE_TRIGGERS (trigger events only; not discovery / autoreg / internal / service, etc.);
  2. event->flags & ZBX_FLAGS_DB_EVENT_CREATE (newly created DB event in this batch);
  3. event->value == TRIGGER_VALUE_PROBLEM (1).

So: new trigger problem events only.

Recovery records

Emitted for each entry in the event_recovery hashset whose recovery event was a trigger event (recovery->r_event->source == EVENT_SOURCE_TRIGGERS in original Zabbix).

Recoveries come from normal trigger OK transitions, correlation closes, and (via task manager) manual problem close.

Not exported

  • Non-trigger event sources.
  • Problem events not marked as newly created in the batch.
  • Standalone OK events that are not recoveries linked in event_recovery.
  • History/trends (those use separate history-*.ndjson / trends-*.ndjson writers when enabled).

Export JSON structure

Protocol tags are defined in include/zbxjson.h (clock, ns, value, eventid, name, severity, hosts, groups, tags, tag, p_eventid).

Problem event (value = 1)

{
  "clock": 1710000000,
  "ns": 123456789,
  "value": 1,
  "eventid": 12345,
  "name": "High CPU utilization",
  "severity": 3,
  "hosts": [
    { "host": "web01", "name": "Web server 01" }
  ],
  "groups": [
    "Linux servers"
  ],
  "tags": [
    { "tag": "scope", "value": "performance" }
  ]
}
Field Type Meaning
clock number Unix time (seconds) when the problem was detected
ns number Nanoseconds to add to clock
value number Always 1 (TRIGGER_VALUE_PROBLEM)
eventid number Problem event ID
name string Problem / event name
severity number 0 Not classified … 5 Disaster
hosts array of objects Hosts involved in the trigger expression (host = technical name, name = visible name)
groups array of strings Distinct host group names of those hosts (loaded from DB at export time)
tags array of objects Problem tags (tag / value); may be empty

Recovery event (value = 0)

{
  "clock": 1710000300,
  "ns": 987654321,
  "value": 0,
  "eventid": 12346,
  "p_eventid": 12345
}
Field Type Meaning
clock number Unix time when the problem was resolved
ns number Nanoseconds to add to clock
value number Always 0 (TRIGGER_VALUE_OK)
eventid number Recovery event ID (recovery->r_event->eventid in original Zabbix)
p_eventid number Problem event ID being closed (recovery->eventid)

Recovery records intentionally omit name, severity, hosts, groups, and tags.


Original zbx_export_events() behaviour (summary)

Classic implementation (pre-Glaber rewrite of events):

  1. Skip if no buffered events.
  2. Iterate events: filter trigger + CREATE + PROBLEM; build problem JSON; zbx_problems_export_write().
  3. Iterate event_recovery: for trigger recoveries, build recovery JSON; write.
  4. zbx_problems_export_flush().

Later Zabbix 6.x variants also optionally fed the same JSON into connectors (streaming) when connector filters matched tags; file export remained gated by events_export_enabled. The Glaber commented copy still shows that dual path, but file writing is the subject of this document.

Bug note in the current commented Glaber copy

In glb_events.c the commented recovery block sets both eventid and p_eventid from recovery->eventid. That does not match original Zabbix (or the official protocol), where:

  • eventid = recovery event id;
  • p_eventid = problem event id.

Any revive of this code should restore the original mapping (and use the current recovery structure fields, e.g. recovery_event_id if r_event is no longer present).


Runtime enable check

zbx_is_export_enabled(ZBX_FLAG_EXPTYPE_EVENTS)

Returns SUCCEED only when:

  1. export library was initialized with a non-NULL ExportDir;
  2. ExportType includes events, or ExportType was unset (treated as all types).

Flags (include/zbxexport.h):

  • ZBX_FLAG_EXPTYPE_EVENTS = 1
  • ZBX_FLAG_EXPTYPE_HISTORY = 2
  • ZBX_FLAG_EXPTYPE_TRENDS = 4

Implications for a Glaber revive

To restore events export, at minimum:

  1. Re-implement serialization equivalent to zbx_export_events() against the problems keeper / current event model (not the old static events / event_recovery buffers alone).
  2. Call it wherever problems and recoveries are finalized (history/trigger path and manual close), not only from the commented dbcache.c site.
  3. Keep using zbx_problems_export_write() / flush() and the existing ExportDir / ExportType=events switch so file naming and rotation stay compatible with existing consumers.

History and trends export are separate writers (zbx_history_export_*, zbx_trends_export_*) and are outside the scope of this file unless they share the same ExportDir configuration.