Chezlepro/life-noc
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
life-noc/docs/modeles/inputs-store-model-v1.md

6 KiB
Raw Permalink Blame History

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 :

data/inputs/<domaine>.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/<domaine>.yaml contient un mapping dont les clés correspondent aux item_key.

Exemple :

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 :

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 :

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 :

data/inputs/<domaine>.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/<domaine>.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 :

data/inputs/<domaine>.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