Alerts overview

An alert (called a monitor in the API and throughout this site) is a threshold check against one column of a saved query’s result. Every time the query’s data refreshes, arcodash re-checks the condition and, if the outcome changed since last time, notifies whoever’s subscribed.

The condition

A monitor’s condition has three parts, set when you create it:

• Column — which column of the query’s result to read.
• Operator — >, <, >=, <=, ==, or !=.
• Value — the threshold to compare against.

Each check reads the first row of the query’s most recent result, pulls the named column’s value out of it, and compares it against the threshold with the chosen operator. If the comparison is true, the monitor is triggered; if it’s false, it’s ok.

[!NOTE] A monitor always evaluates the query’s published result — the same published/draft split queries have everywhere else. It also always reads row one specifically; if your query can return more or fewer rows depending on the data, write it so the row that matters is always first (e.g. ORDER BY plus a tight WHERE/LIMIT 1).

Monitor state

A monitor is always in one of three states:

• unknown — no result to evaluate yet, the result has no rows, the named column is missing from the first row, or the column’s value isn’t numeric. This is also the starting state for a brand-new monitor.
• ok — the condition evaluated false on the most recent check.
• triggered — the condition evaluated true on the most recent check.

Notifications only fire on a state change — going from ok to triggered, or back again — never on every check that leaves the state unchanged. Going from ok or unknown into triggered starts a fresh incident: any earlier acknowledgment is cleared, and escalation restarts from its first step. See Managing monitor incidents for what happens once a monitor is triggered.

Custom subject and body (email only)

A monitor’s Email destination can override the default subject and body text. Both fields accept two placeholders, substituted literally when a notification is sent:

Token	Substituted with
{{name}}	The monitor’s name.
{{state}}	The new state (ok, triggered, or unknown).

For example, a custom subject of [{{state}}] {{name}} renders as [triggered] Signup drop. Leave either field blank to use the default subject/body. This substitution is email-specific — Slack, webhook, and the other destination types don’t have a custom-message field; they render a fixed, non-editable payload for every state change.

Rearm: throttling repeat notifications

If a monitor keeps flipping in and out of triggered in quick succession, that’s noisy without adding information. Set a rearm period (in seconds): once a monitor triggers, a repeat trigger within that many seconds of the last one still updates the state, but skips sending another notification. Once the rearm window has passed, the next trigger notifies normally again. Leave rearm unset (or 0) to notify on every single triggered transition, with no throttling.

[!IMPORTANT] Notifications only ever fire on a state change (see above) — a monitor that stays triggered continuously, without ever clearing back to ok first, never re-notifies at all, rearm or no rearm. Rearm only throttles the case where a monitor is flapping ok→triggered→ok→triggered; it doesn’t make a persistently-triggered monitor remind you periodically. If you need a recurring nudge for an incident nobody’s acknowledged, that’s what escalation is for.

Where to go next

• Notification destinations — where a triggered alert actually gets sent.
• Managing monitor incidents — mute, snooze, acknowledge, and delivery history.
• Escalation — notifying a second destination if a triggered monitor stays unacknowledged.
• Data observability monitors — the freshness/row-count/ null-rate/duplicate checks, which are the same threshold-on-a-query-result mechanism aimed at a handful of common data-health questions.
• Core concepts — where a monitor fits among the rest of arcodash’s vocabulary.