Circuit Breaker
Circuit breakers prevent cascading failures by stopping requests to failing upstreams.
How It Works01
Closed → Failures → Open → Timeout → Half-Open → Success → Closed
↑ ↓
└──────── Failures ───────────┘States
Closed: Normal operation, requests pass through
Open: Failures exceeded threshold, requests fail fast
Half-Open: Testing if service recovered
Configuration02
Circuit breakers are configured per upstream, not per route. The breaker trips on a sustained error rate (not a raw failure count):
upstreams:
- name: order-service
circuit_breaker:
error_threshold: 50.0 # Open when ≥50% of requests error
min_requests: 20 # Minimum requests in the window before tripping
timeout: 30s # Stay open this long before probing again
instances:
- id: order-1
host: 10.0.0.21
port: 8080| Key | Type | Description |
error_threshold | float | Error-rate percentage that opens the breaker. |
min_requests | integer | Minimum requests in the window before it can trip. |
timeout | duration | How long the breaker stays open before probing. |
The circuit_breaker block is parsed and validated everywhere, but it is only
wired into a live breaker on the Kubernetes/operator-driven path. For upstreams
registered from a static config file, it is not yet enforced. See
Upstreams.
Monitoring03
# View circuit breaker states
curl http://gateway:9090/_/circuit-breakers
# Prometheus metrics
octopus_circuit_breaker_state{upstream="order-service"}
octopus_circuit_breaker_failures_total{upstream="order-service"}Example04
upstreams:
- name: payment-service
circuit_breaker:
error_threshold: 50.0
min_requests: 20
timeout: 30s
instances:
- id: payment-1
host: 10.0.0.31
port: 8080
routes:
- path: /api/payments/*
upstream: payment-serviceOnce payment-service exceeds a 50% error rate over at least 20 requests:
Circuit opens
Requests fail fast without hitting the upstream
After 30s, the circuit probes again (half-open)
If probes succeed, the circuit closes