Détection d'anomalies¶

Avertissement

Ce service est actuellement en phase alpha.
Il peut évoluer rapidement et certaines fonctionnalités sont expérimentales.

Description¶

Le service de détection d'anomalies fournit une détection d'anomalies sur les flux d'événements en utilisant des modèles Isolation Forest.
Il est exécuté sous forme de service Python conteneurisé, avec intégration à Canopsis et TimescaleDB pour le stockage et la récupération des données.

Fonctionnalités principales :

Détection automatique d'anomalies sur les événements collectés par les connecteurs surveillés
Stockage des résultats dans TimescaleDB
Journalisation en JSON pour intégration avec des systèmes de logs
Possibilité d'extension avec d'autres algorithmes

Prérequis¶

Accès à une base TimescaleDB avec les tables KPI (message_rate, vues agrégées)
Variable d'environnement CPS_POSTGRES_URL configurée
Script de migration appliqué pour créer les tables event_anomaly et event_anomaly_hourly

Lancement (Docker Compose)¶

Exemple de service dans docker-compose.yml :

services:
  anomaly:
    <<: *app_service_base
    image: docker.canopsis.net/docker/pro/anomaly-python:26.04.0
    restart: "on-failure"

La liste des connecteurs à surveiller est gérée depuis l'interface d'administration (voir Connecteurs surveillés pour anomalies).

Connecteurs surveillés pour anomalies¶

Le menu Administration -> Connecteurs surveillés pour anomalies permet de gérer la liste des connecteurs dont les événements sont analysés par le service de détection d'anomalies.

Le module Connecteurs surveillés pour anomalies permet de gérer la liste de ces connecteurs. Les données d'anomalies de ces connecteurs sont affichées sur la page Bilan de santé.

La liste des connecteurs est présentée dans un tableau avec les colonnes suivantes :

Colonne	Description
Nom du connecteur	Nom du connecteur surveillé
Activé	Indique si la surveillance est active pour ce connecteur
Date de création	Date de création de l'entrée
Date de mise à jour	Date de la dernière modification
Auteur	Utilisateur ayant créé ou modifié l'entrée
Actions	Modifier ou supprimer le connecteur surveillé

Les connecteurs sont triés par ordre alphabétique. Le tri n'est pas modifiable depuis l'interface.

Créer ou modifier un connecteur surveillé¶

Cliquez sur le bouton + pour ouvrir la fenêtre Créer un connecteur surveillé pour anomalies, ou sur l'icône de modification pour ouvrir Modifier le connecteur surveillé pour anomalies.

Paramètre	Description
Activé	Active ou désactive la surveillance des anomalies pour ce connecteur
Nom du connecteur	Nom du connecteur à surveiller. Le champ propose une suggestion automatique à partir des connecteurs existants. Il est possible d'ajouter un connecteur qui n'existe pas encore en base. Un même nom de connecteur peut être ajouté plusieurs fois.

Note

Modifier le nom d'un connecteur supprime l'ancien nom de la liste et ajoute le nouveau.

Supprimer un connecteur surveillé¶

Un clic sur le bouton de suppression affiche une fenêtre de confirmation :
Supprimer {nom} de la liste des connecteurs de surveillance d'anomalies ?

En cas de confirmation :

La surveillance des anomalies est arrêtée pour ce connecteur.
Les données haute fréquence sont supprimées sous 24 heures (sans suppression immédiate).
Les données horaires agrégées (event_anomaly_hourly) sont supprimées selon les paramètres de stockage.

Actions en masse¶

Après avoir sélectionné plusieurs connecteurs, les actions suivantes sont disponibles :

Action	Description
Supprimer les connecteurs surveillés pour anomalies	Supprime les connecteurs sélectionnés après confirmation. Les effets sont identiques à la suppression unitaire.
Activer les connecteurs surveillés pour anomalies	Active immédiatement la surveillance pour les connecteurs sélectionnés, sans confirmation.
Désactiver les connecteurs surveillés pour anomalies	Désactive la surveillance pour les connecteurs sélectionnés après confirmation. Les effets sont identiques à la suppression.

Si une action ne s'applique pas à un connecteur sélectionné (ex. activer un connecteur déjà actif), elle est ignorée pour ce connecteur.

Droits¶

Deux droits sont disponibles pour cette fonctionnalité :

Droit	Description
Connecteurs surveillés pour anomalies (Administration)	Accès CRUD à la page Connecteurs surveillés pour anomalies
Connecteurs surveillés pour anomalies (API)	Accès à l'API de gestion des connecteurs surveillés pour anomalies

Bilan de santé - Onglet Connecteurs¶

L'onglet Connecteurs du Bilan de santé affiche l'état des connecteurs surveillés par le service de détection d'anomalies.

Le bouton Gérer les connecteurs surveillés ouvre directement la page d'administration des connecteurs.

Les connecteurs sont répartis en deux sections :

Connecteurs activés : connecteurs dont la surveillance est active
Connecteurs désactivés : connecteurs dont la surveillance est désactivée

Chaque section affiche "Aucun connecteur" si elle est vide.

Les données sont mises à jour toutes les minutes via websocket.

Tuiles des connecteurs¶

Chaque connecteur est représenté par une tuile triée par ordre alphabétique dans sa section. Trois états sont possibles :

Couleur	Description
Verte	Aucune anomalie détectée lors de la dernière minute
Rouge	Anomalie détectée lors de la dernière minute
Grise	Données insuffisantes (modèle en cours d'entraînement)

Lors de la phase initiale d'entraînement du modèle (moins d'une heure de données disponibles), toutes les tuiles affichent Données insuffisantes. Une info-bulle précise : Entraînement du modèle en cours, veuillez vérifier plus tard.

Une fois au moins un modèle entraîné, chaque tuile affiche :

Le nom du connecteur
Le nombre d'événements
L'intervalle de la dernière minute

Détail d'un connecteur¶

Un clic sur une tuile ouvre une fenêtre de détail avec :

Le nom du connecteur en titre
Le bouton Activé permettant de désactiver la surveillance (après confirmation : Désactiver la surveillance des anomalies pour {connecteur} ?)
Les compteurs pour la période sélectionnée :
- Anomalies détectées
- Événements moyens
- Intervalle de regroupement des événements (constante : 1 min)
Un graphique pour la période sélectionnée, avec les anomalies mises en évidence et la courbe des événements moyens. Au survol d'un point, le nombre d'événements pour cet intervalle est affiché.

La période peut être sélectionnée parmi les 24 dernières heures (par tranche horaire). La tranche courante est sélectionnée par défaut. Les tranches du jour précédent sont suffixées de (hier).

Note

Si les données sont insuffisantes pour afficher le graphique, le message suivant est affiché : Pas encore assez de données pour afficher le graphique des anomalies.

Paramètres de stockage¶

La section Anomalies d'événements des paramètres de stockage permet de configurer la rétention des données horaires d'anomalies.

Paramètre	Description	Défaut
Supprimer les données horaires des anomalies	Supprime les enregistrements de la table `event_anomaly_hourly` plus anciens que le délai configuré	Activé, 1 mois

Cycle de vie du service¶

Démarrage : initialisation d'un modèle Isolation Forest pour chaque connecteur à partir de l'historique TimescaleDB
Initialisation du modèle : si moins d'une heure de données historiques est disponible, le service attend avant d'entraîner le modèle
Traitement périodique : lecture des données récentes, prédiction des anomalies, sauvegarde des résultats. L'intervalle de regroupement des événements est de 1 minute (constante)
Ré-entraînement du modèle : les modèles sont ré-entraînés après la moitié de l'intervalle --interval depuis le dernier entraînement. Avec l'intervalle par défaut de 6h, le ré-entraînement se produit toutes les 3 heures
Politique de rétention : les données haute fréquence anciennes sont purgées en conservant uniquement les agrégats
Arrêt propre : libération des connexions à la base de données à l'arrêt

Paramètres du service¶

Requis¶

La variable d'environnement CPS_POSTGRES_URL doit pointer vers la base TimescaleDB :

CPS_POSTGRES_URL=postgresql://user:pass@timescaledb:5432/canopsis

Optionnels¶

Paramètre	Type	Défaut	Description	Recommandation
`--contamination`	float ou str	`"auto"`	Proportion d'anomalies attendues dans les données. Accepte un flottant dans (0.0, 0.5] ou `"auto"`.	Commencer à `0.1` (10%) et ajuster selon les résultats. En cas de doute, utiliser `"auto"`.
`--interval`	str	`"6h"`	Fenêtre de données pour l'entraînement du modèle. Exemples : `1h`, `30m`, `12h`. Minimum : 1h.	Utiliser au moins `5h` (~300 points) pour un apprentissage robuste.
`--db-url`	str	None	URL de connexion à la base de données. Surcharge `CPS_POSTGRES_URL` si fournie.	Fournir explicitement si les variables d'environnement peuvent différer.
`--log-level`	str	`"INFO"`	Niveau de verbosité des logs. Valeurs : `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`.	Conserver `INFO` en phase de mise en service. Passer à `WARNING` ou `ERROR` en production stable.

Modèle de données¶

Les résultats sont stockés dans TimescaleDB :

event_anomaly : détections minute par minute
event_anomaly_hourly : agrégat horaire des anomalies

Exemples de requêtes :

SELECT * FROM event_anomaly
WHERE time >= NOW() - INTERVAL '1 hour'
ORDER BY time, connector_name;

SELECT * FROM event_anomaly_hourly
WHERE time >= NOW() - INTERVAL '1 day'
ORDER BY time, connector_name;

Dépannage¶

Problème	Cause probable	Solution
Modèle non entraîné (démarrage à froid)	Moins d'1h de données disponibles	Vérifier la présence d'au moins 1h de données agrégées dans `message_rate`
Aucune donnée	Connecteur absent ou non surveillé	Vérifier que le connecteur est bien ajouté dans Connecteurs surveillés pour anomalies et présent dans `message_rate`
Trop d'anomalies détectées	Paramètre `--contamination` trop élevé	Réduire `--contamination` (ex. de `0.1` à `0.05`) ou augmenter `--interval`
Pas assez d'anomalies détectées	Paramètre `--contamination` trop faible	Augmenter `--contamination` (ex. de `0.05` à `0.1`) ou réduire `--interval`
Débit élevé	Rétention TimescaleDB insuffisante	Vérifier les paramètres de rétention et la fréquence de ré-entraînement