Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/danielfm/pybreaker/llms.txt

Use this file to discover all available pages before exploring further.

PyBreaker exposes a set of properties and methods for runtime monitoring and management. These allow operations teams to observe circuit health at a glance, integrate circuit state into existing dashboards and health endpoints, and intervene manually when circumstances require it — for example, forcing a circuit open during planned maintenance or forcing it closed after confirming a dependency has recovered.

​
Reading Circuit Breaker State

The most commonly needed runtime attributes are exposed as simple read-only properties. 
# Current state: 'closed', 'open', or 'half-open'
print(db_breaker.current_state)

# Consecutive failure count
print(db_breaker.fail_counter)

# Consecutive success count (relevant in half-open state)
print(db_breaker.success_counter)

# Circuit breaker name (useful for logging)
print(db_breaker.name)
PropertyTypeDescription
current_statestrOne of 'closed', 'open', or 'half-open' as reported by the state storage
fail_counterintNumber of consecutive failures recorded since the last reset
success_counterintNumber of consecutive successes recorded in half-open state
namestr | NoneOptional human-readable name set at construction time

​
Reading and Updating Configuration

All three threshold properties are mutable. You can read their current values and update them at runtime without restarting the application — useful for dynamically adjusting sensitivity in response to observed behaviour. 
# Get/set failure threshold
print(db_breaker.fail_max)       # e.g. 5
db_breaker.fail_max = 10         # Update at runtime

# Get/set reset timeout (seconds)
print(db_breaker.reset_timeout)  # e.g. 60.0
db_breaker.reset_timeout = 120   # Update at runtime

# Get/set success threshold
print(db_breaker.success_threshold)  # e.g. 1
db_breaker.success_threshold = 3     # Require 3 successes before closing
success_threshold controls how many consecutive successful trial calls are required while in the half-open state before the circuit closes. Setting it higher than 1 adds a confirmation window before fully restoring traffic.

​
Manual State Control

In exceptional situations, you may need to override the automatic state machine. PyBreaker provides three methods for direct state manipulation. 
# Force the circuit open (e.g., during planned maintenance)
db_breaker.open()

# Allow a trial call (transition to half-open)
db_breaker.half_open()

# Force the circuit closed (e.g., after confirming recovery)
db_breaker.close()
Manual state changes bypass normal failure tracking. Calling open(), half_open(), or close() directly does not reset counters in the way that automatic state transitions do, and may cause the circuit to behave unexpectedly if mixed with normal call traffic. Reserve these methods for operational interventions — planned maintenance windows, post-incident recovery, or testing — rather than application logic.

​
Naming Circuit Breakers

Setting a name at construction time is strongly recommended for any deployment where you have more than one circuit breaker. Names appear in listener callbacks and make log messages, metrics, and health payloads immediately actionable. 
db_breaker = pybreaker.CircuitBreaker(
    fail_max=5,
    reset_timeout=60,
    name='database'
)

cache_breaker = pybreaker.CircuitBreaker(
    fail_max=3,
    reset_timeout=30,
    name='redis-cache'
)

# Name is available in listeners
class LogListener(pybreaker.CircuitBreakerListener):
    def state_change(self, cb, old_state, new_state):
        print(f"[{cb.name}] State changed: {old_state} -> {new_state}")

​
Exposing to Operations

Circuit breaker state is most valuable when surfaced through your existing operational tooling. Consider the following patterns:
  • Health endpoints — expose current_state, fail_counter, and reset_timeout in your service’s /health or /status endpoint so load balancers and monitoring systems can observe circuit health.
  • Metrics pipelines — use a CircuitBreakerListener to emit counters and gauges to Prometheus, DataDog, StatsD, or any other metrics backend on every failure, success, and state_change event.
  • Structured logging — log state changes with the circuit breaker’s name property so log aggregation tools can correlate events across service instances.
def circuit_breaker_health():
    return {
        "db": {
            "state": db_breaker.current_state,
            "fail_count": db_breaker.fail_counter,
            "fail_max": db_breaker.fail_max,
        }
    }
This dictionary can be serialised to JSON and included in any HTTP health check response or exported as structured log fields.

Build docs developers (and LLMs) love

Get started for freeTalk to us