DRAFT — Preliminary version, do not share. · Version préliminaire, ne pas partager.

Alertes

Les règles d'alerte surveillent les états que vos appareils signalent et ouvrent une alerte lorsqu'un appareil franchit un seuil. Fundamentum avertit ensuite les bonnes personnes par courriel et dans l'application, ferme l'alerte lorsque l'appareil revient à la normale, et publie chaque changement sur un flux d'événements que vos systèmes peuvent consommer.

Cycle de vie d'une alerte : une règle d'alerte évalue les états des appareils, ouvre une alerte lorsque toutes les conditions sont remplies, la résout lorsqu'une condition n'est plus remplie, manuellement ou lorsque la règle change, et envoie des notifications ainsi que des événements déclenchés ou résolus à chaque changement

Avant de commencer

Fonctionnement

Une règle d'alerte possède un nom, un niveau de gravité, de une à dix conditions, des messages facultatifs et des notifieurs facultatifs. Une alerte s'ouvre pour un appareil lorsque toutes les conditions de la règle sont remplies, et se ferme dès que l'une d'elles ne l'est plus. Une seule alerte par règle et par appareil est ouverte à la fois.

Il existe six niveaux de gravité, du plus bas au plus élevé : info, advisory, warning, minor, major et critical. Une règle créée sans niveau est critical.

Une condition compare un état à un seuil :

Opérateur Nombres Texte
=, != Oui Oui
>, < Oui Non

Hystérésis

L'hystérésis empêche une alerte d'osciller lorsqu'une valeur fluctue autour du seuil. Il s'agit d'un seuil de libération, et non d'une marge : une fois la condition déclenchée, elle le reste jusqu'à ce que la valeur franchisse la valeur d'hystérésis.

Pour temperature > 75 avec une hystérésis de 70, l'alerte s'ouvre au-dessus de 75 et ne se ferme qu'en dessous de 70. Pour >, l'hystérésis doit être inférieure au seuil ; pour <, supérieure. Elle ne s'applique pas à = et !=.

1. Trouver qui avertir

fun api v1 alert get-alert-rule-notifiable --project-id <project-id>

La réponse énumère les users du projet (avec id, name et email) et les roles que vous pouvez avertir, sous forme de paires nom de rôle et libellé, telles que {"devices_manager": "Devices Manager"}. Les notifieurs utilisent l'id de l'utilisateur ou le nom du rôle.

2. Créer une règle

fun api v1 alert store-alert-rule --project-id <project-id> --body '{
  "name": "Freezer too warm",
  "description": "Freezer temperature above safe limit",
  "is_active": true,
  "level": "major",
  "registry_id": <registry-id>,
  "conditions": [
    {"name": "Temperature", "state": "temperature", "operator": ">", "value": "-15", "hysteresis": -17}
  ],
  "alert_messages": [
    {"language": "en", "message": "Freezer temperature is above -15 °C."},
    {"language": "fr", "message": "La température du congélateur dépasse -15 °C."}
  ],
  "notifiers": [
    {"notifiable_type": "roles", "notifiable": ["devices_manager"], "action_url": "https://app.example.com/alert-rules/{alert_rule_id}"}
  ]
}'

La réponse n'inclut pas les notifieurs. Vérifiez-les avec fun api v1 alert get-alert-rule-notifiers --project-id <project-id> --alert-rule-id <alert-rule-id>, et gérez-les avec les commandes projects-alert-notifier de fun api v2.

3. Recevoir les notifications

Chaque utilisateur averti reçoit un courriel, envoyé depuis l'adresse d'expédition de votre projet, et une notification dans l'application sous l'icône de cloche. Les deux sont envoyés à l'ouverture de l'alerte et lors de sa résolution.

Pour éviter les avalanches, un utilisateur reçoit au plus un courriel par heure et par règle, comptés séparément pour les alertes ouvertes et résolues. Pendant cette heure, les occurrences suivantes incrémentent plutôt un compteur sur la notification dans l'application.

4. Suivre et résoudre les alertes

# Open alerts of a rule
fun api v1 alert get-alerts-by-rule --project-id <project-id> --alert-rule-id <alert-rule-id>

# All alerts of a device, open and closed (stopped_at)
fun api v1 alert get-alerts-by-device --project-id <project-id> --device-id <device-id>

# Close an alert by hand
fun api v1 alert resolve-alert-by-alert-id --project-id <project-id> --alert-id <alert-id>

Une alerte se ferme également lorsque vous modifiez ou supprimez les conditions d'une règle, ou supprimez la règle. Définir is_active à false arrête l'évaluation de la règle, mais laisse ouvertes ses alertes en cours.

5. Diffuser les événements d'alerte vers vos systèmes

Activez le flux de plateforme alerts pour votre projet, puis consommez-le avec un connecteur. Consultez Topics.

fun api v1 pub-sub scope-pub-sub-topic --project-id <project-id> --scopeable-topic alerts

Chaque événement a un event_type valant triggered ou resolved :

{
  "event_type": "triggered",
  "data": {
    "name": "Freezer too warm",
    "project_id": 1,
    "alert_id": 79,
    "alert_rule_id": 12,
    "device_id": 101,
    "device": {"id": 101, "name": "Freezer 3", "serial_number": "sn-0001"},
    "level": "major",
    "messages": [{"language": "en", "message": "Freezer temperature is above -15 °C."}],
    "conditions": [
      {"state_key": "temperature", "state_value": "-12", "operator": ">", "is_triggering": true,
       "threshold_value": "-15", "threshold_hysteresis": "-17"}
    ],
    "created_at": "2026-10-22T14:03:11Z",
    "stopped_at": null,
    "stopping_reason": null,
    "resolved_by": null
  }
}

Pour resolved, stopped_at est renseigné et stopping_reason vaut state_changed, manually_by_user, updated_rule ou deleted_rule. Lorsqu'un utilisateur résout l'alerte manuellement, resolved_by contient l'identifiant de cet utilisateur.

Étapes suivantes