Configure alerts
Turn an event into a metric, then raise a metric-threshold alert that files its own ticket when the metric crosses the line.
An alert rule watches one metric and raises an alert when its value breaches a condition —
"checkout errors > 50", "active users < 100". The window it looks at is cut into buckets and
each bucket is judged on its own: a rule fires when enough of them breach, not when the window
averages out past a line. When it fires, Shipeasy files a ticket into the same queue as your bugs and
error reports, so the thing you need to look at shows up where you already triage.
Alerts are evaluated server-side every 10 minutes — there's no SDK call and nothing to poll. You only define the rule.
Create a rule in the dashboard
Open Alerts in the sidebar and click New alert rule. Everything below is one sheet:
Name it
A label for the rule, shown on the rule and on every alert it raises.Pick the metric and the condition
Choose the metric, then the kind of condition. Threshold crosses a number you set (greater
than, at or above, less than, at or below). Range leaves a band it should stay inside.
Anomaly departs from the metric's own usual level for that hour of the week. Outliers
watches for one group running away from the others, and needs a metric grouped with by (…).
No data fires when the metric stops reporting altogether — a count of zero is a reading, not
silence.
Choose the window and its buckets
Over 24h is the default; presets run from 1h to 7d, or pick custom hours. The window is cut into 6 to 12 buckets — by default twelve equal ones (Even split), or pick a bucket width such as 5 minutes or 1 hour. Must breach says how many buckets have to be past the line: all must breach (every bucket that had data) or N of M.
Set severity, then who hears about it
Severity is Critical, Warning or Info — danger, warn and info in the CLI and API (--severity danger is Critical, --severity warn is Warning). Notify lists where a fired alert goes —
In-app (Home and the bell) is on by default, and you can add a Slack channel and an email
address.
Create the rule
Click Create alert rule. It is enabled straight away unless you switch it off.
Under Tuning a rule has optional extras: a Warn at level that speaks up before the rule pages, a Clears at level the metric must reach before the alert closes, One alert per group for grouped metrics, a Delay for data that lands in batches, and Auto-resolve.
Create a rule in the dashboard
Go to Alerts → New alert rule. In Manual mode you pick the metric, the
comparator and the threshold; the lookback window (24h by default) is split
into buckets — 6 to 12 of them, at a width we support — and each bucket is
judged on its own. You choose how many buckets must breach before the rule
fires, and whether a fired alert resolves itself when the metric comes back
inside the threshold or is set to Never auto-resolve. The dashboard labels
the middle severity Warning (warn on the CLI and API). (You can also describe the rule to the
assistant and let it draft the card for you.) The API and CLI shape below is
the same rule expressed as fields.
What an alert chart shows
Every rule renders as a 14-day chart of its metric with the alert story drawn on top. Three things it surfaces — each a different facet of how a rule reads its metric:
It shades every breach
The dashed line is the threshold; wherever the metric crosses to the breaching side, that stretch is shaded in the rule's severity colour and the marker shows the moment it fired. One band = one alert ticket.
It judges the window in buckets
A rule never fires on a single reading. It cuts its window into buckets and asks each one whether it breached; it fires once enough of them did (all of them, unless you set N of M). A brief blip punches over the line in one bucket and never pages; a sustained move breaches many. The bright line here is a trailing average drawn only to make the shape easy to read — the rule itself keeps the buckets apart. Widen the window to need a longer stretch, narrow it to catch faster.
It can guard a floor, not just a ceiling
Flip the comparator to < (or <=) and the rule watches a floor — it fires when the metric
falls below the line. Useful for "signups per hour", "active sessions", or any health number that's
bad when it drops.
The event → metric → alert chain
An alert rule doesn't read raw events; it reads a metric. So a working alert is a three-link chain:
1 · Event→
A fact your app emits — checkout_error, page_view. Captured through the SDK and stored in
Analytics Engine.
2 · Metric→
An aggregation over an event — count of events, distinct users, a sum or average. This is the number an alert compares.
3 · Alert rule→
A threshold on the metric over a time window, with a severity. The cron evaluates it and fires when the value breaches.
# 1. a metric over the event (DSL grammar: /metrics/grammar)
shipeasy metrics create checkout-errors \
--event-name checkout_error --query 'count(checkout_error)'
# 2. a threshold rule on that metric — `shipeasy metrics list` prints the id
shipeasy ops alerts create \
--name "Checkout errors spiking" --metric-id <id> \
--comparator gt --threshold 50 --window-hours 24 --severity danger
# 3. confirm it landed
shipeasy ops alerts listThe same three steps are available over MCP (ops_alerts_create) and as the
/shipeasy:alerts:create skill, which surveys your project and proposes rules worth adding. The
CLI command is shipeasy ops alerts; shipeasy ops fired-alerts list is the read-only view of
what has already fired.
The rule fields
Prop
Type
The window is always judged in 6 to 12 buckets, so a "last 30 minutes" intent is a 1-hour window with 5-minute buckets, not a sub-hour window. Pick a window long enough that the metric is stable and buckets narrow enough to catch the spike you care about.
How it fires
A cron evaluates every enabled rule every 10 minutes. For each rule it:
- Reads the metric from Analytics Engine over the window
[now − window hours, now], cut into buckets. - Judges each bucket on its own against the condition. Buckets with no data are left out.
- If enough buckets breach — all of them by default, or the N of M you set — the rule raises an alert.
- When a previously-breaching rule comes back inside its threshold (or reaches Clears at), the alert resolves — no manual clearing.
Auto-resolve is a different thing: it closes an alert the rule has stopped being able to judge (for example because the data stopped arriving), never one that is still breaching. It defaults to Never, which leaves such an alert open until the metric speaks again.
Each rule is evaluated in isolation, so a misconfigured metric can't block the others.
What firing produces
A fired alert does three things at once:
An alert record→
Shows in the read-only fired-alerts view (shipeasy ops fired-alerts list, critical first),
with the observed value, the rule, and a deep link to the metric. One active alert per rule —
re-breaches update it rather than piling up.
A feedback ticket→
Auto-filed into the unified queue as type alert. Severity maps to priority:
Critical → critical, Warning → high, Info → medium.
Deduped while open, so a flapping metric won't spam new tickets.
A notification→
An alert.triggered event goes to the places the rule's Notify lists — in-app by
default, plus any Slack channel or email address you added — per your notification preferences.
When the metric recovers, the alert resolves and no new ticket is filed. If it breaches again after resolving, a fresh alert and ticket are raised.
Where alerts are delivered
By default a notification follows your project default delivery (set under
Settings → Notifications): a default Slack channel and a default email. With no
default set, email falls back to the project owner and Slack to the connector's
configured channel. Any rule can override that with its own target —
useful for routing, say, billing alerts to #finance and on-call alerts to
#incidents.
The Slack channel is always picked from your project's real channels (a
typeahead in the wizard, the in-dashboard assistant, the CLI channels
command) — Shipeasy never guesses a channel. A Slack target requires a
connected Slack connector; the email target works with no connector.
# list the channels the bot can post to
shipeasy ops alerts channels
# create a rule that posts to #incidents and emails on-call
shipeasy ops alerts create --name "Checkout errors spiking" \
--metric-id <id> --comparator gt --threshold 50 \
--notify '{"slackChannel":{"id":"C0123","name":"incidents"},"email":"oncall@acme.com"}'
# move an existing rule's target, or clear it back to the project default
shipeasy ops alerts update "Checkout errors spiking" \
--notify '{"slackChannel":{"id":"C0456","name":"billing"}}'
shipeasy ops alerts update "Checkout errors spiking" --notify nullOver MCP the same control is the notify argument on ops_alerts_create /
ops_alerts_update, and the in-dashboard assistant renders the same channel typeahead
before it writes the rule.
From Slack: the /shipeasy alert <metric> <gt|gte|lt|lte> <threshold> [name]
slash command creates a rule from a channel and automatically targets that
channel — the alert posts back to where you set it up. Requires the Slack app
to be connected to the project.
Which channels fire (in-app, email, Slack) is still governed by your per-event notification preferences — the target only decides where each enabled channel delivers.
Tuning a rule
Everything except the metric is editable in place — from the rule's panel on the Alerts page or the CLI. Adjust the threshold, flip the comparator, widen the window, change the buckets or severity, or toggle it off without recreating it:
shipeasy ops alerts update "Checkout errors spiking" \
--threshold 80 --window-hours 2 --severity warn
shipeasy ops alerts update "Checkout errors spiking" --enabled falseTo repoint a rule at a different metric, archive it and create a new one — the metric is pinned for the rule's life because it fixes both what is measured and how it's aggregated.
Level shifts — when it started, and what changed then
Alerting answers "is something wrong now". The first question of any incident is a different one — when did this start, and what did we change at that moment — and no alert rule can answer it: the earliest moment a rule can name is the start of whatever window it happens to watch.
So a nightly scan segments the last two weeks of every metric that carries an enabled rule, finds the points where its level moved and stayed moved, and records each one with the level either side of it. They show on the metric's detail panel, newest first, under Level shifts.
Beside each one, where there is a match, sits the nearest change you made in the half hour before it: a gate rolled out, a config edited, a killswitch armed. That is a correlation, not a cause — the flag that went to 50% four minutes earlier is usually the reason and sometimes a coincidence, and the panel says "around" rather than "because" for exactly that reason. A change made after the level moved is never named: that is usually somebody responding to the incident.
Nothing here pages anybody, and a level shift never files a ticket. It is context for an incident you already know about, so a metric that moved for a good reason — a launch, a pricing change — costs you nothing but a line
A spike is not a level shift. One bad bucket, or an excursion that comes straight
back, is what an anomaly rule is for; a shift has to hold for at least four
buckets to be recorded at all.
Where to next
Errors auto-file their own tickets once they cross a count threshold.
Read →Step 0Define a metricThe metric DSL an alert rule reads from.
Read →ReferenceAPI referenceThe alert-rules and alerts admin endpoints.