# Canary Release

A canary release exposes a limited portion of production to a change and evaluates it before widening the rollout.

- Type: practice
- Domain: Engineering & architecture
- Level: Intermediate
- Last reviewed: 2026-10-19
- Original: [Soroush’s Product Wiki](<https://wiki.soroush.uk/topic/canary-release/>)

## What it means

A canary release introduces a new version or configuration to a small, time-bounded subset of production traffic or instances while the remainder continues on the established version. Comparative signals guide promotion, pause, or rollback. Its primary purpose is release-risk detection; a short operational canary does not automatically establish a causal product uplift.

## Why it matters

Production traffic reveals failures that test environments miss. Limiting early exposure reduces the number of affected users when detection and rollback are fast enough to matter.

## When to use it

Use canaries when versions can coexist, traffic can be divided, and useful health signals arrive within the observation window. They are less effective for very low traffic or delayed effects. Irreversible data changes require a separate compatibility and recovery plan.

## How it works

1. Define the rollout unit, health signals, and stop conditions.
2. Verify version and data compatibility plus a workable rollback path.
3. Send a small, representative share of traffic to the candidate.
4. Compare errors, latency, and important task outcomes over a meaningful interval.
5. Promote in stages or revert, then continue watching for delayed failures.

## A practical example

A booking API routes 5% of requests to a new version. Its confirmation errors increase while the control stays stable, so rollout stops and traffic returns to the old version. The team investigates before exposing the remaining customers.

## Where it breaks

A biased or tiny sample can miss failures, and shared dependencies may affect both groups. Some bugs emerge only at full scale or after long delays. Canarying limits exposure but cannot make a dangerous change harmless.

## Common mistakes

- Promoting on a timer without evaluating health.
- Watching only overall averages that hide the canary’s failures.
- Assuming traffic rollback reverses database writes.

## Sources

1. [Canarying Releases](<https://sre.google/workbook/canarying-releases/>) — Google SRE · Engineering handbook
2. [Canary Release](<https://martinfowler.com/bliki/CanaryRelease.html>) — Martin Fowler · Practitioner guidance

## Related topics

- [Feature Flags](<https://wiki.soroush.uk/topic/feature-flags/>)
- [Observability](<https://wiki.soroush.uk/topic/observability/>)
- [Continuous Delivery](<https://wiki.soroush.uk/topic/continuous-delivery/>)
