315 lines
6 KiB
Markdown
315 lines
6 KiB
Markdown
# 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/<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 :
|
||
|
||
```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/<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 :
|
||
|
||
```text
|
||
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
|
||
|