CPRA - Système concurrent de pulsation, remédiation et alerte

Surveillez des millions de services en simultané avec une remédiation automatisée et un dimensionnement dynamique des workers.

CPRA est un système de surveillance d'infrastructure haute performance conçu pour les équipes de plateforme gérant des architectures de microservices à grande échelle. Construit sur une architecture Entité-Composant-Système (ECS) et les principes de la théorie des files d'attente, CPRA prend en charge plus d'un million de contrôles de santé simultanés avec un dimensionnement automatique du pool de workers pour atteindre les objectifs de niveau de service (SLO).

Table des matières

• Pourquoi CPRA ?
• Fonctionnalités clés
• Caractéristiques de performance
• Architecture
• Démarrage rapide
• Installation
• Configuration
• Options en ligne de commande
• Documentation
• Dépannage
• Contribuer
• Licence

Pourquoi CPRA ?

Utilisez CPRA lorsque vous devez :

• Surveiller 100 000+ services, conteneurs ou endpoints simultanés
• Remédier automatiquement aux pannes sans intervention humaine
• Dimensionner dynamiquement l'infrastructure de surveillance en fonction de la charge
• Atteindre une latence P95 inférieure à 100 ms de la détection à l'alerte
• Minimiser l'empreinte mémoire (~100 octets par moniteur)

Fonctionnalités clés

🚀 Massive évolutivité

• Gère 1 000 000+ moniteurs simultanés sur du matériel standard
• Passage à l'échelle linéaire avec un surcoût minimal par moniteur
• Conception économe en mémoire : ~100 octets par moniteur

⚡ Haute performance

• 10 000+ contrôles de santé par seconde par pipeline
• Latence P95 < 100 ms de la planification au traitement des résultats
• Traitement par lots et files d'attente sans verrouillage minimisant les surcoûts

🔄 Remédiation automatisée

• Trois pipelines indépendants :
  1. Pulse : Contrôle de santé (HTTP, TCP, ICMP, scripts personnalisés)
  2. Intervention : Récupération automatique (redémarrage de services, mise à l'échelle des ressources, exécution de scripts)
  3. Code : Alertes et notifications (email, SMS, webhooks, PagerDuty)

🧠 Dimensionnement intelligent

• Théorie des files d'attente M/M/c : calcule automatiquement le nombre optimal de workers
• Approximation d'Allen-Cunneen : gère la variabilité réelle de la charge de travail
• Dimensionnement piloté par les SLO : mise à l'échelle dynamique pour atteindre les objectifs de latence

🏗️ Architecture orientée données

• Entité-Composant-Système (ECS) utilisant mlange-42/ark
• Disposition mémoire optimisée pour le cache pour des performances maximales
• Allocations et pression GC minimales

🔧 Prêt pour la production

• Profilage pprof intégré pour le débogage
• Arrêt progressif avec annulation par contexte
• Journalisation complète avec mode débogage
• Gestion de la mémoire avec déclenchement automatique du GC

Caractéristiques de performance

Voir Aperçu de l'architecture pour des benchmarks et analyses détaillés.

Architecture

CPRA utilise une architecture à trois pipelines basée sur les principes d'Entité-Composant-Système :

Trois pipelines de traitement indépendants

1. Pipeline Pulse : Exécute les contrôles de santé (requêtes HTTP, connexions TCP, scripts personnalisés)
2. Pipeline Intervention : Effectue la remédiation automatisée en cas d'échec des moniteurs
3. Pipeline Code : Envoie des notifications d'alerte aux systèmes de gestion des incidents

Chaque pipeline fonctionne indépendamment avec sa propre file d'attente et son pool de workers dimensionné dynamiquement, permettant :

• Réglage spécifique par pipeline : configurez chaque pipeline séparément
• Isolation des pannes : la défaillance d'un pipeline n'affecte pas les autres
• Dimensionnement indépendant : adaptez les workers en fonction de la charge de chaque pipeline

Architecture de la file d'attente et du pool de workers

Implémentations de files d'attente :

• HybridQueue : Tampon circulaire + slice de débordement pour un traitement FIFO fiable
• AdaptiveQueue : Tampon circulaire à mise à l'échelle automatique pour charge variable
• WorkivaQueue : Tampon circulaire sans verrouillage pour une latence ultra-faible

Pools de workers dynamiques :

• Propulsé par panjf2000/ants goroutine pool
• Mise à l'échelle automatique utilisant la théorie des files d'attente M/M/c
• Workers min/max et objectifs SLO configurables

Pour une explication complète de l'architecture, consultez l'Aperçu de l'architecture.

Démarrage rapide

Option 1 : Compiler et exécuter localement

# Prérequis : Go 1.25 ou ultérieur
go version  # Devrait afficher go1.25 ou supérieur

# Compiler à partir des sources
git clone https://github.com/ziad/cpra.git
cd cpra
go build .

# Exécuter avec une configuration d'exemple
./cpra --yaml mock-servers/test_10k.yaml

Sortie attendue :

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)

Installation

Prérequis

• Go 1.25 ou ultérieur (télécharger)
• Docker (optionnel, pour déploiement conteneurisé)

Compilation à partir des sources

1. Cloner le dépôt :

   root@kitploit:~

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

2. Télécharger les dépendances :

   root@kitploit:~

   go mod download
   

3. Compiler l'application :

   root@kitploit:~

   go build .
   

4. Vérifier l'installation :

   root@kitploit:~

   ./cpra --help
   

Déploiement Docker

1. Construire l'image Docker :

   root@kitploit:~

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

2. Exécuter le conteneur :

   root@kitploit:~

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

Configuration

Configuration des moniteurs (YAML)

Créez un fichier monitors.yaml pour définir les contrôles de santé :

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

Génération de configurations de test :

Utilisez mock-servers/generate_monitors.py pour générer des configurations de test avec n'importe quel nombre de moniteurs.

Configuration de l'application

Configurez le comportement de CPRA par programmation :

package main

import (
    "cpra/internal/controller"
)

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

    // Mode débogage
    config.Debug = true

    // Paramètres du pool de workers (s'applique aux trois pipelines)
    config.WorkerConfig.MinWorkers = 10
    config.WorkerConfig.MaxWorkers = 500

    // Paramètres de la file d'attente
    config.QueueCapacity = 131072  // Doit être une puissance de 2

    // Réglage des performances
    config.BatchSize = 2000
    config.SizingServiceTime = 20 * time.Millisecond  // Durée moyenne d'un job
    config.SizingSLO = 100 * time.Millisecond         // Latence cible
    config.SizingHeadroomPct = 0.15                   // Marge de sécurité de 15 %

    ctrl := controller.NewController(config)
    // ... suite de l'initialisation
}

Consultez la Référence API pour toutes les options de configuration.

Options en ligne de commande

./cpra [OPTIONS]

Exemples :

# Exécuter avec journalisation de débogage
./cpra --yaml monitors.yaml --debug

# Exécuter avec un port pprof personnalisé
./cpra --yaml monitors.yaml --pprof.addr localhost:8080

# Désactiver le profilage
./cpra --yaml monitors.yaml --pprof=false

Documentation

Guides complets

• Aperçu de l'architecture - Conception du système, diagrammes et analyse des performances
• Référence API - Documentation complète de l'API avec signatures de fonctions
• Référence des types - Structures de données et définitions de composants
• Tutoriel de démarrage rapide - Commencer en 5 à 10 minutes
• Tâches courantes - Guides pratiques pour les opérations typiques

Ressources supplémentaires

• Pour commencer - Guide détaillé d'installation et de déploiement

Dépannage

Problèmes courants

Problème : Fichier YAML introuvable

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

Solution : Vérifiez que le chemin du fichier est correct. Utilisez des chemins absolus ou relatifs à l'endroit où vous exécutez le binaire :

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

Problème : La compilation échoue avec une erreur de version Go

go.mod requires go >= 1.25

Solution : Mettez à niveau Go vers la version 1.25 ou ultérieure :

go version  # Vérifier la version actuelle
# Télécharger Go 1.25+ depuis https://go.dev/dl/

Problème : Utilisation mémoire élevée Solution : Vérifiez l'utilisation mémoire avec pprof :

# Pendant que CPRA est en cours d'exécution, accédez à pprof
go tool pprof http://localhost:6060/debug/pprof/heap

# Afficher les principaux consommateurs de mémoire
(pprof) top

Ajustez les limites mémoire dans la configuration :

config.WorkerConfig.MaxWorkers = 200  // Réduire le nombre max de workers
config.QueueCapacity = 65536          // Réduire la taille de la file d'attente

Problème : Le pool de workers ne se dimensionne pas Solution : Activez la journalisation de débogage pour voir les décisions de dimensionnement :

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

Vérifiez les paramètres de la théorie des files d'attente :

config.SizingServiceTime = 50 * time.Millisecond  // Augmenter si les jobs prennent plus de temps
config.SizingSLO = 200 * time.Millisecond         // Assouplir le SLO si nécessaire

Problème : Les moniteurs ne s'exécutent pas Solution : Vérifiez le format de configuration des moniteurs et consultez les journaux :

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

Validez la syntaxe YAML :

# Utiliser un validateur YAML
python -m yaml monitors.yaml

Obtenir de l'aide

• Documentation : Consultez le dossier docs/ pour des guides détaillés
• Problèmes : Ouvrir un ticket pour les bugs ou demandes de fonctionnalités
• Discussions : Posez des questions et partagez des idées dans GitHub Discussions
• Journaux : Fournissez toujours les journaux lors du signalement de problèmes (utilisez le flag --debug)

Contribuer

Nous accueillons les contributions de la communauté ! CPRA est un projet open source et nous apprécions :

• 🐛 Rapports de bugs et corrections
• ✨ Demandes de fonctionnalités et implémentations
• 📖 Améliorations de la documentation
• 🧪 Améliorations de la couverture de tests
• 💡 Optimisations des performances

Pour commencer :

1. Recherchez les tickets étiquetés good first issue
2. Forkez le dépôt et soumettez une pull request

Ressources de développement :

• Aperçu de l'architecture - Comprendre la conception du système
• Référence API - Signatures de fonctions et utilisation

Licence

Ce projet est sous licence MIT License - voir le fichier LICENSE pour les détails.

Remerciements

CPRA repose sur d'excellentes bibliothèques open source :

• mlange-42/ark - Système Entité-Composant-Système haute performance
• panjf2000/ants - Pool de goroutines avec dimensionnement dynamique
• Workiva/go-datastructures - Structures de données sans verrouillage
• uber-go/zap - Journalisation structurée