Deploy and run
Shadow traffic
Try a new version on a copy of real traffic before anyone sees it: CLI copies requests to it, compares its errors and latency with the live version, and you promote or discard it.
Shadow traffic runs your next version beside the live one and sends it a copy of some real requests. Visitors only ever get answers from the live version; the new one's answers are measured and thrown away. At the end, CLI tells you whether the new version did as well or worse.
How to do it: open an app and press Try in the shadow, then choose how much traffic and for how long.
"Try my new version in the shadow for an hour before switching."
Shadow traffic runs the next version of an app beside the live one and sends it a copy of a share of real requests. Callers only ever get the live version's answers; the new version's answers are measured and thrown away. When its time is up CLI compares the two and says whether the new one did as well, worse, or saw too little to tell. Nothing changes for your users until you promote it.
It sits between a canary (the new version answers some real users) and a plain deploy (it answers everyone).
Start one
In the dashboard, open the service and choose Try in the shadow. From an agent or the terminal:
POST /v1/services/:id/shadow {"percent": 50, "minutes": 30}
cli shadow web --percent 50 --minutes 30| Field | Default | Meaning |
|---|---|---|
percent | 100 | Share of live requests copied to the new version |
minutes | 30 | How long to watch (5 to 1440) |
includeWrites | false | Also copy POST, PUT, PATCH and DELETE |
promoteIfHealthy | false | Promote by itself if it did at least as well |
The service needs a live version to shadow; otherwise you get SHADOW_NEEDS_LIVE.
Reads only, unless you say so
By default only GET and HEAD requests are copied. The shadow uses the same databases as the live version, so copying writes would do them twice. Turn on includeWrites only when the new version writes somewhere else, or when doubled writes don't matter.
For the same reason a shadow never runs the service's release command (migrations). It runs when you promote.
Read the result
GET /v1/deploys/:id/shadow shows requests, 5xx rate and p95 latency for both versions, live while it runs. When the time is up the deploy waits with a verdict:
- good: it failed no more often than the live version and wasn't much slower.
- worse: more errors, or a p95 over twice the live version's plus 100 ms.
- inconclusive: fewer than 20 copied requests.
Then POST /v1/deploys/:id/shadow {"action": "promote"} starts it for real traffic (with the usual health check, after the release command), or {"action": "discard"} drops it. A shadow nobody decides on is discarded after a day, and a newer deploy of the service replaces it.
Cost
The shadow is one more container for its minutes, at the service's plan price. The dry run (?dryRun=true) shows the amount.