Alert rules

The Neens detectors find anomalies and regressions automatically, but sometimes you know exactly what you want to watch: “page me when the toxicity pass-rate drops below 90%” or “tell me when the error rate goes over 5%.” Alert rules let you say that directly — a metric, a threshold, and a window — and route the result through the same notification sinks as insights.

At a glance

Anatomy of a rule

Every rule is four choices plus a couple of options:

The rule fires when metric <comparator> threshold. An empty or idle window (no data) is never a breach — an alert fires on real signal, not on the absence of it.

Creating a rule

Create one with POST /alerts:

curl -X POST https://your-neens/api/alerts \
  -H "Authorization: Bearer $NEENS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Toxicity pass-rate floor",
    "measureKey": "eval_pass_rate",
    "metricKey": "toxicity",
    "comparator": "lt",
    "threshold": 0.9,
    "window": "24h",
    "severity": "high"
  }'

GET /alerts/catalogue returns the alertable measures, comparators, windows, and severities the rule-builder offers, so a UI never has to hardcode them.

Test before you trust it

POST /alerts/{id}/test evaluates the rule right now and reports the current value and whether it would breach — without recording anything, notifying anyone, or touching the rule’s state. Use it to sanity-check a threshold against live data.

{ "value": 0.83, "display": "83%", "breached": true, "comparator": "lt", "threshold": 0.9, "window": "24h" }

Trend alerts — page me when a KPI slips

A threshold rule compares a number to a fixed line. Sometimes what you care about is the direction of travel: not “is containment below 85%?” but “has containment fallen from where it was last week?”. A KPI trend rule watches a Business KPI’s own recent history and fires when it has regressed by at least a percentage you set, over a window you set.

A trend rule references a KPI (not a raw measure), because a trend needs the KPI’s recorded daily history and its declared direction — so a drop in containment and a rise in cost per case are both “regressed”, each oriented correctly.

curl -X POST https://your-neens/api/alerts \
  -H "Authorization: Bearer $NEENS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Containment is slipping",
    "ruleType": "kpi_trend",
    "config": { "kpiId": "a68e0cbb059f4b0ba38f409ee2145b19",
                "lookbackDays": 7, "minDeltaPct": 5 },
    "severity": "high"
  }'

What happens on a breach

When the periodic evaluator finds a rule breaching, it:

1. Records an alert in the Insights store (type alert, in the Observe feed) — so it appears in-app alongside detector insights, with the same lifecycle and feedback.
2. Dispatches it to the sinks — the in-app feed always, plus Slack (for high-severity rules) and any webhook whose tags match. This is the exact notification-sink plumbing insights use; no new configuration is needed.
3. Respects the cooldown — while the metric stays breached, the rule won’t re-notify until its cooldown elapses, so a persistent problem doesn’t spam you.

When the metric recovers (stops breaching), the rule’s open alert is automatically resolved and drops out of the feed — mirroring how detector insights self-resolve.

Each rule keeps a short history (GET /alerts/{id}/events) of its breaches and recoveries, and its last evaluated value and state on the rule itself.

Troubleshooting