CPRA - Sistema di Allertamento e Ripristino a Impulsi Concorrenti

Monitora milioni di servizi in contemporanea con riparazione automatica e scalabilità dinamica dei worker.

CPRA è un sistema di monitoraggio dell'infrastruttura ad alte prestazioni progettato per team di piattaforma che gestiscono architetture di microservizi su larga scala. Costruito su architettura Entity-Component-System (ECS) e principi di teoria delle code, CPRA gestisce oltre 1.000.000 di controlli di salute simultanei con scalabilità automatica del pool di worker per raggiungere gli obiettivi SLO.

Sommario

• Perché CPRA?
• Caratteristiche principali
• Caratteristiche prestazionali
• Architettura
• Avvio rapido
• Installazione
• Configurazione
• Opzioni da riga di comando
• Documentazione
• Risoluzione dei problemi
• Contribuire
• Licenza

Perché CPRA?

Usa CPRA quando hai bisogno di:

• Monitorare oltre 100.000 servizi, contenitori o endpoint simultanei
• Riparare automaticamente i guasti senza intervento umano
• Scalare dinamicamente l'infrastruttura di monitoraggio in base al carico
• Ottenere una latenza P95 inferiore a 100ms dalla rilevazione all'allertamento
• Ridurre al minimo l'ingombro di memoria (~100 byte per monitor)

Caratteristiche principali

🚀 Scalabilità massiva

• Gestisce oltre 1.000.000 di monitor simultanei su hardware commodity
• Scalabilità lineare con overhead minimo per monitor
• Design efficiente in memoria: ~100 byte per monitor

⚡ Alte prestazioni

• Oltre 10.000 controlli di salute al secondo per pipeline
• Latenza P95 < 100ms dalla pianificazione all'elaborazione del risultato
• Elaborazione batch e code lock-free riducono al minimo l'overhead

🔄 Riparazione automatica

• Tre pipeline indipendenti:
  1. Pulse: Controllo di salute (HTTP, TCP, ICMP, script personalizzati)
  2. Intervention: Recupero automatico (riavvio servizi, scalatura risorse, esecuzione script)
  3. Code: Allertamento e notifiche (email, SMS, webhook, PagerDuty)

🧠 Scalabilità intelligente

• Teoria delle code M/M/c: Calcola automaticamente il numero ottimale di worker
• Approssimazione di Allen-Cunneen: Gestisce la variabilità del carico reale
• Dimensionamento guidato da SLO: Si adatta dinamicamente per raggiungere gli obiettivi di latenza

🏗️ Architettura orientata ai dati

• Entity-Component-System (ECS) usando mlange-42/ark
• Disposizione della memoria cache-friendly per massime prestazioni
• Minime allocazioni e pressione GC

🔧 Pronto per la produzione

• Profilazione pprof integrata per il debugging
• Arresto graduale con cancellazione del contesto
• Logging completo con modalità debug
• Gestione della memoria con attivazione automatica della garbage collection

Caratteristiche prestazionali

Consulta la Panoramica dell'architettura per benchmark dettagliati e analisi.

Architettura

CPRA utilizza un'architettura a tre pipeline costruita su principi Entity-Component-System:

Tre pipeline di elaborazione indipendenti

1. Pipeline Pulse: Esegue controlli di salute (richieste HTTP, connessioni TCP, script personalizzati)
2. Pipeline Intervention: Esegue la riparazione automatica quando i monitor falliscono
3. Pipeline Code: Invia notifiche di allerta ai sistemi di gestione degli incidenti

Ogni pipeline opera indipendentemente con la propria coda e pool di worker scalato dinamicamente, consentendo:

• Ottimizzazione specifica per pipeline: Configura ogni pipeline separatamente
• Isolamento dei guasti: Il fallimento di una pipeline non influisce sulle altre
• Scalabilità indipendente: Scala i worker in base al carico per pipeline

Architettura della coda e del pool di worker

Implementazioni delle code:

• HybridQueue: Ring buffer + slice di overflow per elaborazione FIFO affidabile
• AdaptiveQueue: Ring buffer con auto-scalatura per carico variabile
• WorkivaQueue: Ring buffer lock-free per latenza ultra-bassa

Pool di worker dinamici:

• Alimentato dal pool di goroutine panjf2000/ants
• Scalatura automatica usando la teoria delle code M/M/c
• Min/Max worker e obiettivi SLO configurabili

Per una spiegazione completa dell'architettura, consulta la Panoramica dell'architettura.

Avvio rapido

Opzione 1: Compila ed esegui localmente

# Prerequisiti: Go 1.25 o successivo
go version  # Dovrebbe mostrare go1.25 o superiore

# Compila dal sorgente
git clone https://github.com/ziad/cpra.git
cd cpra
go build .

# Esegui con configurazione di esempio
./cpra --yaml mock-servers/test_10k.yaml

Output previsto:

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)

Installazione

Prerequisiti

• Go 1.25 o successivo (download)
• Docker (opzionale, per distribuzione containerizzata)

Compilazione dal sorgente

1. Clona il repository:

   root@kitploit:~

   git clone https://github.com/ziad/cpra.git
   cd cpra
   

2. Scarica le dipendenze:

   root@kitploit:~

   go mod download
   

3. Compila l'applicazione:

   root@kitploit:~

   go build .
   

4. Verifica l'installazione:

   root@kitploit:~

   ./cpra --help
   

Distribuzione con Docker

1. Crea l'immagine Docker:

   root@kitploit:~

   docker build -f docker/Dockerfile -t cpra:latest .
   

2. Esegui il container:

   root@kitploit:~

   docker run -it --rm \
     -v $(pwd)/my-monitors.yaml:/app/monitors.yaml \
     cpra:latest \
     ./cpra --yaml monitors.yaml
   

Configurazione

Configurazione dei monitor (YAML)

Crea un file monitors.yaml per definire i controlli di salute:

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

Generazione di configurazioni di test:

Usa mock-servers/generate_monitors.py per generare configurazioni di test con qualsiasi numero di monitor.

Configurazione dell'applicazione

Configura il comportamento di CPRA in modo programmatico:

package main

import (
    "cpra/internal/controller"
)

func main() {
    config := controller.DefaultConfig()

    // Modalità debug
    config.Debug = true

    // Impostazioni del pool di worker (si applicano a tutte e tre le pipeline)
    config.WorkerConfig.MinWorkers = 10
    config.WorkerConfig.MaxWorkers = 500

    // Impostazioni della coda
    config.QueueCapacity = 131072  // Deve essere una potenza di 2

    // Ottimizzazione delle prestazioni
    config.BatchSize = 2000
    config.SizingServiceTime = 20 * time.Millisecond  // Durata media del job
    config.SizingSLO = 100 * time.Millisecond         // Latenza target
    config.SizingHeadroomPct = 0.15                   // 15% di buffer di sicurezza

    ctrl := controller.NewController(config)
    // ... resto dell'inizializzazione
}

Consulta il Riferimento API per le opzioni di configurazione complete.

Opzioni da riga di comando

./cpra [OPZIONI]

Esempi:

# Esegui con registrazione debug
./cpra --yaml monitors.yaml --debug

# Esegui con porta pprof personalizzata
./cpra --yaml monitors.yaml --pprof.addr localhost:8080

# Disabilita la profilazione
./cpra --yaml monitors.yaml --pprof=false

Documentazione

Guide complete

• Panoramica dell'architettura - Progettazione del sistema, diagrammi e analisi delle prestazioni
• Riferimento API - Documentazione API completa con firme delle funzioni
• Riferimento dei tipi - Strutture dati e definizioni dei componenti
• Tutorial di avvio rapido - Inizia in 5-10 minuti
• Attività comuni - Guide pratiche per operazioni tipiche

Risorse aggiuntive

• Per iniziare - Guida dettagliata all'installazione e distribuzione

Risoluzione dei problemi

Problemi comuni

Problema: File YAML non trovato

Warning: YAML file monitors.yaml not found, starting without loading monitors

Soluzione: Verifica che il percorso del file sia corretto. Usa percorsi assoluti o relativi rispetto alla directory da cui esegui il binario:

./cpra --yaml $(pwd)/monitors.yaml

Problema: La compilazione fallisce con errore di versione Go

go.mod requires go >= 1.25

Soluzione: Aggiorna Go alla versione 1.25 o successiva:

go version  # Controlla la versione corrente
# Scarica Go 1.25+ da https://go.dev/dl/

Problema: Utilizzo elevato di memoria Soluzione: Controlla l'utilizzo della memoria con pprof:

# Mentre CPRA è in esecuzione, accedi a pprof
go tool pprof http://localhost:6060/debug/pprof/heap

# Visualizza i maggiori consumatori di memoria
(pprof) top

Regola i limiti di memoria nella configurazione:

config.WorkerConfig.MaxWorkers = 200  // Riduci il numero massimo di worker
config.QueueCapacity = 65536          // Riduci la dimensione della coda

Problema: Il pool di worker non si scala Soluzione: Abilita la registrazione debug per vedere le decisioni di scalatura:

./cpra --yaml monitors.yaml --debug

Controlla i parametri della teoria delle code:

config.SizingServiceTime = 50 * time.Millisecond  // Aumenta se i job richiedono più tempo
config.SizingSLO = 200 * time.Millisecond         // Rilassa lo SLO se necessario

Problema: I monitor non vengono eseguiti Soluzione: Verifica il formato della configurazione dei monitor e controlla i log:

./cpra --yaml monitors.yaml --debug 2>&1 | grep ERROR

Convalida la sintassi YAML:

# Usa un validatore YAML
python -m yaml monitors.yaml

Ottenere aiuto

• Documentazione: Consulta la cartella docs/ per guide dettagliate
• Problemi: Apri un ticket per bug o richieste di funzionalità
• Discussioni: Fai domande e condividi idee nelle Discussioni GitHub
• Log: Fornisci sempre i log quando segnali problemi (usa il flag --debug)

Contribuire

Accogliamo con favore i contributi della comunità! CPRA è un progetto open-source e apprezziamo:

• 🐛 Segnalazioni e correzioni di bug
• ✨ Richieste di funzionalità e implementazioni
• 📖 Miglioramenti alla documentazione
• 🧪 Miglioramenti alla copertura dei test
• 💡 Ottimizzazioni delle prestazioni

Per iniziare:

1. Cerca problemi etichettati con good first issue
2. Fai un fork del repository e invia una pull request

Risorse di sviluppo:

• Panoramica dell'architettura - Comprendi la progettazione del sistema
• Riferimento API - Firma delle funzioni e utilizzo

Licenza

Questo progetto è concesso in licenza con la Licenza MIT - consulta il file LICENSE per i dettagli.

Riconoscimenti

CPRA è costruito su eccellenti librerie open-source:

• mlange-42/ark - Entity-Component-System ad alte prestazioni
• panjf2000/ants - Pool di goroutine con scalabilità dinamica
• Workiva/go-datastructures - Strutture dati lock-free
• uber-go/zap - Logging strutturato