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).

Threshold-free (baseline) monitors

Instead of a fixed value, a monitor can be of kind baseline: it learns what is normal for the column from its own recent history and triggers when a new value is an outlier. Pick Baseline instead of Threshold when creating the monitor; the operator and value are not used.

Learning: until the monitor has recorded 7 observations it only collects data and stays ok; the monitor shows its learning progress.
Statistics: each check compares the new value with the median of the last 30 observations using a robust z-score (median absolute deviation). A change of less than 2% of the median is never flagged. There is no seasonality model, so a strong weekly pattern can produce false positives.
Sensitivity: low, medium (default), or high, which trigger at a z-score of 5, 3.5, or 2.5.
No AI in the check: baseline evaluation is plain statistics. It makes no call to an AI provider and needs no provider key.

In the API, set options.kind to "baseline" (and optionally options.sensitivity) in place of op and value.

Why did this fire?

Every alert notification carries a short, deterministic statistics line describing what changed (for example, the new value against the recent median). It is computed from the monitor’s recorded observations and needs no AI.

If your organization has an AI provider configured, an AI analysis is added to the alert. The model proposes up to three read-only queries (it is asked to aggregate, for example counts or sums per segment or time bucket, but that is not guaranteed), arcodash runs them on the monitor’s data source, and the model writes a one or two sentence narrative with a confidence level (low, medium, or high). The whole investigation has a 20 second budget: if it takes longer or fails, the alert goes out immediately with the statistics line alone. The narrative appears in the notification on every destination type and on the incident card.

An investigation needs a data source with an AI profile, and it sends the investigation query results (the model is asked to aggregate them) to your provider. Admins control it with Explain alerts with AI in AI Settings, which requires Include sample values in AI prompts to be on. See Data handling & privacy for exactly what is sent.

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 and chat destinations (Slack, Teams and the like) 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 as a label: `Alerting`, `OK`, `Can't evaluate`, or `Not checked yet`.

For example, a custom subject of [{{state}}] {{name}} renders as [Alerting] Signup drop. Leave either field blank to use the default subject/body.

In chat messages the custom subject replaces the card title and the custom body replaces the lead line under it. The Observed and Condition fields and the footer stay as they are. Generic webhook, PagerDuty, and Datadog destinations ignore custom text and send a fixed payload.

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.