CPRA is a high-performance infrastructure monitoring system designed for platform teams managing large-scale microservice architectures. Built on Entity-Component-System (ECS) architecture and queueing theory principles, CPRA handles 1,000,000+ concurrent health checks with automatic worker pool scaling to meet SLO targets.
Monitor millions of services concurrently with automated remediation and dynamic worker scaling.
CPRA is a high-performance infrastructure monitoring system designed for platform teams managing large-scale microservice architectures. Built on Entity-Component-System (ECS) architecture and queueing theory principles, CPRA handles 1,000,000+ concurrent health checks with automatic worker pool scaling to meet SLO targets.
Use CPRA when you need to:
| Metric | Value |
|---|---|
| Max Concurrent Monitors | 1,000,000+ |
| Throughput | 10,000+ checks/sec/pipeline |
| Latency (P95) | < 100ms (configurable via SLO) |
| Memory per Monitor | ~100 bytes |
| Total Memory (1M monitors) | ~100 MB + worker pool overhead |
| Worker Scaling | Dynamic (M/M/c based) |
See Architecture Overview for detailed benchmarks and analysis.
CPRA uses a three-pipeline architecture built on Entity-Component-System principles:
Each pipeline operates independently with its own queue and dynamically-scaled worker pool, enabling:
Queue Implementations:
Dynamic Worker Pools:
For a comprehensive architecture explanation, see the Architecture Overview.
# Prerequisites: Go 1.25 or later
go version # Should show go1.25 or higher
# Build from source
git clone https://github.com/ziad/cpra.git
cd cpra
go build .
# Run with example configuration
./cpra --yaml mock-servers/test_10k.yaml
Expected Output:
Starting CPRA Optimized Controller for 1M Monitors
Profiling server listening at http://localhost:6060/debug/pprof/
Loading monitors from mock-servers/test_10k.yaml...
Monitor loading completed in 1.2s
[INFO] Controller started successfully
[INFO] Pulse pipeline processing 10,000 monitors
[INFO] Worker pool scaled to 143 workers (target SLO: 100ms)
Clone the repository:
git clone https://github.com/ziad/cpra.git
cd cpra
Download dependencies:
go mod download
Build the application:
go build .
Verify installation:
./cpra --help
Build the Docker image:
docker build -f docker/Dockerfile -t cpra:latest .
Run the container:
docker run -it --rm \
-v $(pwd)/my-monitors.yaml:/app/monitors.yaml \
cpra:latest \
./cpra --yaml monitors.yaml
Create a monitors.yaml file to define health checks:
monitors:
- name: "my-service-health-check"
pulse_check:
type: http
interval: 30s
timeout: 5s
max_failures: 3
config:
method: GET
url: http://my-service.example.com/health
retries: 2
intervention:
action: docker
config:
container: my-service-container
action: restart
codes:
red:
dispatch: true
notify: pagerduty
config:
url: https://events.pagerduty.com/v2/enqueue
yellow:
dispatch: true
notify: log
config:
file: /var/log/cpra-alerts.log
Generating Test Configurations:
Use mock-servers/generate_monitors.py to generate test configurations with any number of monitors.
Configure CPRA behavior programmatically:
package main
import (
"cpra/internal/controller"
)
func main() {
config := controller.DefaultConfig()
// Debug mode
config.Debug = true
// Worker pool settings (applies to all three pipelines)
config.WorkerConfig.MinWorkers = 10
config.WorkerConfig.MaxWorkers = 500
// Queue settings
config.QueueCapacity = 131072 // Must be power of 2
// Performance tuning
config.BatchSize = 2000
config.SizingServiceTime = 20 * time.Millisecond // Average job duration
config.SizingSLO = 100 * time.Millisecond // Target latency
config.SizingHeadroomPct = 0.15 // 15% safety buffer
ctrl := controller.NewController(config)
// ... rest of initialization
}
See the API Reference for complete configuration options.
./cpra [OPTIONS]
| Option | Type | Default | Description |
|---|---|---|---|
--yaml | string | internal/loader/replicated_test.yaml | Path to monitors YAML file |
--config | string | - | Configuration file path (optional) |
--debug | bool | false | Enable debug-level logging |
--pprof | bool | true | Enable pprof profiling server |
--pprof.addr | string | localhost:6060 | Pprof server listen address |
Examples:
# Run with debug logging
./cpra --yaml monitors.yaml --debug
# Run with custom pprof port
./cpra --yaml monitors.yaml --pprof.addr localhost:8080
# Disable profiling
./cpra --yaml monitors.yaml --pprof=false
Issue: YAML file not found
Warning: YAML file monitors.yaml not found, starting without loading monitors
Solution: Verify the file path is correct. Use absolute paths or paths relative to where you run the binary:
./cpra --yaml $(pwd)/monitors.yaml
Issue: Build fails with Go version error
go.mod requires go >= 1.25
Solution: Upgrade Go to version 1.25 or later:
go version # Check current version
# Download Go 1.25+ from https://go.dev/dl/
Issue: High memory usage
Solution: Check memory usage with pprof:
# While CPRA is running, access pprof
go tool pprof http://localhost:6060/debug/pprof/heap
# View top memory consumers
(pprof) top
Adjust memory limits in configuration:
config.WorkerConfig.MaxWorkers = 200 // Reduce max workers
config.QueueCapacity = 65536 // Reduce queue size
Issue: Worker pool not scaling
Solution: Enable debug logging to see scaling decisions:
./cpra --yaml monitors.yaml --debug
Check queueing theory parameters:
config.SizingServiceTime = 50 * time.Millisecond // Increase if jobs take longer
config.SizingSLO = 200 * time.Millisecond // Relax SLO if needed
Issue: Monitors not executing
Solution: Verify monitor configuration format and check logs:
./cpra --yaml monitors.yaml --debug 2>&1 | grep ERROR
Validate YAML syntax:
# Use a YAML validator
python -m yaml monitors.yaml
--debug flag)We welcome contributions from the community! CPRA is an open-source project and we appreciate:
Getting Started:
good first issueDevelopment Resources:
This project is licensed under the MIT License - see the LICENSE file for details.
CPRA is built on excellent open-source libraries:
Documentation • Architecture • Issues
Built with ❤️ for platform teams managing large-scale infrastructure