AutoBreaker#

Adaptive circuit breaker for Go with percentage-based thresholds that automatically adjust to traffic patterns.

Why AutoBreaker?#

Traditional circuit breakers use static failure thresholds (e.g., “trip after 10 failures”). This creates problems: at high traffic, 10 failures may represent <1% error rate (too sensitive), while at low traffic, 10 failures may be 100% error rate (too slow to protect).

AutoBreaker uses percentage-based thresholds that adapt to request volume automatically. Configure once, works correctly across all traffic levels and environments.

Quick Start#

1
go get github.com/1mb-dev/autobreaker

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
package main

import (
    "fmt"
    "time"
    "github.com/1mb-dev/autobreaker"
)

func main() {
    breaker := autobreaker.New(autobreaker.Settings{
        Name:    "api-client",
        Timeout: 10 * time.Second,
    })

    result, err := breaker.Execute(func() (interface{}, error) {
        return httpClient.Get("https://api.example.com/data")
    })

    if err == autobreaker.ErrOpenState {
        fmt.Println("Circuit open, using fallback")
        return
    }

    fmt.Printf("Result: %v\n", result)
}

Key Features#

Adaptive Thresholds - Percentage-based failure detection scales with traffic
Runtime Configuration - Update settings without restart
Zero Dependencies - Standard library only
High Performance - <100ns overhead per request, zero allocations
Observability - Metrics() and Diagnostics() APIs built-in
Thread-Safe - Lock-free atomic operations throughout

Documentation#

Getting Started#

Guides#

Building AutoBreaker - Architecture and design decisions
State Machine - State transition specification
Concurrency - Lock-free implementation details
Error Classification - Custom error handling
Performance - Benchmarks and optimization
Decision Guide - When to use AutoBreaker
Migration - From sony/gobreaker

Reference#

API Reference - Complete API documentation
Examples - Production-ready examples
Contributing - How to contribute
Security - Security policy
Changelog - Release history

Performance#

Benchmarks (Go 1.21+, Apple M1):

Operation	Latency	Allocations
Execute (Closed)	78.5 ns	0 allocs
Execute (Open)	0.34 ns	0 allocs
UpdateSettings()	89.2 ns	0 allocs

See Performance Guide for detailed analysis.

Examples#

Production-ready examples in the examples/ directory:

production_ready - HTTP client integration, recommended starting point
runtime_config - Dynamic configuration updates (file, API, signals)
observability - Monitoring, metrics, and diagnostics
prometheus - Prometheus collector integration
adaptive - Adaptive vs static threshold comparison
custom_errors - Custom error classification

License#

MIT License - see LICENSE file.

Contributing#

Contributions welcome! Please see Contributing Guide for guidelines.