Configure alerts

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.

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 compares the window average, not the raw spike

A rule never fires on a single reading — it compares the window average (the bright line) against the threshold. A brief blip that punches over the line averages back out and never pages; only a sustained move fires. Widen the window to smooth more, 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. 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 list

The rule fields

How it fires

A cron evaluates every enabled rule on a roughly 10-minute cadence. For each rule it:

1. Compiles the rule's metric into a query over the window [now − window hours, now] and reads the aggregated value from Analytics Engine.
2. Compares that value to the threshold with the comparator. If it breaches, the rule raises an alert.
3. 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:

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 on 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 alert-rules channels

# create a rule that posts to #incidents and emails on-call
shipeasy alert-rules create "Checkout errors spiking" \
  --metric checkout-errors --comparator gt --threshold 50 \
  --slack-channel '#incidents' --email oncall@acme.com

# move an existing rule's target, or clear it back to the project default
shipeasy alert-rules update "Checkout errors spiking" --slack-channel '#billing'
shipeasy alert-rules update "Checkout errors spiking" --clear-target

Over MCP the same control is the notify argument on exp_create_alert_rule / exp_update_alert_rule ({ slack_channel: { id, name }, email }), and the in-dashboard assistant renders the same channel typeahead before it writes the rule.

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 — 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 false

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

Where to next