Skip to main content
Alerts have a full editor in the web app, so you can shape a scope against real data before arming it. Everything here maps one-to-one onto defineAlert, so an alert built in the UI can be moved into code later (and vice versa).

​
The alert list

Open Alerts from your workspace sidebar. Each row shows the alert’s schedule, whether it is enabled, its latest evaluation outcome, and who last changed it.
  • New alert creates an Untitled alert — checked hourly, watching every span, breaching at a 10% error rate — and opens it. It starts disabled, so nothing fires until you arm it.
  • New folder groups alerts, the same folders used elsewhere in the workspace. Creating an alert inside a folder files it there.
  • Right-click a row (or use its ⋯ menu) to Edit its name, description, and folder, Duplicate it, Move to another folder, or Remove it.
Duplicating is the quickest way to fan one alert out across workflows: the copy keeps the original’s scope, threshold, schedule, and actions, and starts disabled so it can’t fire before you have retargeted it.

​
Configure the trigger

Open an alert and stay on the Trigger tab. The toggle in the header arms and disarms it, and the name is editable in place. The data sources are listed under the store they read from: Orchestration (spans, runs, records and SQL) covers what your plays, tools and agents ran, Storage (a model and SQL) covers the data in your models and warehouse. Picking one shows its description underneath. The Scope section switches on the source you land on:
  • Spans gives you the same filter bar as the Spans view — workflow or triggering agent, node kind, integration, connector, action, tool, agent, execution status, free-text search — with a live table of the spans currently matching underneath. That table is the fastest way to tell an over-broad scope from an over-narrow one.
  • Runs gives you the run list’s filter bar (play or tool, statuses, release, user, free-text search) with a live table of the matching runs: title and status, credits, the play or tool the run belongs to, and when it was created and finished. On “All triggers” the table spans every play and tool, so the workflow column tells you where each run came from. Ad-hoc runs, the ones agents spawn outside a play or a tool, never appear, because the alert never counts them.
  • Records gives you the same bar and the same table over records instead of runs: the same work counted once per record, in its latest state, so a record re-run into success stops counting as failed. Its status menu has no idle or skipped, which a record can never be.
  • Orchestration SQL and Storage SQL give you a SQL editor with a preview that runs the query and shows the value it returns, so you can confirm it yields a single number before saving. The orchestration schema lists the columns of the first; the second runs against your warehouse, where models are referenced as <dataset>.<model>. Remember that a query scope windows itself, or doesn’t.
  • Model pairs a model picker with the usual filter builder, and shows the model’s records under it, filtered exactly as the alert measures them, so the rows you see are the ones being counted.
Under the table sits the preview, which answers the question the table can’t: whether this alert would fire right now, and on what value. It re-evaluates with the table as you change filters, so scope and verdict always describe the same thing. The SQL sources run it from the Preview button in their editor instead, since a half-typed query is not worth running. Windowed sources (spans, runs, records) are read over the last hour, whatever cron you end up setting. A preview that says nothing matched is an answer too: an empty window is never a breach, except for count with below-or-equal. Below the scope, set the threshold (metric, aggregation, operator, value), the schedule cron, and the actions to fire on breach. Actions accept a connector action, a tool, or an agent, and their inputs can interpolate the firing’s values — {{alert.url}}, {{event.value}}, {{event.spansUrl}} and the rest.
A spans, runs or records alert’s window starts where its last evaluation ended, not at a fixed lookback, so the cron is effectively the window size. Widening the cron from @every 5m to @every 1h makes each evaluation judge an hour, which changes what a percentage or a percentile actually means. SQL and model scopes are not windowed for you, so there the cron is only how often the question gets asked.

​
Read the history

The Events tab lists every evaluation, newest first, with its status, the value computed, and the window judged. Filter by status to find just the firings, and expand one to see the runs its actions spawned. See Events for what each status means.

​
Best practices

  • Preview before arming — shape the scope against the live table, watch the preview under it for the value your threshold would judge, and leave the alert disabled until the numbers look right.
  • Match the cron to the signal — short windows catch spikes but are noisier; long windows smooth them out and fire later.
  • Watch silence, not just errors — a count / lte alert catches a workflow that stopped running, which no error-rate alert can.
  • Make the action say what happened — interpolate {{event.value}} and {{event.spansUrl}} so whoever reads the Slack message doesn’t have to go hunting.

​
Next steps

Define alerts in code

The defineAlert reference — scopes, metrics, actions, and the evaluation window.

Read the events

Statuses, snapshots, and the runs a firing spawned.

Monitor from the CLI

Runs, batches, spans, and traces from the terminal.

Play health

Batch-health thresholds and alert actions on a play.