Circuit breaker

API Design

Meaning

The circuit breaker pattern wraps a remote call to detect repeated failures and short-circuit subsequent calls, preventing cascade failures in distributed systems. It addresses the pain point of hammering a failing dependency and exhausting resources while it is down. The trigger is any code path that calls an unreliable external service or resource where repeated failures should be contained rather than retried blindly.

Primary Function

Resilience pattern

Communicative Purpose

Prevents cascade failures by stopping calls to a failing dependency after a threshold of failures is reached, giving the downstream service time to recover.

Pattern

wrap call → monitor failures → open circuit on threshold → fail fast → half-open to test recovery → close on success

Função primária

Resilience pattern

Propósito comunicativo

Prevents cascade failures by stopping calls to a failing dependency after a threshold of failures is reached, giving the downstream service time to recover.

Situações de gatilho

Microservices: calling an external service that may be temporarily unavailable; Distributed systems: protecting against cascade failures when one dependency slows or fails; API clients: handling flaky third-party APIs with bounded retry budgets

Contextos

Microservices architecture, distributed systems, cloud-native applications, service meshes, API gateways, resilience libraries (Hystrix, resilience4j, Polly, pybreaker)

Padrão

wrap call → monitor failures → open circuit on threshold → fail fast → half-open to test recovery → close on success

Colocados típicos

retry policy
fallback
timeout
bulkhead
rate limiter
health check
sliding window
service registry

Substituições comuns

Retry with exponential backoff (simpler but does not stop cascade)
Timeout (only bounds a single call
no failure history)
Bulkhead (isolates resource pools but does not fail fast on failure)

Erros comuns

Setting failure threshold too low causing flapping between open and half-open states; Forgetting the half-open state so the circuit never re-tests recovery; Not providing a fallback so users see raw errors when the circuit opens; Sharing one circuit across unrelated endpoints so one bad endpoint blocks all traffic; Not logging state transitions making post-incident debugging impossible

Similar / contraste

Bulkhead (isolates resource pools vs. fails fast on failure); Retry (re-attempts vs. stops attempting); Timeout (bounds a single call vs. tracks failure history); Rate limiter (throttles by request count vs. by failure rate)

Interferências

Coming from electrical engineering: may think of circuit breaker as purely hardware — in software it is a stateful wrapper around function calls; Coming from Python: may reach for nested try/except chains — circuit breaker tracks failure history across calls, not just within one invocation

Família do chunk

bulkhead
retry
timeout
fallback
rate limiter
health check
sliding window

Nuance

When NOT to use: local in-process calls where failure is unlikely and the overhead of state checks outweighs the resilience benefit; Performance: adds a small per-call cost for state inspection, negligible in most paths but measurable in tight loops; Boundary: state must be scoped per-dependency, not globally, otherwise one failing service blocks unrelated services sharing the breaker

Efeito pragmático

Prevents cascade failures that take down entire systems when one dependency becomes slow or unavailable, enabling graceful degradation and faster recovery of the overall system.

Dica de memória

Circuit breaker: like an electrical fuse that trips after too many shorts — stop the current before it melts the whole panel.

Upgrade path

Adaptive circuit breaker with dynamic thresholds driven by error budgets, or composition with bulkhead and retry policies

Frequência: MediumFormulaicidade: FlexiblePrioridade de aquisição: Active recallPrioridade de output: BothTag de espaçamento: Medium-term

Examples

import time from enum import Enum class CircuitState(Enum): CLOSED, OPEN, HALF_OPEN = "closed", "open", "half_open" class CircuitBreaker: def __init__(self, failure_threshold=5, reset_timeout=30): self.failure_threshold = failure_threshold self.reset_timeout = reset_timeout self.failures = 0 self.state = CircuitState.CLOSED self.opened_at = None def execute(self, func, *args): if self.state == CircuitState.OPEN: if time.time() - self.opened_at >= self.reset_timeout: self.state = CircuitState.HALF_OPEN else: raise ConnectionError("circuit open") try: result = func(*args) self._record_success() return result except Exception: self._record_failure() raise def _record_success(self): self.failures = 0 self.state = CircuitState.CLOSED def _record_failure(self): self.failures += 1 self.opened_at = time.time() if self.failures >= self.failure_threshold: self.state = CircuitState.OPEN breaker = CircuitBreaker(failure_threshold=3, reset_timeout=10) def query_database(sql): return db.execute(sql) rows = breaker.execute(query_database, "SELECT * FROM users")

def get_recommendations(user_id): try: return breaker.call(recommendation_service.fetch, user_id) except ConnectionError: return get_cached_recommendations(user_id) def get_cached_recommendations(user_id): return cache.get(f"recs:{user_id}") or [] recs = get_recommendations(42)

import pybreaker import requests payment_breaker = pybreaker.CircuitBreaker(fail_max=5, reset_timeout=60) def charge_customer(order_id, amount): @payment_breaker def do_charge(): response = requests.post( "https://payments.example.com/charge", json={"order_id": order_id, "amount": amount}, timeout=5, ) response.raise_for_status() return response.json() return do_charge() result = charge_customer("order_123", 99.95)