Skip to content
Software Architecture Guide

Circuit Breaker

Explanation

Section titled “Explanation”

A circuit breaker is a proxy: a stand-in between a caller and the service it calls. It is a state machine, so it is always in one of three states.

  • Closed: Calls pass through. The breaker counts recent failures. If they exceed a threshold within a time period, it switches to Open and starts a timer.
  • Open: Calls fail immediately with an exception. This is called failing fast.
  • Half-Open: The timer has expired. A limited number of trial calls pass. If they succeed, the breaker assumes the fault is fixed, resets its counter and returns to Closed. If they fail, it returns to Open and restarts the timer.

Half-Open also protects a recovering service from a sudden flood of requests.

Instead of a timer, an open breaker can probe the service with a ping or a health-check operation. The result decides when to go Half-Open. Operators should also be able to trip or reset a breaker by hand.

Why it matters. Blocked requests that wait for time-outs hold threads, memory and database connections. Unrelated parts of the system that need the same resources can then fail too. Failing fast avoids this.

What callers do. Callers must handle the breaker’s exception. They can reduce functionality for a while, call an alternative operation to get the same data, or tell the user to try again later.

Retry. A circuit breaker and a retry mechanism (see Retry) serve different purposes, but you can combine them. The retry logic must stop when the breaker signals that the fault is not transient.

Monitoring. Log every state change. Breakers should also expose their state for deeper monitoring.

In practice. Resilience4j implements the circuit breaker as a state machine with CLOSED, OPEN and HALF_OPEN states. It lets you configure how long the breaker waits in Open before moving to half-open.

Example

Section titled “Example”

A web shop calls a separate recommendation service. That service starts failing. After several failed calls in a short period, the breaker opens. Product pages now skip the recommendations block at once instead of hanging. When the timer expires, the breaker lets a few trial calls through. If they succeed, recommendations return.

Trade-offs

Section titled “Trade-offs”

The wait time in Open needs tuning. If the breaker stays open too long, it raises errors even after the fault is fixed. If it moves to Half-Open too quickly, it keeps flipping between states, and response times suffer.

Callers also take on work. Every caller must decide what to do when the breaker rejects a call.

The three states of a circuit breaker and the transitions between them.

Diagram source 
stateDiagram-v2
    [*] --> Closed
    Closed --> Open: failures exceed threshold
    Open --> HalfOpen: time-out expires
    HalfOpen --> Closed: trial calls succeed
    HalfOpen --> Open: trial call fails

Checks

Section titled “Checks”
  • The document states the failure threshold and time period that trip each circuit breaker.
  • The document states how a tripped breaker recovers: a time-out, a health-check probe, or a manual reset.
  • Callers define what they do when the breaker rejects a call, such as degrading functionality or informing the user.
  • Retry logic stops when the breaker signals a non-transient fault.
  • Breaker state changes are logged and exposed for monitoring.
Section titled “Related”

Sources

Section titled “Sources”