diff --git a/docs/inputs-store-model-v1.md b/docs/inputs-store-model-v1.md new file mode 100644 index 0000000..f9cd245 --- /dev/null +++ b/docs/inputs-store-model-v1.md @@ -0,0 +1,315 @@ +# Life-NOC — Inputs Store Model v1 + +## 1. Objet + +Ce document définit le **modèle de stockage des intrants** de Life-NOC. + +L’objectif est de séparer clairement : + +- la **définition** des services, des sondes et des seuils +- les **valeurs vivantes** utilisées par les sondes +- les **mécanismes d’ingestion** de ces valeurs + +Dans Life-NOC : + +- `domains.yaml` définit les domaines, les items, les seuils, les politiques et le type de sonde +- `data/inputs/` contient les **intrants vivants** +- les sondes lisent ces intrants pour produire les états Icinga + +--- + +## 2. Principe général + +La source de vérité des **intrants** ne doit pas être mélangée avec la définition des services. + +### Séparation voulue + +- `domains.yaml` = **configuration** +- `data/inputs/*.yaml` = **valeurs** +- les interfaces = **moyens d’alimentation** +- les sondes = **mécanismes d’évaluation** + +Cela permet : + +- de modifier une valeur sans régénérer toute la définition du système +- d’alimenter une sonde par saisie manuelle, MQTT, API ou autre +- de garder un dépôt stable même lorsque les valeurs changent + +--- + +## 3. Convention de structure + +Le modèle standard v1 des intrants est : + +```text +data/inputs/.yaml +```` + +Exemples : + +* `data/inputs/revue.yaml` +* `data/inputs/voiture.yaml` +* `data/inputs/maison.yaml` +* `data/inputs/energie.yaml` + +Cette convention est **canonique** pour Life-NOC v1. + +--- + +## 4. Pourquoi un fichier par domaine + +Le domaine constitue la bonne granularité pour les intrants car : + +* il regroupe des items de même nature métier +* il tend à partager un profil d’ingestion commun +* il facilite la lecture humaine +* il permet d’introduire des interfaces cohérentes par domaine + +Le domaine fournit donc le **cadre d’ingestion**. +Chaque item garde sa propre source logique à l’intérieur de ce cadre. + +--- + +## 5. Structure d’un fichier d’intrants de domaine + +Chaque fichier `data/inputs/.yaml` contient un mapping dont les clés correspondent aux `item_key`. + +Exemple : + +```yaml +revue-quotidienne-life-noc: + value: "2026-03-14" + captured_at: "2026-03-14T08:00:00Z" + origin: manual + +revue-hebdomadaire-priorites: + value: "2026-03-10" + captured_at: "2026-03-14T08:00:00Z" + origin: manual +``` + +--- + +## 6. Champs minimaux v1 + +### `value` + +Valeur métier utilisée par la sonde. + +Exemples : + +* date de dernière exécution +* compteur +* niveau de stock +* valeur mesurée + +### `captured_at` + +Horodatage de capture ou de mise à jour de l’intrant. + +Format recommandé : + +* ISO 8601 UTC + +Exemple : + +```text +2026-03-14T08:00:00Z +``` + +### `origin` + +Origine de l’intrant. + +Valeurs typiques : + +* `manual` +* `mqtt` +* `api` +* `derived` + +--- + +## 7. Champs optionnels + +Des champs complémentaires pourront être ajoutés selon les besoins : + +* `unit` +* `source_ref` +* `notes` +* `quality` +* `comment` +* `updated_by` + +Ils ne font pas partie du noyau minimal v1. + +--- + +## 8. Rôle du domaine et rôle de l’item + +### Le domaine + +Le domaine définit le **cadre général** : + +* structure d’intrants dominante +* profil d’ingestion principal +* interfaces cohérentes +* conventions de stockage + +### L’item + +L’item définit le **cas particulier** : + +* type de sonde +* seuils +* unité +* clé de lookup +* paramètres propres + +Autrement dit : + +* le domaine dit **comment on travaille** +* l’item dit **quoi on surveille** + +--- + +## 9. Référence entre un item et son intrant + +Un item sondé peut référencer un intrant du store avec : + +```yaml +probe: + type: elapsed_time + source: + type: manual_date + inputs_file: "/opt/life-noc/data/inputs/revue.yaml" + item_key: "revue-hebdomadaire-priorites" +``` + +La sonde résout alors : + +* `inputs_file` → fichier de domaine +* `item_key` → clé à l’intérieur du fichier + +--- + +## 10. Compatibilité et migration + +Le store des intrants est introduit progressivement. + +### Règle de compatibilité + +Si la sonde reçoit : + +* `inputs_file` +* `item_key` + +elle lit le store. + +Sinon, elle peut utiliser une valeur inline fournie dans `domains.yaml`. + +Cela permet une migration sans rupture. + +### Conséquence + +Il n’est pas nécessaire de migrer tous les domaines en même temps. + +--- + +## 11. Portée v1 + +### Convention cible + +Tous les domaines Life-NOC sont destinés à utiliser, à terme, cette structure : + +```text +data/inputs/.yaml +``` + +### Mise en œuvre initiale + +La migration effective commence seulement par les domaines réellement sondés avec la nouvelle méthode. + +En v1, il est recommandé de commencer par : + +* `data/inputs/revue.yaml` + +Les autres domaines seront migrés progressivement, au fur et à mesure de l’introduction de vraies sondes. + +--- + +## 12. Pourquoi ne pas tout migrer d’un coup + +Une migration brutale de tous les domaines augmenterait le risque de régression et compliquerait inutilement le dépôt. + +Le modèle retenu privilégie : + +* une convention unique +* une adoption graduelle +* une compatibilité arrière +* une progression domaine par domaine + +--- + +## 13. Interfaces d’alimentation possibles + +Les intrants stockés dans `data/inputs/*.yaml` peuvent provenir de différentes interfaces : + +* édition manuelle +* script CLI +* interface web +* API +* ingestion MQTT +* calcul dérivé + +Le store d’intrants constitue la **couche commune de persistance**, indépendamment du mode d’ingestion. + +--- + +## 14. Positionnement architectural + +Le modèle de store d’intrants s’inscrit dans l’architecture Life-NOC suivante : + +1. **définition** + + * `domains.yaml` + * types de sondes + * seuils + * politiques + +2. **ingestion** + + * GUI + * API + * MQTT + * scripts + +3. **persistance** + + * `data/inputs/.yaml` + +4. **évaluation** + + * sondes + * calcul de métrique + * états Icinga + +--- + +## 15. Conclusion + +Le répertoire `data/inputs/` devient le modèle canonique de stockage des intrants Life-NOC. + +Le format standard v1 est : + +```text +data/inputs/.yaml +``` + +Cette convention permet : + +* une séparation claire entre définition et valeurs +* une gestion cohérente domaine par domaine +* une migration graduelle +* une intégration future avec GUI, API et MQTT + diff --git a/docs/life-noc-sondes-et-intrants-v1.md b/docs/life-noc-sondes-et-intrants-v1.md new file mode 100644 index 0000000..3e2de95 --- /dev/null +++ b/docs/life-noc-sondes-et-intrants-v1.md @@ -0,0 +1,711 @@ +# Life-NOC — Modèle des sondes et des intrants v1 + +## 1. Objet + +Ce document définit le **modèle canonique des sondes** et le **modèle de gestion des intrants** de Life-NOC. + +L’objectif est de séparer clairement : + +- la **définition** des services, des sondes et des seuils +- les **intrants vivants** utilisés par les sondes +- les **mécanismes d’ingestion** de ces intrants +- la **traduction en états Life-NOC** + +Ce modèle doit permettre : + +- de faire coexister des suivis encore **mockés** et des suivis **réels** +- d’introduire progressivement des sondes réelles sans casser l’existant +- d’unifier les méthodes d’évaluation par grandes familles de suivis + +--- + +## 2. Principes de design + +### 2.1 Stabilité d’abord + +Le dépôt existant doit rester fonctionnel et déployable pendant toute l’introduction des sondes réelles. + +Aucune migration brutale ne doit être exigée. + +--- + +### 2.2 Une sonde par nature de calcul, pas par item + +Les services Life-NOC ne doivent pas reposer sur une multitude de scripts ad hoc. + +Ils doivent être des **instances paramétrées** d’un petit nombre de types de sondes génériques. + +Autrement dit : + +- un item décrit **quoi mesurer** +- la sonde décrit **comment l’évaluer** + +--- + +### 2.3 Les sources de données sont multiples + +Life-NOC doit pouvoir recevoir des données à partir de plusieurs mécanismes : + +- saisie manuelle +- MQTT +- fichiers +- API +- commandes locales +- valeurs dérivées + +MQTT est un **mécanisme de transport**, pas une mémoire durable. + +--- + +### 2.4 L’ambiguïté technique est critique + +Dans Life-NOC, l’impossibilité de conclure techniquement ne doit pas être interprétée comme un état neutre. + +Une erreur de lecture, de parsing ou d’accès à la donnée doit produire un état **CRITICAL**, afin de forcer la correction de la sonde ou de sa source. + +--- + +## 3. Sémantique des états Life-NOC + +Life-NOC utilise la sémantique suivante : + +- **UNKNOWN** : pas encore dû, pas encore à faire +- **OK** : actionnable maintenant +- **WARNING** : il faut se presser +- **CRITICAL** : en retard, anormal, ou impossible à évaluer + +Cette convention diffère volontairement de l’usage classique de Nagios/Icinga. + +Dans Life-NOC : + +- le vert n’exprime pas l’absence de travail +- il exprime le **bon moment pour agir** +- le gris `UNKNOWN` signifie que l’item n’est pas encore dans sa fenêtre d’action + +--- + +## 4. Taxonomie des sondes v1 + +Le modèle conceptuel v1 couvre cinq types de sondes. + +### 4.1 `elapsed_time` + +Mesure le **temps écoulé** depuis un événement ou une exécution précédente. + +#### Exemples +- revue quotidienne +- revue hebdomadaire +- inspection trimestrielle +- test détecteurs +- vérification sauvegardes + +#### Donnée de base +- date de dernière exécution + +#### Métrique typique +- jours écoulés + +#### Logique générale +Plus le temps écoulé augmente, plus l’item devient dû. + +--- + +### 4.2 `elapsed_distance` + +Mesure une **distance écoulée** depuis un événement passé. + +#### Exemples +- kilométrage depuis vidange +- kilométrage depuis entretien pneus +- kilométrage depuis vérification freins +- kilomètres depuis changement de courroie + +#### Données de base +- compteur courant +- compteur lors de la dernière exécution + +#### Métrique typique +- kilomètres écoulés + +#### Logique générale +Plus la distance écoulée augmente, plus l’item devient dû. + +--- + +### 4.3 `current_value` + +Mesure une **valeur instantanée** comparée à des seuils. + +#### Exemples +- tension batterie +- température +- humidité +- espace disque libre +- charge électrique +- niveau de tension + +#### Donnée de base +- valeur actuelle observée + +#### Métriques typiques +- volts +- pourcentage +- degrés +- gigaoctets +- watts + +#### Logique générale +L’état dépend d’un positionnement par rapport à un ou plusieurs seuils. + +--- + +### 4.4 `remaining_quantity` + +Mesure ce qu’il **reste** d’un stock, d’une réserve ou d’une autonomie. + +#### Exemples +- nourriture chats restante +- réserve d’eau +- vitamines restantes +- carburant restant +- consommables + +#### Donnée de base +- quantité restante + +#### Métriques typiques +- jours d’autonomie +- litres +- unités +- kilogrammes +- pourcentage + +#### Logique générale +Plus la quantité restante diminue, plus l’item devient critique. + +--- + +### 4.5 `days_until_due` + +Mesure le **temps restant avant une échéance fixe**. + +#### Exemples +- permis de conduire +- carte d’assurance maladie +- passeport +- assurances +- échéance fiscale +- rendez-vous + +#### Donnée de base +- date d’échéance + +#### Métrique typique +- jours restants + +#### Logique générale +Plus on approche de la date, plus l’item entre dans la fenêtre d’action, puis dans l’urgence. + +--- + +## 5. Sources de données + +Le modèle distingue le **type de sonde** de la **source de données**. + +### 5.1 Sources conceptuellement prévues + +- `manual_date` +- `manual_counter` +- `manual_value` +- `mqtt` +- `file_json` +- `file_text` +- `csv` +- `api` +- `command` +- `derived` + +### 5.2 Sources v1 à faible risque + +Pour l’implémentation initiale, seules les sources suivantes sont retenues : + +- `manual_date` + +Les autres sources sont **réservées** au modèle, mais non implémentées dans la première tranche. + +--- + +## 6. Schéma canonique d’un item + +Chaque item peut, à terme, porter une description de sonde structurée. + +Exemple canonique : + +```yaml +probe: + type: elapsed_time + source: + type: manual_date + value: "2026-03-10" + metric: + unit: days + thresholds: + unknown_lt: 5 + ok_gte: 5 + warning_gte: 7 + critical_gte: 10 + policy: + on_error: critical +```` + +--- + +## 7. Règles générales de seuils + +### 7.1 Cas où la métrique augmente avec l’urgence + +Exemples : + +* jours écoulés +* kilomètres écoulés + +Ordre d’évaluation recommandé : + +1. `critical_gte` +2. `warning_gte` +3. `ok_gte` +4. sinon `unknown` + +--- + +### 7.2 Cas où la métrique diminue avec la gravité + +Exemples : + +* quantité restante +* tension minimale +* autonomie restante + +Ordre d’évaluation recommandé : + +1. `critical_lt` +2. `warning_lt` +3. `ok_gte` +4. sinon `unknown` + +--- + +### 7.3 Cas où la métrique est une échéance future + +Exemples : + +* jours avant expiration +* jours avant rendez-vous +* jours avant renouvellement + +Ordre d’évaluation recommandé : + +1. `critical_lt` +2. `warning_lt` +3. `ok_lt` +4. sinon `unknown` + +--- + +## 8. Politique d’erreur + +La politique d’erreur par défaut de Life-NOC est : + +```yaml +policy: + on_error: critical +``` + +Cela signifie que les situations suivantes doivent produire `CRITICAL` : + +* donnée absente +* donnée invalide +* parsing impossible +* source inaccessible +* seuils incohérents +* type de sonde non supporté +* unité non supportée +* configuration incomplète + +Cette règle vise à éviter que des erreurs techniques demeurent invisibles. + +--- + +## 9. Modèle de stockage des intrants + +La source de vérité des **intrants** ne doit pas être mélangée avec la définition des services. + +### Séparation voulue + +* `domains.yaml` = **configuration** +* `data/inputs/*.yaml` = **valeurs** +* les interfaces = **moyens d’alimentation** +* les sondes = **mécanismes d’évaluation** + +Cela permet : + +* de modifier une valeur sans régénérer toute la définition du système +* d’alimenter une sonde par saisie manuelle, MQTT, API ou autre +* de garder un dépôt stable même lorsque les valeurs changent + +--- + +## 10. Convention de structure du store + +Le modèle standard v1 des intrants est : + +```text +data/inputs/.yaml +``` + +Exemples : + +* `data/inputs/revue.yaml` +* `data/inputs/voiture.yaml` +* `data/inputs/maison.yaml` +* `data/inputs/energie.yaml` + +Cette convention est **canonique** pour Life-NOC v1. + +--- + +## 11. Pourquoi un fichier par domaine + +Le domaine constitue la bonne granularité pour les intrants car : + +* il regroupe des items de même nature métier +* il tend à partager un profil d’ingestion commun +* il facilite la lecture humaine +* il permet d’introduire des interfaces cohérentes par domaine + +Le domaine fournit donc le **cadre d’ingestion**. +Chaque item garde sa propre source logique à l’intérieur de ce cadre. + +--- + +## 12. Structure d’un fichier d’intrants de domaine + +Chaque fichier `data/inputs/.yaml` contient un mapping dont les clés correspondent aux `item_key`. + +Exemple : + +```yaml +revue-quotidienne-life-noc: + value: "2026-03-14" + captured_at: "2026-03-14T08:00:00Z" + origin: manual + +revue-hebdomadaire-priorites: + value: "2026-03-10" + captured_at: "2026-03-14T08:00:00Z" + origin: manual +``` + +--- + +## 13. Champs minimaux v1 du store + +### `value` + +Valeur métier utilisée par la sonde. + +Exemples : + +* date de dernière exécution +* compteur +* niveau de stock +* valeur mesurée + +### `captured_at` + +Horodatage de capture ou de mise à jour de l’intrant. + +Format recommandé : + +* ISO 8601 UTC + +Exemple : + +```text +2026-03-14T08:00:00Z +``` + +### `origin` + +Origine de l’intrant. + +Valeurs typiques : + +* `manual` +* `mqtt` +* `api` +* `derived` + +--- + +## 14. Champs optionnels du store + +Des champs complémentaires pourront être ajoutés selon les besoins : + +* `unit` +* `source_ref` +* `notes` +* `quality` +* `comment` +* `updated_by` + +Ils ne font pas partie du noyau minimal v1. + +--- + +## 15. Rôle du domaine et rôle de l’item + +### Le domaine + +Le domaine définit le **cadre général** : + +* structure d’intrants dominante +* profil d’ingestion principal +* interfaces cohérentes +* conventions de stockage + +### L’item + +L’item définit le **cas particulier** : + +* type de sonde +* seuils +* unité +* clé de lookup +* paramètres propres + +Autrement dit : + +* le domaine dit **comment on travaille** +* l’item dit **quoi on surveille** + +--- + +## 16. Référence entre un item et son intrant + +Un item sondé peut référencer un intrant du store avec : + +```yaml +probe: + type: elapsed_time + source: + type: manual_date + inputs_file: "/opt/life-noc/data/inputs/revue.yaml" + item_key: "revue-hebdomadaire-priorites" +``` + +La sonde résout alors : + +* `inputs_file` → fichier de domaine +* `item_key` → clé à l’intérieur du fichier + +--- + +## 17. Compatibilité et migration + +Le store des intrants est introduit progressivement. + +### Règle de compatibilité + +Si la sonde reçoit : + +* `inputs_file` +* `item_key` + +elle lit le store. + +Sinon, elle peut utiliser une valeur inline fournie dans `domains.yaml`. + +Cela permet une migration sans rupture. + +### Conséquence + +Il n’est pas nécessaire de migrer tous les domaines en même temps. + +--- + +## 18. Portée v1 + +### Convention cible + +Tous les domaines Life-NOC sont destinés à utiliser, à terme, cette structure : + +```text +data/inputs/.yaml +``` + +### Mise en œuvre initiale + +La migration effective commence seulement par les domaines réellement sondés avec la nouvelle méthode. + +En v1, il est recommandé de commencer par : + +* `data/inputs/revue.yaml` + +Les autres domaines seront migrés progressivement, au fur et à mesure de l’introduction de vraies sondes. + +--- + +## 19. Pourquoi ne pas tout migrer d’un coup + +Une migration brutale de tous les domaines augmenterait le risque de régression et compliquerait inutilement le dépôt. + +Le modèle retenu privilégie : + +* une convention unique +* une adoption graduelle +* une compatibilité arrière +* une progression domaine par domaine + +--- + +## 20. Interfaces d’alimentation possibles + +Les intrants stockés dans `data/inputs/*.yaml` peuvent provenir de différentes interfaces : + +* édition manuelle +* script CLI +* interface web +* API +* ingestion MQTT +* calcul dérivé + +Le store d’intrants constitue la **couche commune de persistance**, indépendamment du mode d’ingestion. + +--- + +## 21. Positionnement architectural + +Le modèle des sondes et des intrants s’inscrit dans l’architecture Life-NOC suivante : + +1. **définition** + + * `domains.yaml` + * types de sondes + * seuils + * politiques + +2. **ingestion** + + * GUI + * API + * MQTT + * scripts + +3. **persistance** + + * `data/inputs/.yaml` + +4. **évaluation** + + * sondes + * calcul de métrique + * états Icinga + +--- + +## 22. Coexistence avec le modèle mocké + +Le dépôt actuel repose sur une preuve de concept initialement mockée. + +L’introduction du modèle de sonde ne doit pas casser cette base. + +### Règle de compatibilité + +* si un item **ne définit pas** de bloc `probe`, il continue de fonctionner selon la logique mock existante +* si un item **définit** un bloc `probe`, il peut être pris en charge par la nouvelle sonde générique, selon les types réellement supportés par le moteur + +Cette compatibilité permet une migration progressive, item par item. + +--- + +## 23. Portée de l’implémentation initiale + +Le **modèle conceptuel v1** couvre cinq types de sondes. + +Cependant, afin de préserver la stabilité du dépôt, l’**implémentation initiale** est volontairement limitée à : + +* `probe.type = elapsed_time` +* `source.type = manual_date` +* `metric.unit = days` + +Tous les autres types restent **documentés mais non encore codés**. + +Cette décision est volontaire. Elle permet : + +* de garder le dépôt stable +* de valider la mécanique sur un seul cas simple +* de faciliter le débogage +* de réduire le risque de régression + +--- + +## 24. Exemple complet + +```yaml +revue: + - name: revue-hebdomadaire-priorites + date: "2026-03-10" + notes: Revoir les priorités de la semaine + + probe: + type: elapsed_time + source: + type: manual_date + inputs_file: "/opt/life-noc/data/inputs/revue.yaml" + item_key: "revue-hebdomadaire-priorites" + metric: + unit: days + thresholds: + unknown_lt: 5 + ok_gte: 5 + warning_gte: 7 + critical_gte: 10 + policy: + on_error: critical +``` + +Et dans le store : + +```yaml +revue-hebdomadaire-priorites: + value: "2026-03-10" + captured_at: "2026-03-14T08:00:00Z" + origin: manual +``` + +Interprétation : + +* moins de 5 jours depuis la dernière revue : `UNKNOWN` +* à partir de 5 jours : `OK` +* à partir de 7 jours : `WARNING` +* à partir de 10 jours : `CRITICAL` + +--- + +## 25. Conclusion + +Life-NOC dispose maintenant d’un cadre unifié pour : + +* définir les types de sondes +* structurer les seuils +* normaliser les intrants +* séparer configuration et valeurs +* préparer l’intégration future avec GUI, API et MQTT + +Le modèle standard v1 repose sur : + +* une taxonomie de cinq types de sondes +* une convention de store d’intrants par domaine +* une migration progressive, compatible avec l’existant +