Operate
Promises that guard deploys
Say what an app promises its users (uptime, success rate, speed). CLI tracks the room left to miss and can hold back deploys when a promise breaks.
A promise is what your app commits to, in plain numbers: "up 99.9% of the time", "99.5% of requests succeed", "99% of requests answer in under 300 milliseconds", or, measured in visitors' own browsers, "75% of visits show the page within 2.5 seconds" (with real visitor speed turned on).
Every promise leaves a little room to miss. 99.9% uptime over 30 days allows about 43 minutes down. CLI keeps track of how much of that room is used up and shows it as a bar:
- On track: plenty of room left.
- Running low: three quarters used. You get an alert.
- Broken: it's past its limit. You get an alert.
You can also tell CLI to hold back deploys when a promise breaks. New versions then wait, because shipping more changes to an app that's already struggling usually makes it worse. Fixes can still go out: rolling back always works, and a deploy marked as a fix goes through when the app has a canary or smoke tests to catch a bad one. An owner or admin can push a deploy through with a reason, which is recorded.
How to do it: open an app, go to Settings, find Promises and press Make a promise. Fill in the ones you care about, choose Just tell me or Hold back deploys, and save.
"Promise 99.9% uptime for my API and hold back deploys if it breaks."
Set promises
PUT /v1/services/:id/promise
{"promise": {"uptime": 99.9, "success": 99.5, "latencyMs": 300, "latencyPercent": 99, "windowDays": 30, "guard": "freeze"}}visitorLoadMs and visitorPercent (default 75) add a promise measured from real visits: the share of visits whose main content (LCP) showed within that time. It needs real visitor speed on the app; its objective has kind: "visitors".
Admins and owners; apps only. At least one of uptime, success or latencyMs.
| Field | Meaning |
|---|---|
uptime | percent of the time it answers health checks (90 to 99.999) |
success | percent of requests that don't end in a 5xx |
latencyMs, latencyPercent | that share of requests (default 99%) answer within this many milliseconds |
windowDays | 7, 28 or 30 (default 30). A new app is only measured from when it was created |
guard | warn (default) or freeze |
{"promise": null} removes them.
Read the status
GET /v1/services/:id/promise{
"promise": { "uptime": 99.9, "latencyPercent": 99, "windowDays": 30, "guard": "freeze" },
"objectives": [
{ "kind": "uptime", "label": "Up 99.9% of the time", "target": 99.9, "actual": 99.82, "budgetUsed": 1.8, "burnRate": 6, "state": "spent" }
],
"state": "spent",
"frozen": true,
"summary": "Broken: \"Up 99.9% of the time\" is past its limit. New deploys are held back until it recovers; rollbacks and fixes can still go out."
}How each is measured:
- Uptime: downtime from incidents (see /docs/incidents) inside the window, against
(1 − target) × window. - Success: 5xx answers from the router's hourly counts, against
(1 − target) × requests. - Latency: requests slower than
latencyMs, from the hourly duration histograms (the largest bucket at or under the target counts as fast), against(1 − latencyPercent) × requests. Needs request metrics (CLI_TRAEFIK_METRICS_URL).
budgetUsed is the share of the room to miss that's gone (1 = all of it). burnRate is the last hour's pace against what the window allows: 1 means on pace to use exactly all of it, 14 means it would be gone in about two days. state per objective: ok under 75%, low from 75%, spent at 100%.
The deploy guard
With guard: "freeze" and any objective spent, POST /v1/services/:id/deploys and deploys from Git pushes answer 409 CONFLICT with error.details.frozen: true, the status, canDeployFix and canOverride. What still goes through:
- rollbacks (
POST /v1/deploys/:id/rollback) and CLI's own deploys (autoscaling, region moves); {"fix": true}on an app with a canary or smoke tests (see /docs/previews-and-releases);{"override": "reason"}from an owner or admin. The reason is kept in the activity log with the deploy.
Shadow deploys take no traffic and are never held back. A held Git push is recorded as a failed deploy with the reason, like any other.
Alerts
The leader checks every hour. When a promise starts running low, breaks, or gets back on track after breaking, the project gets an event: promise_at_risk, promise_broken or promise_kept. Add them to a channel's events to be told (see /docs/alerts-and-webhooks).