The Event System
Every signal GridNMS collects — a device going down, a syslog message, an SNMP trap, a threshold breach — becomes an event. This page describes the event lifecycle: collection, the transformation rules engine, the two-tier store, and notification delivery.
Where events come from
Section titled “Where events come from”Events originate in one of four collector services:
| Source | What it does |
|---|---|
| monitor | Pings every monitored device via ICMP. Raises PING_DOWN (critical) when a device goes unreachable and PING_UP (info) when it returns, which clears the open down event. |
| poller | Runs pack collectors on a per-device interval, records metrics, and raises/clears events when an interface bandwidth threshold is crossed. |
| syslog | Receives RFC 3164 / RFC 5424 UDP syslog on 514/udp. |
| snmptrap | Receives SNMP v1/v2c/v3 traps and informs on 162/udp. |
Syslog and SNMP-trap packets are written to a durable per-collector queue the instant they arrive, then processed in batches — so no messages are dropped during bursts or while the database is busy.
Severity mapping
Section titled “Severity mapping”All severities across the system use a single 5-level scale (see the severity reference). Incoming syslog priorities and SNMP trap types are mapped onto it:
Syslog priority → GridNMS severity
| Syslog priority | GridNMS severity |
|---|---|
| 0 Emergency, 1 Alert, 2 Critical | 1 Critical |
| 3 Error | 2 Error |
| 4 Warning | 3 Warning |
| 5 Notice, 6 Informational | 4 Info |
| 7 Debug | 5 Debug |
SNMPv1 generic trap → tag / severity
| Generic | Tag | Severity |
|---|---|---|
| 0 coldStart | SNMP_COLD_START | 2 Error |
| 1 warmStart | SNMP_WARM_START | 3 Warning |
| 2 linkDown | SNMP_LINK_DOWN | 1 Critical |
| 3 linkUp | SNMP_LINK_UP | 4 Info |
| 4 authFailure | SNMP_AUTH_FAIL | 2 Error |
| 5 egpNeighborLoss | SNMP_EGP_LOSS | 3 Warning |
| 6 enterpriseSpecific | SNMP_TRAP | 3 Warning |
SNMPv2c/v3 traps derive a SNMP_TRAP_<oid> tag with a default Warning severity,
which transformations can override.
Dual timestamps
Section titled “Dual timestamps”Syslog and trap events carry two timestamps: the event time parsed from the message itself (so the original device time is preserved even when delivery is delayed) and the receive time recorded when the collector got the packet. Both are kept in the cold archive.
Vendor parsers and transformations
Section titled “Vendor parsers and transformations”Before an event is stored, it passes through two enrichment stages:
-
Vendor parser chain (syslog only) — vendor-specific formats are normalised into meaningful tags and severities. For example, Palo Alto PAN-OS CSV logs become
PAN_TRAFFIC,PAN_THREAT,PAN_SYSTEM, and so on. -
Transformation rules engine — admin-defined rules match on a message regex, tag, device, class, or severity and apply an action:
Action Effect setTag Replace the event’s tag setSeverity Override the severity suppress Drop the event entirely (nothing is stored) closeExisting Auto-close matching open events
Rules are evaluated in order; the first matching suppress drops the event.
The two-tier store
Section titled “The two-tier store”Once enriched, an event is written to the hot store (PostgreSQL Events) and
is immediately visible in the UI. Syslog and trap events are simultaneously
written to the cold archive (a fire-and-forget dual write), so full history
is available in Event History right away.
- Hot store — recent, active, and recently-cleared events only, within a configurable retention window (default 30 days). Kept small for UI speed.
- Cold archive — long-term history in daily SQLite files (default) or ClickHouse. An hourly scheduler ages old events out of the hot store.
Key event fields:
| Field | Meaning |
|---|---|
Severity | 1 Critical … 5 Debug |
Tag | Short machine-readable event tag (e.g. PING_DOWN) |
Source | Originating service: monitor, poller, syslog, snmptrap |
Status | 0 open · 1 acknowledged · 2 closed |
Count | Times the event has fired without clearing |
FirstSeen / LastSeen | First and most-recent occurrence |
Subscriptions and notifications
Section titled “Subscriptions and notifications”After an event is written, it’s matched against per-user subscriptions. Subscriptions filter by device, class, tag, severity threshold, and message regex. A match queues a notification, and a worker delivers it:
| Channel | Transport |
|---|---|
| SMTP | |
| Webhook | HTTP POST (JSON, custom headers supported) |
| Slack | Incoming webhook |
| PagerDuty | Events API v2 |
Failed deliveries are retried up to three times before being marked failed.
Searching history
Section titled “Searching history”Event History is queried from the cold archive with filters for device, time range, severity, source, and full-text search on the message and tag — with a time-bucketed severity histogram for the selected range.