Set up alerts
Get told when errors climb, responses slow down, traffic changes sharply or a release fails.
- Time
- About 8 min
- Who can do it
- alerts.manage to change rules (release manager, admin); alerts.read to view
- Where
- Alerts
- You finish with
- Rules that fire and resolve on their own
What and why#
A flag change can break things quietly: an SDK starts failing, a rollout doubles traffic, a scheduled release does not apply. Alert rules watch the numbers FlagSwift already collects and tell you when one crosses a line, so you hear about it before your users do.
How a rule is evaluated#
- Every enabled rule is measured once a minute by a scheduler on the server (it is switched off by
SCHEDULER_ENABLED=false). A new or edited rule is measured straight away so you see a value without waiting. - Error rate and latency look at the last N hours, including the hour in progress.
- Volume drop and spike compare the last N complete hours with the N hours before them, so a half-finished hour never looks like a drop.
- A rule is Firing when its value reaches the threshold (at or above) and it has enough observations, OK when it is below, and Not enough data when it has too few observations to judge. Too little data never fires, so a quiet night is not an incident.
What happens when a rule fires#
The state change is recorded once even with several server instances, written to the rule's history, shown in the console and on the Overview page, and sent out as notifications. Another message is sent when it resolves.
Before you start#
- Creating, editing, pausing and deleting rules takes
alerts.manage, held by release managers and admins. Everyone withalerts.read, which is every built-in role, can see rules. - A project with some traffic. Error and latency rules measure API requests, volume rules measure evaluations and release rules count failed releases.
- Optional: ask your operator to set
ALERT_WEBHOOK_URLand an email provider if you want messages outside the console.
Pick what to watch#
| Watch | Description |
|---|---|
| Evaluation error rate | Failed API calls as a percentage of requests in the window. Default 5 %, allowed 0.1 to 100. Uses minimum requests. |
| Latency p95 | 95th percentile API response time, estimated from latency buckets. Default 500 ms, allowed 5 to 60,000. Uses minimum requests. |
| Evaluation volume drop | Evaluations fell by at least this percentage compared with the same number of hours before. Default 50 %, allowed 1 to 100. Needs traffic in the earlier period. |
| Evaluation volume spike | Evaluations grew by at least this percentage compared with the same number of hours before. Default 200 %, allowed 1 to 100,000. |
| Release failures | A count of releases that failed in the window. Default 1, allowed 1 to 1,000. A plain count: no minimum requests. |
Walk through it#
Create a rule
Open Alerts and choose New alert rule. Fill in the fields below.
Fields on the form Field Description Name Required, up to 100 characters. Example: Checkout API errors. Project The project to watch. It cannot be changed after the rule is created. Archived projects are refused. Environment All environments, or one. Pick Production if staging noise should not wake anyone. Watch One of the kinds above. Changing it fills in that kind's sensible threshold. Fires at or above The threshold, in the unit shown (%, ms or failures). Checked against the allowed range for the kind. Over the last The window: 1, 2, 3, 6, 12 or 24 hours. Default 1 hour. Minimum requests Default 20, at least 1. Hidden for release failures. Below this many observations the rule shows Not enough data. The New alert rule form with an error rate rule filled in. Minimum requests appears for every kind except release failures. You should see. The rule appears with a value and checked just now within a moment. If it has too little traffic it reads Not enough data.An organization can have at most 50 rules; the 51st is refused with a conflict.
Read the state
Each rule shows OK, Firing (with how long), Not enough data or Paused, its current value and when it was last checked. Open History to see when it fired and resolved and at what value. Each rule keeps its last 20 history entries. Firing rules also count in Alerts firing on the Overview page.
Alert rules are checked every minute. Each card shows its state, its current value and a History list. Pause, edit or delete
Use the switch on a rule to pause or resume it, Edit to change it or Delete to remove it and its history (this cannot be undone). Changing the environment, kind, threshold, window or minimum requests, or pausing the rule, resets it to Not enough data, because its old state answered a different question.
Do it with the API
This is the dashboard API: it uses your session cookie and needs alerts.manage. kind is one of error_rate, latency_p95, volume_drop, volume_spike or release_failures. GET /api/alerts lists rules with counts.firing and counts.total, PATCH /api/alerts/{id} changes fields or sets enabled, and DELETE /api/alerts/{id} removes a rule. See the Alerts API page.
curl -s -b jar.txt -X POST https://flags.example.com/api/alerts \
-H "Content-Type: application/json" \
-d '{
"projectId": "PROJECT_ID",
"environment": "production",
"name": "Production API errors",
"kind": "error_rate",
"threshold": 5,
"windowHours": 1,
"minSamples": 50
}'{
"status": "success",
"message": "Alert rule created",
"data": {
"id": "alr_123",
"name": "Production API errors",
"kind": "error_rate",
"threshold": 5,
"windowHours": 1,
"minSamples": 50,
"environment": "production",
"enabled": true,
"state": "ok",
"lastValue": 0.4,
"firingSince": null,
"history": []
}
}Pause a rule, or change its threshold
Send only the fields you want to change. The update accepts name, environment, kind, threshold, windowHours, minSamples and enabled. The project is not part of an update because a rule stays with its project. The threshold is checked against the range for the kind, as in the table above.
curl -s -b jar.txt -X PATCH https://flags.example.com/api/alerts/alr_123 \
-H "Content-Type: application/json" \
-d '{ "enabled": false }'
curl -s -b jar.txt -X PATCH https://flags.example.com/api/alerts/alr_123 \
-H "Content-Type: application/json" \
-d '{ "threshold": 2, "windowHours": 3 }'Where alerts go#
Rules always show in the console. If your operator sets ALERT_WEBHOOK_URL, FlagSwift posts JSON there when a rule fires or resolves. The body has text and content fields, which Slack and Discord accept, plus event (alert.firing or alert.resolved) and an alert object with the name, kind, value and threshold. If an email provider is configured (Resend or SMTP), everyone whose role includes alerts.manage is also emailed. A failed notification never blocks anything; the webhook gives up after 5 seconds.
Limits today
Good to know#
Start with two rules
Why does my release failures rule say OK, not Not enough data?
Why does a volume rule stay on Not enough data?
How soon will a rule notice?
Can I silence a rule for a maintenance window?
What to check#
- Set a release failures rule to 1 failure and confirm it shows OK, not Not enough data.
- Lower a threshold temporarily to confirm a rule fires, then restore it and watch it resolve. Resolving shows in History.
- If you use the webhook, confirm the message arrives in your chat.
- Creating, editing and deleting rules appears in the audit log as alert rule actions.
If something goes wrong#
The New alert rule button or the switch is missing
Why: Your role lacks alerts.manage.
Fix: Ask a release manager or admin to make the change.
400 Threshold must be between ...
Why: The threshold is outside the range for that kind, for example above 100 for an error rate.
Fix: Use the range in the table above.
409 An organization can have at most 50 alert rules
Why: The organization is at the limit. On FlagSwift Commercial the plan limit (Pro 5, Business 50) applies first and is returned as 402 PLAN_LIMIT_REACHED.
Fix: Delete rules you no longer need, or merge several into one with a wider scope.
A rule never fires although errors are obvious
Why: Fewer requests than Minimum requests were seen in the window, so it reads Not enough data.
Fix: Lower Minimum requests or widen the window.
Rules show Not checked yet and never update
Why: The scheduler is off on every instance (SCHEDULER_ENABLED=false) or the server is not running.
Fix: Ask your operator to leave the scheduler on for at least one instance.
Nothing arrives in chat or email
Why: No ALERT_WEBHOOK_URL is set, the address does not answer within 5 seconds, or no email provider is configured.
Fix: Check the server's logs for webhook.rejected or webhook.failed, and the settings in Self-hosting.