Chezlepro/life-noc
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
life-noc/docs/life-noc-sondes-et-intrants-v1.md

14 KiB
Raw Blame History

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 :

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 :

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 :

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.

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/<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

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 :

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 :

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 :

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.

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

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 :

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