Events

Events are the core signaling mechanism in NetXMS. Every significant state change, threshold violation, or system condition generates an event that flows through the Event Processing Policy (EPP) for evaluation. Understanding how events work — where they come from, what they carry, and how they flow through the system — is essential for effective monitoring, because every alarm, notification, and automated action in NetXMS ultimately traces back to an event.

Event Sources

NetXMS is an event-based monitoring system. Events originate from many parts of the platform, but they all arrive in the same event queue and are processed by the same rules engine. This uniformity is a deliberate design choice: regardless of whether a problem was detected by polling, reported by an agent, or signaled by an SNMP trap, the response mechanism is always the same EPP rule set.

The main event sources are:

Polling processes

The server continuously polls managed nodes for status, configuration, and topology changes. When a node stops responding, an interface goes down, or a network service fails its check, the poller generates an event. These are among the most common events in any NetXMS deployment — SYS_NODE_DOWN, SYS_IF_DOWN, SYS_SERVICE_DOWN, and their corresponding recovery events.

Threshold violations

When a collected metric crosses a configured threshold, the data collection engine generates SYS_THRESHOLD_REACHED. When the value returns to normal, it generates SYS_THRESHOLD_REARMED. Thresholds connect data collection to event processing — they translate numeric trends into actionable signals. See Thresholds for how to configure them.

SNMP traps

Network devices send unsolicited SNMP trap messages to report hardware failures, link state changes, authentication failures, and other conditions. NetXMS receives these traps and converts them into events based on configured trap-to-event mappings. See SNMP Traps for details.

Syslog messages

When NetXMS acts as a syslog receiver, incoming messages are evaluated against parsing rules. Matched messages generate events, allowing traditional syslog-based alerting to be unified with the rest of the monitoring pipeline.

Windows Event Log

The NetXMS agent on Windows can monitor the Windows Event Log and generate events when entries match configured parsing rules.

Agent-reported conditions

Agents running on monitored nodes can report conditions back to the server. This includes file monitoring alerts and log file parsing matches. (Agent tunnel state changes also produce events, but those are generated by the server’s tunnel handling, not reported by the agent.)

NXSL scripts

Scripts can generate events programmatically using the PostEvent() function. This is the extension point for custom monitoring logic — any condition that can be detected in a script can become an event.

External applications

The nxevent command-line tool and the NetXMS client library allow external applications and scripts to inject events directly into the server.

Internal server conditions

The server itself generates events for its own operational health: database query failures, certificate expiration warnings, LDAP synchronization problems, license issues, and similar conditions. These events allow NetXMS to monitor itself using the same mechanisms it uses for everything else.

All of these sources feed into a single event queue. By default a single event processor takes events from this queue and evaluates them against the EPP rules; when parallel processing is enabled (Events.Processor.PoolSize greater than 1), a master thread dispatches events into per-thread queues keyed by Events.Processor.QueueSelector.

Event Lifecycle

When an event is generated, it follows this path:

  1. Generation — Something in the system detects a condition and creates an event record. The record carries properties from multiple sources: the event template provides the code, default severity, and message template; the generating code supplies the source object and parameters. The timestamp is set automatically at generation; the generating code can additionally supply an origin timestamp (for example, the time a forwarded syslog message was originally produced). Tags can come from the event template, from the generating code (e.g., the PostEvent() or PostEventEx() functions), or both. Some of these properties (severity, tags) can be modified later by EPP actions during processing.

  2. Processing — The event enters the Event Processing Policy, where it is evaluated against rules in order. Each rule has a condition part (which events to match, from which sources, at what times, with what severity) and an action part (what to do when matched). An event can match multiple rules, and each matched rule executes its configured actions. EPP actions can modify event properties such as severity and message before the event is logged.

  3. Action execution — Matched rules execute their configured responses: creating or resolving alarms, sending notifications, executing scripts, updating persistent storage, or running server actions. Actions can be immediate or delayed with configurable timers.

  4. Logging — After processing, the event is written to the event log if its event template has the log flag enabled. The logged record reflects any modifications made by EPP actions during processing (such as severity or message changes). The event log provides an audit trail of logged events in the monitored environment. Events whose template has the log flag disabled will not appear in the log, regardless of whether any EPP rule matched them. (One built-in exception: SYS_DB_QUERY_FAILED is rate-limited to protect the log — at most 30 occurrences per minute are written even with the flag set.)

  5. Retention — For events that were logged, the event record remains in the event log for the configured retention period, then is purged by the housekeeping process.

Events and alarms are distinct: an event is a record of something that happened; an alarm is an ongoing state requiring attention. See Alarms for how alarms are created and managed.

Event Templates

Every event type in NetXMS is defined by an event template. The template is not the event itself — it is the blueprint that defines how events of that type behave.

An event template defines:

Event code and name

The code is a unique numeric identifier; the name is a human-readable symbolic name like SYS_NODE_DOWN or CUSTOM_BACKUP_FAILED. Built-in events have codes below 100000. Custom events use codes 100000 and above.

Default severity

The severity assigned to events generated from this template. The EPP can override severity for specific rules, but the template sets the baseline. NetXMS uses five severity levels: Normal, Warning, Minor, Major, and Critical.

Message template

A text string with macro placeholders that is expanded when an event is generated. Macros like %1 through %99 reference positional parameters passed at event generation time, while %<name> references named parameters. The expanded message becomes the event’s human-readable description — what operators see in the event log and alarm browser.

Tags

Optional labels attached to events for filtering and categorization in EPP rules. Tags provide a flexible way to group related events across different event types without relying solely on event codes.

Description

Free-form text documenting the event’s purpose and parameters. The description is shown in the event template editor and in event selection dialogs; it is not part of generated events.

Options

Two flags control event visibility: Write to log determines whether generated events are written to the event log, and Hide from event monitor excludes generated events from the real-time event monitor view.

The template system means that event types are data, not code. You can create new event types, modify message templates, and adjust default severities without restarting the server or writing any code. See How to Create Custom Events for the procedures, and Event Types Reference for the complete list of built-in event templates and their properties.

Further Reading