Alerter depuis la console

Guide d'exploitation : configurer, déployer et observer la passerelle. Ce que fait la fonctionnalité côté produit : guide produit ; l'appeler : guide développeur.

La console évalue ses règles toutes les 15 s, dans les deux modes, et notifie par webhook signé. Rien n'est saisi dans la console : règles, webhooks et résumés sont déclarés dans les valeurs du chart, relus sans redémarrage ; une version invalide est refusée et dite à l'écran Alertes, la précédente s'applique.

Étapes

Déclarer règles, webhooks et résumés

1. Écrire les règles, les webhooks et les résumés dans les valeurs de la console :

   values.yaml

   # Valeurs de la console
   alerts:
     rules:     # sortes fermées : error_rate, p95, breaker_open, slo_burn, new_error_code
       - { name: reports-5xx, kind: error_rate, upstream: reports, threshold: 5%, for: 1m, notify: [ops] }
       - { name: orders-p95, kind: p95, operation: createOrder, threshold: 300ms, for: 2m }
     webhooks:  # https exigé (allowHttp pour le lever) ; secretFile : whsec_<base64>, une ligne par secret
       - { name: ops, url: "https://hooks.example/flexway", secretFile: /etc/flexway-console-alerts/ops }
       - { name: chat, urlFile: /etc/flexway-console-alerts/chat-url, secretFile: /etc/flexway-console-alerts/chat, allowPrivate: true }
     summaries:
       - { name: weekly, every: weekly, at: "07:00", weekday: monday, webhook: chat }   # heure UTC
     existingSecret: console-alerts    # secrets et URL à jeton, montés sur /etc/flexway-console-alerts
   slos:
     - { operation: createOrder, availability: 99.9%, latency: { p95: 300ms, target: 99% }, window: 30d }
     - { name: orders-api, upstream: orders-svc, availability: 99.5% }   # un groupe : voir Objectifs SLO par groupe d'opérations

2. Mettre les secrets et les URL à jeton dans le Secret nommé par existingSecret.

3. Déployer les valeurs : la console relit le fichier sans redémarrer.

Régler les règles intégrées

Régler une règle intégrée plutôt que la taire - quelques cas :

alerts:
  builtins:
    # Resserrer : un petit trafic de publications sonne trop tôt ; 5 % refusés, à partir de 100 publications.
    - { name: broker-backpressure, threshold: 5%, minRequests: 100 }
    # Retarder : un courtier qui bascule en moins de 3 min n'est pas un incident.
    - { name: broker-unavailable, for: 3m }
    # Plus tôt : un coupe-circuit ouvert sonne déjà sans délai ; une passerelle dégradée, au bout de 30 s.
    - { name: gateway-degraded, for: 30s }

Avec le proxy Kafka natif (depuis 1.6.0), la règle kafka-proxy-refusals compte des causes fermées et accepte excludeCauses (Clients Kafka natifs : clusters virtuels par tenant) :

alerts:
  builtins:
    - { name: kafka-proxy-refusals, threshold: 10%, excludeCauses: [quota] }   # ne pas sonner sur un quota atteint

Avec l'écouteur MQTT des appareils (depuis 1.7.0), cinq règles de plus - device-connections-refused, sparkplug-node-offline, mqtt-listener-saturation, device-throttled et sparkplug-sequence-gaps, ces deux dernières désactivées par défaut ; le threshold des deux règles Sparkplug est un nombre, pas une part (Console : l'écran Appareils).

Vérifier la signature côté destinataire

Le corps : {"type": "flexway.alert.firing", "timestamp": ..., "data": {"rule", "kind", "state", "since", "target", "value", "unit", "threshold", "subjects"}} (flexway.alert.resolved, flexway.summary.daily, flexway.summary.weekly) - jamais un tenant. Vérifier la signature (Standard Webhooks) avant tout traitement :

import base64, hashlib, hmac, time

def verify(secret: str, headers, body: bytes) -> bool:
    key = base64.b64decode(secret.removeprefix("whsec_"))
    msg_id, ts = headers["webhook-id"], headers["webhook-timestamp"]
    if abs(time.time() - int(ts)) > 300:          # rejeu : 5 minutes de tolérance
        return False
    mac = hmac.new(key, f"{msg_id}.{ts}.".encode() + body, hashlib.sha256).digest()
    want = base64.b64encode(mac).decode()
    # deux signatures pendant une rotation, séparées par une espace : une seule doit correspondre
    return any(hmac.compare_digest(sig.removeprefix("v1,"), want)
               for sig in headers["webhook-signature"].split())

Faire tourner un secret

1. Mettre le nouveau secret en seconde ligne du fichier côté console.
2. Déployer le nouveau côté destinataire.
3. Retirer l'ancien - la console signe avec les deux entre-temps.

Vérifier

• L'écran Diagnostic -> Alertes (admins) liste chaque règle, son état (ok, en attente, déclenchée, résolue, inconnu), sa valeur face au seuil, sa courbe sur 6 h et les livraisons de chaque webhook (résultat, statut, cause).
• Un fichier refusé y est dit, avec sa cause ; la version précédente s'applique.
• GET /api/alerts donne les valeurs en vigueur des règles intégrées et leur origine (tuning).

À savoir

Disponible depuis 1.3.0 ; réglage des règles intégrées en 1.6.0.