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 fires when its value crosses a threshold
over a window — "checkout errors > 50 in the last hour", "active users < 100
in the last 24h". When it fires, Shipeasy files a ticket into the same feedback
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 by a cron — there's no SDK call and nothing to poll. You only define the rule.
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: /shipeasy:metrics:grammar)
shipeasy metrics create checkout-errors \
--event checkout_error --query 'count(checkout_error)'
# 2. a threshold rule on that metric
shipeasy alert-rules create "Checkout errors spiking" \
--metric checkout-errors --comparator gt --threshold 50 --window 1 --severity danger
# 3. confirm it landed
shipeasy alert-rules listThe same three steps are available over MCP (exp_create_alert_rule) and as the
/shipeasy:alerts:create skill, which surveys your project and proposes rules worth adding. The
CLI command is shipeasy alert-rules — shipeasy alerts is the read-only view of what has
already fired.
The rule fields
Windows are whole hours. The minimum is 1 hour and there are no sub-hour windows — a "last 30 minutes" intent rounds up to 1h. Pick a window long enough that the metric is stable but short enough to catch the spike you care about.
How it fires
A cron evaluates every enabled rule on a roughly 10-minute cadence. For each rule it:
- Compiles the rule's metric into a query over the window
[now − window hours, now]and reads the aggregated value from Analytics Engine. - Compares that value to the threshold with the comparator. If it breaches, the rule raises an alert.
- When a previously-breaching rule comes back inside its threshold, the alert auto-resolves — no manual clearing.
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 alerts view (shipeasy alerts list, danger 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:
danger → critical, warn → high,info → medium. Deduped
while open, so a flapping metric won't spam new tickets.
A notification→
An alert.triggered event hits the in-app feed and email, per your project's
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.
Tuning a rule
Everything except the metric is editable in place — adjust the threshold, flip the comparator, widen the window, change severity, or toggle it off without recreating it:
shipeasy alert-rules update "Checkout errors spiking" \
--threshold 80 --window 2 --severity warn
shipeasy alert-rules update "Checkout errors spiking" --enabled falseTo repoint a rule at a different metric, delete 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.