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.

CircuitBreakerListener is the base class for event hooks that observe a CircuitBreaker instance’s activity. Subclass it and override only the methods you need — the base class provides no-op implementations for all callbacks, so unimplemented methods are silently ignored. Multiple listeners can be registered on a single breaker and all are notified for every event.

​
Callbacks

​
before_call(cb, func, *args, **kwargs) → None

Called immediately before the circuit breaker cb attempts to invoke func. Use this hook for pre-call logging, distributed tracing spans, or metrics timers.
​
cb
CircuitBreaker
The circuit breaker instance that is about to make the call.
​
func
Callable
The function that is about to be called.
​
*args, **kwargs
Any
The positional and keyword arguments that will be forwarded to func.

​
failure(cb, exc) → None

Called when a function invocation raises an exception that is not in the breaker’s exclusion list (i.e., cb.is_system_error(exc) returns True). This callback fires before the state transition logic runs, so it is called regardless of whether the failure actually trips the breaker.
​
cb
CircuitBreaker
The circuit breaker instance that recorded the failure.
​
exc
BaseException
The exception that was raised by the guarded function.

​
success(cb) → None

Called when a guarded function invocation completes without raising a system error. This includes calls where an excluded exception is raised — the breaker treats those as successes for counter purposes.
​
cb
CircuitBreaker
The circuit breaker instance that recorded the success.

​
state_change(cb, old_state, new_state) → None

Called whenever the circuit breaker transitions to a new state. This happens when the breaker opens after hitting fail_max, enters half-open after the reset timeout, or closes after reaching success_threshold.
​
cb
CircuitBreaker
The circuit breaker instance whose state changed.
​
old_state
CircuitBreakerState | None
The previous state object. May be None on the very first state notification after the listener is attached, when no prior state exists in the listener’s context.
​
new_state
CircuitBreakerState
The newly entered state object. The name attribute returns the human-readable state string ('closed', 'open', or 'half-open').

​
Example Implementation

import logging
import pybreaker

class LoggingListener(pybreaker.CircuitBreakerListener):
    """Logs all circuit breaker events."""

    def before_call(self, cb, func, *args, **kwargs):
        logging.debug("[%s] Calling %s", cb.name, func.__name__)

    def failure(self, cb, exc):
        logging.warning("[%s] Failure: %s", cb.name, exc)

    def success(self, cb):
        logging.debug("[%s] Success", cb.name)

    def state_change(self, cb, old_state, new_state):
        logging.info(
            "[%s] State change: %s -> %s",
            cb.name,
            old_state.name if old_state else None,
            new_state.name,
        )

​
Registering Listeners

Listeners can be attached at construction time via the listeners parameter, or dynamically at runtime using add_listener / add_listeners. See the Event Listeners guide for full usage examples and patterns.

Build docs developers (and LLMs) love

Get started for freeTalk to us