Skip to content

Writing Rules (Detections & Case Rules)

Detections and Case Rules are written in the same compact rule language. A Detection turns a log or telemetry pattern into an event. A Case Rule watches the stream of events and groups correlated noise (flaps, storms) into a single Case. This page is the reference for both.

The editor’s Test button validates a rule and shows what it compiled to — use it as you write.

rule my_rule {
meta: # settings (key = value)
events: # what to match ($e.field op value)
match: # OPTIONAL: group key + time window
condition: # OPTIONAL: how many matches before it fires
close: # OPTIONAL (Detections): close earlier events on recovery
}
Key Values Meaning
type detection (default) · case case makes it a Case Rule
source log (default) · telemetry Detections: which stream to watch
severity critical high medium low info (or 1–5) major is accepted for high, minor for medium, and warning for low
description text shown in the UI
tag text the event’s Tag (defaults to the rule name)
status open (default) · closed closed = a recovery/audit record
window e.g. 5m default window when there’s no match:
autoclose e.g. 3h Case Rules: close the case after this much quiet

Time units: s m h d — e.g. 30s, 15m, 3h. Operators: = != > < >= <= contains. Group placeholders: $e.field = $x binds field as a group key you then use in match:.


sourcetype, source, host, severity_id, facility, sender_ip, class_uid, category_uid, activity_id, type_uid, src_endpoint_ip, src_endpoint_hostname, src_endpoint_port, actor_user_name, dst_endpoint_ip, dst_endpoint_hostname, protocol_name, action_id, status_id, device_id, collector_id, site_id, transport, subsystem, category, process, tag, signature — plus _raw (use only with contains) and fields.<name> for any field you’ve extracted.

class_uid/category_uid/activity_id/type_uid together classify what kind of event it is (for example, class_uid = 3002 + activity_id = 1 is an authentication logon). status_id is the outcome: 1 = success, 2 = failure, 99 = other. severity_id is the log’s own reported severity, on a 0 (unknown) to 6 (fatal) scale where a higher number is more severe — this is separate from the meta.severity you set for the event the rule raises.

kind (reachability or metric), alive ("true"/"false"), via, rtt, metric, value, if_index, if_name, units, device_id.

No match: means it fires on every match.

rule root_ssh_login {
meta:
severity = "high"
description = "Direct SSH login as root"
events:
$e.class_uid = 3002 # Authentication
$e.activity_id = 1 # Logon
$e.status_id = 1 # Success
$e.actor_user_name = "root"
}

Example 2 — a windowed count (brute force)

Section titled “Example 2 — a windowed count (brute force)”

Group by source IP, count failures in a window. This is the built-in SSH brute force detection GridNMS ships with.

rule ssh_brute_force {
meta:
severity = "high"
description = "10+ failed logins from one source IP within 5 minutes"
events:
$e.class_uid = 3002 # Authentication
$e.activity_id = 1 # Logon
$e.status_id = 2 # Failure
$e.src_endpoint_ip != ""
$e.src_endpoint_ip = $ip
$e.host = $host
match:
$ip, $host over 5m
condition:
#e >= 10
}

This is what the interface Thresholds panel generates for you.

rule eth0_in_high {
meta:
source = "telemetry"
severity = "minor"
tag = "THRESHOLD:eth0:in_bps"
events:
$e.kind = "metric"
$e.device_id = 4
$e.if_index = 12 # or: $e.if_name = "eth0"
$e.metric = "in_bps"
$e.value > 100000
}

A recovery rule fires its own event when the condition clears, marked as the recovery for the matching breach — events themselves are permanent records, never edited or deleted, so this raises a paired recovery event rather than changing the original. This is what the Auto-clear checkbox builds for you automatically.

rule eth0_in_high_clear {
meta:
source = "telemetry"
status = "closed"
events:
$e.kind = "metric"
$e.device_id = 4
$e.if_index = 12
$e.metric = "in_bps"
$e.value <= 100000
close:
tag = "THRESHOLD:eth0:in_bps"
}

close: also accepts a pattern: tag matches "IF-DOWN:%".


Beyond “how many” — the other things condition: can assert

Section titled “Beyond “how many” — the other things condition: can assert”

Every example so far counts matches and fires when there are enough of them. condition: can assert four other shapes, which between them cover the questions a count can’t answer — nothing arrived, too large a share of traffic looks like this, this is unlike its own history, and we are consuming an error budget too fast.

Write this in condition: It fires when Use it for
#e >= N · #e > N at least N matches in the window (the default) a burst — failed logins, repeated errors
#e <= N · #e < N at most N matches in the window traffic falling below an expected floor
#e == 0 nothing matched in the window a dead man’s switch — a heartbeat that stopped, a device that went quiet
ratio($e.field = value) >= 0.5 the matching share of the window breaches a budget (a fraction from 0 to 1) “more than half this host’s logs are one repeated line”
deviation() > 3 the window’s average is more than N standard deviations from its own trailing baseline an anomaly, with no threshold to pick by hand
burnRate($e.status_id = 1) a fast and a slow window both burn the error budget too quickly SLO alerting that ignores brief blips

Two things to know before reaching for these:

  • They apply to scheduled log-stream detections — the default, source = "log". A source = "telemetry" rule is evaluated per-reading as each one arrives, and a Case Rule counts events, so both of those use #e >= N. GridNMS tells you so rather than quietly ignoring the condition.
  • #e == 0 needs a match: group to be useful. Without one it asks “did anything at all match”, which is rarely what you mean; with one it asks the far more useful “which of the things I expect to hear from has gone silent”.

By default a rule runs over your logs. domain points the same grammar at metrics or containers instead:

domain Runs over Conditions allowed
log (default) collected logs all of the above
metric metric samples from monitored devices #e <= N, #e == 0, deviation() > N
container container samples #e <= N, #e == 0
host host metrics from machines running a log forwarder (CPU, memory, disk, network) #e <= N, #e == 0, deviation() > N

Host metrics are kept apart from device metrics, so a metric rule that names one of them (system.cpu.utilization, process.cpu.time, …) is refused when you save it, with a pointer to host. In a host rule, $e.host is the machine’s name — gridnms-tier2 finds the machine whether it reports a short or a fully qualified name — and $e.device_id is the managed device the forwarder is linked to, which is what attaches the resulting event to that device.

A host rule that uses deviation() works on a fixed set of six host metrics: system.cpu.utilization, system.memory.utilization, system.memory.usage, and the 1, 5 and 15 minute load averages (system.cpu.load_average.1m, .5m, .15m). Name one of them in the rule ($e.metric = "system.cpu.utilization"). A rule that names any other metric, or no metric at all, is refused when you save it.

The non-log domains deliberately answer only absence and deviation questions (container rules: absence only). A metric threshold — “fire when CPU goes above 90” — is a telemetry rule instead, evaluated the moment the reading arrives rather than on a schedule; that’s Example 3 above, and it’s what the Thresholds panels build for you.

Example 5 — a metric series that went silent

Section titled “Example 5 — a metric series that went silent”

Fires once per device-and-metric pair that reported nothing for 15 minutes. This is the built-in Metric series silent detection.

rule metric_series_silent {
meta:
domain = "metric"
severity = "major"
tag = "METRIC_SILENT"
window = "15m"
events:
$e.device_id = $dev
$e.metric = $m
match:
$dev, $m over 15m
condition:
#e == 0
}

Example 5b — a host that stopped reporting its CPU

Section titled “Example 5b — a host that stopped reporting its CPU”

Fires once per host that was reporting its CPU and has gone quiet for 15 minutes. Use host (not metric) for anything a log forwarder collects from its machine.

rule host_cpu_silent {
meta:
domain = "host"
severity = "major"
window = "15m"
events:
$e.host = $host
$e.metric = "system.cpu.utilization"
match:
$host over 15m
condition:
#e == 0
}

Example 6 — one log line drowning out a host

Section titled “Example 6 — one log line drowning out a host”

Fires when a single signature accounts for half or more of a host’s log volume over 30 minutes — the shape of a stuck loop or a newly-chatty component. This is the built-in Dominant log signature detection.

rule log_signature_dominance {
meta:
severity = "warning"
tag = "LOG_SIGNATURE_DOMINANT"
window = "30m"
events:
$e.host = $host
match:
$host over 30m
condition:
ratio($e.signature = "request") >= 0.5
}

Example 7 — an anomaly with no threshold to pick

Section titled “Example 7 — an anomaly with no threshold to pick”

Fires when a metric’s 15-minute average strays more than three standard deviations from its own recent history — useful where “normal” differs per device and no single number would suit them all. This is the built-in Metric baseline deviation detection.

rule metric_baseline_deviation {
meta:
domain = "metric"
severity = "major"
tag = "METRIC_ANOMALY"
window = "15m"
events:
$e.device_id = $dev
$e.metric = $m
match:
$dev, $m over 15m
condition:
deviation() > 3
}

Example 8 — burning an error budget too fast

Section titled “Example 8 — burning an error budget too fast”

burnRate() takes the predicate that defines a good event and compares two windows at once: it fires only when a short window and a long window are both burning the budget faster than allowed, so a brief blip doesn’t page anyone while a sustained problem does. Because it needs more than one number, its settings live in meta:.

rule slo_error_budget_burn_rate {
meta:
severity = "major"
tag = "SLO_BURN_RATE"
slo_objective = "0.999" # the availability you're promising
slo_fast_window = "5m" # short window...
slo_fast_burn = "14.4" # ...and how fast it may burn
slo_slow_window = "1h" # long window...
slo_slow_burn = "14.4" # ...and its own limit
events:
$e.host = $host
match:
$host over 5m
condition:
burnRate($e.status_id = 1) # status_id 1 = success, i.e. "good"
}

slo_objective is a fraction below 1 (0.999 is three nines). The burn multipliers are how much faster than budget is too fast — 14.4 is the widely-used value for a fast window, and means “at this rate the whole month’s budget is gone in about two days”.


A Case Rule runs over the events stream. events: selects which events to watch, match: is the group key + window, and condition: is the count threshold. When a group trips, GridNMS opens one Case, attaches the events, sends a single notification, and suppresses the per-event alerts.

Author them under Configure → Logs and Events → Case Rules with New Case Rule.

detection (the rule that produced the event), device_id, device_class, tag, severity, source, collector_id, message, component_id, signature.

component_id is set when the event came from a service monitor rather than a device, so a check with no device of its own still groups on its own subject. signature is the message with its variable parts normalised away — grouping on it keeps two different problems on one device in two different cases.

The same signal recurring on the same device or component.

rule flapping_signal {
meta:
type = "case"
title = "Flapping signal"
severity = "minor"
autoclose = "3h"
description = "The same signal firing repeatedly on the same device or component"
events:
$e.source = "detector"
$e.severity <= 4
$e.detection = $det
$e.device_id = $dev
$e.component_id = $comp
$e.signature = $sig
match:
$det, $dev, $comp, $sig over 15m
condition:
#e >= 2
}

The group key is deliberately narrow: the same detection, on the same device or component, reporting the same message. A second, unrelated problem on a flapping device opens its own case and still reaches you.

A device that keeps going down and coming back up is grouped in full: once its flapping case is open, each “recovered” notice that closes one of those short outages joins the same case instead of sending its own message. A recovery after an outage that lasted longer than the rule’s window still notifies you, and so does a device that goes down once and comes back — the case only absorbs recoveries that belong to the repeat. When the device settles and the case closes, you get one closing notice.

This pairing applies only to a rule that waits for a repeat (#e >= 2, as above). A rule you write with #e >= 1 opens its case on the very first event, which says nothing about whether the signal is flapping — so its recoveries keep notifying one by one. If you want the quiet down/up behaviour, ask for a repeat.

E.g. a switch reboot dumping many interface-down events.

rule device_event_storm {
meta:
type = "case"
title = "Event storm on a device"
severity = "major"
autoclose = "1h"
events:
$e.device_id = $dev
match:
$dev over 5m
condition:
#e >= 15
}

Case Rules evaluate like firewall rules: the highest-priority matching rule wins an event, and an event belongs to exactly one rule’s case. Each rule’s priority is derived automatically from how specific it is (a rule that names a detection outranks a broad catch-all, and more group-by fields and filters add weight), or you can set an explicit Priority (0–32000) on the rule’s edit sheet to pin the order. When a higher-priority rule opens a case, it also claims matching recent events out of any lower-priority rule’s case, so the outcome is the same no matter which rule fired first. Cases you open by hand are never touched — no rule can pull events out of them. Rules with equal priority split events the same deterministic way every time.

Streaming and telemetry detections work the same way. When a log line or a device reading matches more than one streaming/telemetry detection, only the highest-priority one fires — it raises a single event instead of one per matching rule. Leave Priority blank to have it derived from how specific the detection is, or set an explicit value (0–32000) to pin the order. Recovery (“auto-clear”) always tracks its own detection, so turning a detection’s priority up never leaves a “device down” event stuck open. Scheduled (timer-based) log detections are unaffected — each still runs on its own and raises its own events.

Example 3 — own a specific detection’s cases

Section titled “Example 3 — own a specific detection’s cases”

Naming a detection makes this rule responsible for its cases (and turns off that detection’s own “Open a Case on match”).

rule ssh_bruteforce_cases {
meta:
type = "case"
title = "SSH brute-force incidents"
autoclose = "6h"
events:
$e.detection = "ssh_brute_force"
$e.device_id = $dev
match:
$dev over 30m
condition:
#e >= 1
}

  • The first match still alerts you — Case grouping only kicks in once the threshold trips, so you never miss the initial signal.
  • Notifications are turned on per detection (the Notify section). A Case sends its single alert to the producing detection’s recipients.
  • Auto-clear vs Case Rules: auto-clear closes one event when it recovers; a Case Rule groups a pattern of events into an incident. They complement each other.
  • Severity words map to numbers: critical = 1, high/major = 2, medium/minor = 3, low/warning = 4, info = 5. Anything unrecognised becomes medium.

docs built 2026-11-12 · 945a2dec2