Docs menu

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.

Explain it

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

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

FieldMeaning
uptimepercent of the time it answers health checks (90 to 99.999)
successpercent of requests that don't end in a 5xx
latencyMs, latencyPercentthat share of requests (default 99%) answer within this many milliseconds
windowDays7, 28 or 30 (default 30). A new app is only measured from when it was created
guardwarn (default) or freeze

{"promise": null} removes them.

Read the status

API
GET /v1/services/:id/promise
JSON
{
  "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).