DirectAlerte Agent

Agent de monitoring PM2 pour DirectAlerte avec support multi-site.

Ce projet met en place un agent Node.js qui se connecte à PM2 et envoie les événements et métriques à un backend central via une API REST. Il facilite la surveillance et la gestion des processus PM2 en centralisant les données d'événements et de performance avec support des sites multiples.

Installation

Installation globale (recommandée)

npm install -g directalerte-agent

Si, lors de l'installation, le message « postinstall ignoré » apparaît, c'est normal: le script est désormais tolérant pour éviter les erreurs dans certains contextes PM2. Dans ce cas, exécutez simplement la commande ci-dessous pour configurer le module PM2.

Installation comme module PM2

# Après installation globale
pm2-install-directalerte

Vous pouvez aussi mettre à jour le module et les fichiers associés à tout moment:

pm2-update-directalerte

Utilisation

1. Initialisation interactive

pm2-agent-init

Cette commande vous guide à travers :

• L'inscription/connexion à DirectAlerte
• La sélection ou création d'un site
• La configuration automatique de l'agent
• L'installation comme service PM2 ou systemd

2. Installation rapide PM2

pm2-install-directalerte

Installation automatique comme module PM2 avec interface graphique.

Architecture Multi-Site

L'agent DirectAlerte supporte maintenant un système multi-site :

• Sites : Regroupement logique de serveurs (ex: "Production", "Staging")
• Serveurs : Machines physiques/virtuelles exécutant des processus PM2
• Processus : Applications PM2 monitorées

Utilisateur
├── Site "Production"
│   ├── Serveur "web-01"
│   │   ├── Process "api"
│   │   └── Process "frontend"
│   └── Serveur "db-01"
│       └── Process "mongodb"
└── Site "Staging"
    └── Serveur "staging-01"
        └── Process "api-test"

Fonctionnalités

• Écoute des événements PM2 (processus online, exit, restart, exception, etc.)
• Support du système multi-site avec association serveur/site
• Envoi asynchrone des événements au backend via une API REST sécurisée
• Collecte périodique de métriques (CPU, mémoire) avec filtrage par site
• Installation facile avec pm2-install-directalerte
• Interface d'initialisation interactive avec pm2-agent-init
• Résilience réseau avec file d'attente offline + retry backoff
• Détection d'anomalies CPU/Mémoire (EWMA) et flapping des redémarrages
• Diagnostics enrichis sur exceptions (pm2.describe)
• Intervalle de métriques ajustable à chaud via commande update_interval
• Commandes distantes: restart_process, scale, flush_queue
• Notification de mise à jour de l'agent quand une nouvelle version NPM est disponible

Configuration

Variables d'environnement

| Variable | Description | Requis | |----------|-------------|---------| | BACKEND_URL | URL du backend DirectAlerte | ✅ | | AGENT_API_KEY | Clé API générée automatiquement | ✅ | | SITE_ID | ID du site associé | ✅ | | SERVER_ID | ID unique du serveur | ✅ | | METRICS_INTERVAL_MS | Intervalle de collecte (ms) | ❌ | | COMMANDS_POLL_INTERVAL_MS | Intervalle de polling des commandes (ms) | ❌ | | AGENT_MAX_QUEUE | Taille max de la file offline | ❌ | | FAST_SAMPLING_MS | Intervalle rapide post-anomalie (ms) | ❌ | | FAST_SAMPLING_DURATION_MS | Durée du mode rapide (ms) | ❌ | | UPDATE_CHECK_INTERVAL_MS | Intervalle de vérification des mises à jour | ❌ |

Exemple .pm2-agent.env

BACKEND_URL=http://localhost:3001
AGENT_API_KEY=your-generated-api-key
SITE_ID=64f123456789abcdef012345
SERVER_ID=web-server-01
METRICS_INTERVAL_MS=15000
COMMANDS_POLL_INTERVAL_MS=10000
AGENT_MAX_QUEUE=1000
FAST_SAMPLING_MS=3000
FAST_SAMPLING_DURATION_MS=60000
UPDATE_CHECK_INTERVAL_MS=21600000

Commandes PM2

# Voir tous les processus
pm2 list

# Logs de l'agent
pm2 logs directalerte

# Redémarrer l'agent
pm2 restart directalerte

# Arrêter l'agent
pm2 stop directalerte

# Désinstaller l'agent
pm2 uninstall directalerte

Commandes distantes (Backend → Agent)

L'agent poll régulièrement les commandes depuis le backend et supporte :

• pause_metrics / pause : met en pause l'envoi des métriques
• resume_metrics / resume : reprend l'envoi des métriques
• update_interval : change l'intervalle des métriques à chaud
  • Payload: { "ms": 5000 }
• restart_process : redémarre un process PM2 par nom
  • Payload: { "name": "api" }
• scale : ajuste le nombre d'instances d'un process PM2
  • Payload: { "name": "api", "instances": 3 }
• flush_queue : purge la file d'événements offline

Réponses envoyées par l'agent: completed ou failed avec un message.

Événements supplémentaires émis par l'agent

• metrics:anomaly : détectée via EWMA (CPU ou mémoire)
  • Contient pm_id, cpu, memory, type (cpu, memory ou cpu+memory)
• process:flapping : redémarrages fréquents (≥3 en 2 min)
• agent:update_available : une nouvelle version NPM de l'agent est disponible

Après une anomalie, l'agent passe en mode fast sampling (ex: 3s) pendant une durée définie (ex: 60s), puis revient automatiquement à l'intervalle normal.

Prérequis

• Node.js (version 14 ou supérieure recommandée)
• PM2 installé globalement (npm install -g pm2)
• Accès à un backend DirectAlerte compatible
• Permissions pour exécuter le script avec accès aux processus

Support

• GitHub: https://github.com/exaland/directalerte-agent
• Documentation: https://docs.directalerte.com
• Support: [email protected]

License

MIT License - voir fichier LICENSE pour les détails.