Aller au contenu

La version 0.1.0 est une première version, à l'essai. Voir ce qui n'est pas prouvé →

bogolang
EN

← Documentation

Surveiller et écouter

watch, alert when, et les écouteurs pour syslog, les traps et NetFlow.

Toutes les pages de documentation

Cette page couvre les instructions et les commandes qui s'exécutent dans la durée : watch dessine une valeur en direct, every répète un bloc, alert when lève et efface une alerte, et les blocs on écoutent syslog, les traps SNMP et NetFlow. Les exemples watch_alert et syslog_listener les utilisent.

Tout ici ne fait que lire ou écouter. Rien ne modifie un équipement. Les nouveaux mots (watch, every, alert, per, on, port, address, matching) ne sont spéciaux qu'à leur propre place ; ailleurs, ce sont des noms ordinaires. La page du langage liste chaque nouvelle instruction.

every

Bogolang
every 1min:
    r: PingResult = ping(192.0.2.10)
    print(r.loss)

Le bloc s'exécute, attend une période après le début de la dernière exécution, et s'exécute de nouveau, jusqu'à ce que le programme soit arrêté ou que le bloc sorte avec break. Ctrl+C termine le programme. Dans une relecture, un bloc every attend quand même sa période : un programme qui doit se terminer a besoin d'un break, ou utilise watch ... for ou listen(duration).

watch

watch EXPR every DURATION [for DURATION]

watch recalcule la valeur à chaque période et la dessine. C'est une seule ligne, sans bloc.

Bogolang
watch ping(192.0.2.10) every 1s for 10s
La valeur Ce qui est dessiné
PingResult la perte et la latence actuelles, leur minimum, leur moyenne et leur maximum, une petite ligne d'historique de la latence moyenne ; un tour sans réponse est un x
Une grandeur ou un nombre (Rate, Power, Duration, Percent, int, float) la valeur actuelle, le minimum, la moyenne, le maximum, une ligne d'historique
bool oui ou non, et l'heure du dernier changement
Du texte, ou toute autre chose la valeur, et l'heure du dernier changement
dict[str, V], avec V l'un des types ci-dessus une ligne par clé, donc plusieurs hôtes sont surveillés à la fois ; une clé qui disparaît est affichée une fois comme disparue
  • Sans for, la surveillance tourne jusqu'à Ctrl+C, et Ctrl+C termine le programme. Avec for 5min, la surveillance se termine d'elle-même et le programme continue. every 2s for 5s donne trois lectures et dure 5 secondes : un tour ne commence jamais une fois le temps écoulé. for 0s donne une lecture.
  • À la fin, une ligne par nom reste : le nombre de lectures, le minimum, la moyenne et le maximum. Elle est affichée à chaque fin : la fin normale, Ctrl+C et une erreur.
  • Une erreur pendant le calcul de la valeur est affichée à la place de la valeur pour ce tour. La surveillance continue, et la dernière ligne compte les tours avec une erreur.
  • Sur un terminal, le dessin est redessiné sur place. Quand la sortie n'est pas un terminal (un fichier, un tube), la surveillance affiche une ligne simple par lecture, avec l'heure.
  • La moyenne d'une puissance ou d'un gain est la moyenne de ses valeurs en dB, pas des milliwatts.

L'exemple watch_alert surveille un dict de pertes, une clé par hôte, avec watch w.losses(w.hosts) every 1s for 3s. Lancé avec --replay saved, sa sortie est allée dans un fichier, c'est donc la forme simple :

18:15:14 192.0.2.10 0pct
18:15:14 198.51.100.20 50pct
18:15:15 192.0.2.10 0pct
18:15:15 198.51.100.20 50pct
18:15:16 192.0.2.10 0pct
18:15:16 198.51.100.20 50pct
192.0.2.10: 3 readings; lowest 0pct, average 0pct, highest 0pct
198.51.100.20: 3 readings; lowest 50pct, average 50pct, highest 50pct

watch n'a encore jamais dessiné sur un vrai terminal : les tests dessinent dans du texte. La console Windows, Windows Terminal et un vrai Ctrl+C ne sont pas prouvés.

alert when

alert when EXPR for DURATION [per EXPR] [as NAME]:
    BLOCK

Dans un bloc every, le bloc de alert when s'exécute une fois quand la condition a été vraie pendant la durée donnée, et une fois quand elle s'efface.

  • La condition est « vraie pendant 3 minutes » quand elle a été vraie à chaque tour du bloc every pendant 3 minutes. Un seul tour faux remet le compte à zéro. for 0s lève l'alerte au premier tour vrai.
  • Une alerte levée s'efface au premier tour faux.
  • per donne à chaque valeur sa propre mémoire. Une seule ligne d'alerte dans une boucle sur des équipements sert pour chaque équipement, et chacun a besoin de son propre « vrai depuis quand ». La valeur après per est un Device, un texte, une adresse ou une interface. Gi1/0/24 et GigabitEthernet1/0/24 sont une seule mémoire. L'équipement r1 et le texte "r1" en sont deux.
  • as nomme une Alert, pour que le bloc sache pourquoi il s'exécute :
Membre de Alert Type Ce qu'il contient
.raised bool vrai pour la levée, faux pour l'effacement
.cleared bool l'inverse de .raised
.since Moment quand la condition est devenue vraie, dans le fuseau de l'ordinateur
.lasted Duration de ce moment à ce tour, au dixième de seconde
Bogolang
hosts: list[IP] = [192.0.2.10, 198.51.100.20]
every 1min:
    for h in hosts:
        r: PingResult = ping(h)
        alert when r.loss > 5pct for 3min per h as a:
            if a.raised:
                webhook("noc", f"{h}: loss {r.loss} for {a.lasted}")
            else:
                webhook("noc", f"{h}: back to normal after {a.lasted}")

La vérification refuse, avant que le programme ne s'exécute :

error: alert when must be inside an every block
    An alert is tested again and again. Write it under: every 1min:
error: this alert is inside a loop and has no per
    One alert line then serves every turn of the loop and would mix them. Give each its own memory, for example: alert when r.loss > 5pct for 3min per d:

Une boucle while compte comme une boucle, comme une boucle for. Un bloc change dans un bloc d'alerte est refusé aussi : une alerte arrive quand personne ne regarde, et un changement demande une personne ou une fenêtre planifiée. Le bloc peut quand même prévenir une personne, avec mail ou webhook (voir tableaux, rapports et courriel et API).

alert when devient un if, donc break et continue écrits dans son bloc agissent sur la propre boucle de l'ingénieur. Chaque levée et chaque effacement est une ligne du journal d'exécution, qui nomme la valeur de per, ou alert quand il n'y en a pas.

Limites :

  • La mémoire d'une alerte vit dans le programme en cours. Quand le programme est arrêté puis relancé, une alerte levée est oubliée et son bloc « effacée » ne s'exécute jamais.
  • Il n'y a pas de durée séparée « effacer après ». Une valeur qui oscille autour de sa limite lève l'alerte au plus une fois par période, car la levée demande de nouveau la période entière.

L'exemple watch_alert a donné, sur ses réponses enregistrées (le deuxième hôte perd la moitié de ses pings à chaque tour) :

Alert when the loss stays above 5pct for 2s:
ALERT 198.51.100.20: loss 50pct for 2s
Done after 4 turns.

Écouteurs : on syslog, on trap, on netflow

on syslog|trap|netflow [port NUMBER] [address IP] from EXPR [matching STRING] [as NAME]:
    BLOCK

Un bloc on se place dans le corps d'une classe, à côté de ses méthodes. Son écouteur s'ouvre quand la classe est lue, donc avant que main soit appelé. Dans une méthode, une boucle ou en haut d'un fichier, il est refusé :

error: an on block is written in a class, beside its methods
    Write it in the body of a class, outside every method, loop and block. It listens from the moment the class is read.

Dans le bloc, un champ de la classe est atteint par la classe : SyslogListener.counts. Une ligne on avec une erreur qui n'apparaît qu'à l'exécution (une liste from vide, un port déjà pris) arrête le programme avant main.

Partie Ce qu'elle fait
port NUMBER Le port UDP. Sans lui : 514 pour syslog, 162 pour les traps, 2055 pour NetFlow
address IP La seule adresse de cet ordinateur sur laquelle écouter. Elle se place après le port, ou après le type quand aucun port n'est donné. IPv4 seulement. Sans elle, l'écouteur s'ouvre sur toutes les adresses de l'ordinateur
from EXPR Qui est écouté : un Device, une liste d'équipements, une IP, un Net, ou une liste de ceux-ci. Obligatoire
matching STRING Syslog : garde les messages qui contiennent ce texte, majuscules telles qu'écrites. Traps : garde les traps dont l'OID commence par ces nombres. Refusé sur NetFlow
as NAME Le nom que le bloc donne à l'événement

À propos de from :

  • Un paquet de n'importe qui d'autre est rejeté et compté. Pour écouter tout le monde, écrivez from 0.0.0.0/0 : il doit être écrit, il n'est jamais supposé.
  • Un équipement est reconnu par l'adresse de sa ligne d'inventaire. Un équipement qui envoie depuis une autre de ses adresses est rejeté. Le remède est sur l'équipement (définir son interface source) ou dans le programme (donner le Net).
  • L'adresse d'expéditeur d'un paquet UDP peut être falsifiée. from est un filtre, pas une preuve. Pour cette raison, un bloc change dans un bloc on est refusé.

À propos des ports : Linux ne laisse qu'un administrateur ouvrir un port en dessous de 1024, et un autre programme peut déjà tenir un port. Les deux cas donnent une erreur qui nomme la raison et propose un port plus haut de 5000, comme on syslog port 5514. Deux lignes on sur un même port arrêtent le programme à la deuxième. Quand un écouteur s'ouvre, il affiche une ligne sur la sortie d'erreur standard, avec son type et son port, et dit qu'un écouteur silencieux est le plus souvent dû au pare-feu de l'ordinateur. Bogolang ne touche pas à ce pare-feu.

Comment les blocs s'exécutent

  • Un seul bloc s'exécute à la fois, dans l'ordre d'arrivée des événements, pendant que le reste du programme continue.
  • Au plus 10 000 événements attendent les blocs. Les suivants sont rejetés et comptés dans .too_many. La mémoire ne peut pas se remplir.
  • Une erreur dans un bloc arrête le traitement de cet événement seulement. Elle est affichée avec l'événement, l'écouteur continue, et bogo run se termine avec un code d'échec.
  • Quand le programme atteint la fin de main avec un écouteur ouvert, il continue d'écouter jusqu'à Ctrl+C, et le dit.

Syslog

Le bloc reçoit un SyslogEvent : un LogEvent (voir journaux et topologie) avec .source: IP et .received: Moment, tous deux toujours connus.

  • Chaque message est un événement, de n'importe quel fabricant, dans l'ancienne forme (RFC 3164, avec les variantes Cisco) et la nouvelle (RFC 5424). Un paquet sans priorité en tête est illisible.
  • .severity vient de la priorité, c'est donc toujours un nombre ici. Quand un code Cisco et la priorité donnent deux gravités, .severity est celle de la priorité et .code garde le code tel qu'il est écrit.
  • .facility est la facility d'un code Cisco quand le message en a un ; sinon le programme qui a écrit la ligne (sshd), ou le nom standard du numéro de facility (local7).
  • .device est le nom de l'inventaire quand l'expéditeur est un équipement de la liste from, sinon le nom d'hôte écrit dans le message.
  • .time est l'heure écrite par l'équipement, lue dans le fuseau de cet ordinateur quand le message n'en nomme aucun. Quand le message n'a pas d'heure lisible, c'est l'heure d'arrivée. Les heures sont affichées dans le fuseau de l'ordinateur.

Traps

Le bloc reçoit un Trap :

Champ Type
.source IP
.device str, le nom d'inventaire de l'expéditeur, ou vide
.oid str, quel trap c'est, en nombres
.uptime Duration \| None
.values list[SnmpValue]
.received Moment
  • Les traps de version 1 et de version 2c sont lus. Un inform de version 2c reçoit une réponse, pour que l'équipement ne le renvoie pas.
  • Quand des identifiants SNMP de version 2c sont enregistrés pour l'équipement, la communauté du trap doit correspondre. Sinon, le trap est compté comme « pas dans from ». La communauté n'est jamais affichée.
  • Les traps de version 3 ne sont pas dans cette version.

NetFlow

Le bloc reçoit un Flow, un par enregistrement de flux :

Champ Type
.exporter IP
.src, .dst IP \| None
.src_port, .dst_port int
.protocol str : "tcp", "udp", "icmp", ou le numéro sous forme de texte
.bytes Size
.packets int
.start, .end Moment \| None
.in_if, .out_if int, les numéros SNMP des interfaces
.tos int
.next_hop IP \| None
.received Moment
  • NetFlow version 5, version 9 et IPFIX sont lus.
  • Les versions 9 et IPFIX décrivent leurs enregistrements dans un modèle que l'exportateur envoie de temps en temps. Les enregistrements qui arrivent avant leur modèle ne peuvent pas être lus : ils sont comptés dans .unreadable.
  • Une valeur que l'exportateur n'envoie pas est vide ou nulle. Rien n'est deviné.
  • Beaucoup de routeurs exportent un paquet sur N. .bytes et .packets sont ce que l'exportateur a écrit : Bogolang ne les multiplie pas.
  • Le bloc s'exécute une fois par enregistrement. Bogolang est un outil pour regarder des flux, pas un collecteur de flux pour tout un réseau. sFlow n'est pas dans cette version.

Un programme avec trois écouteurs

Bogolang
edition 2027


class Listeners:
    routers: list[Device] = [Device(name="edge-rt1", ip=192.0.2.254, platform="iosxe")]

    on syslog port 5514 address 192.0.2.1 from 192.0.2.0/24 matching "UPDOWN" as e:
        print(e.device, e.code, e.message)

    on trap port 5162 from routers matching "1.3.6.1.6.3.1.1.5" as t:
        print(t.device, t.oid, len(t.values))

    on netflow port 9995 from 0.0.0.0/0 as f:
        if f.dst_port == 443:
            print(f.src, f.dst, f.bytes, f.packets)

    @staticmethod
    def main(args: list[str]) -> None:
        for c in listen(10min):
            print(c)

listen et stop_listening

Commande Fait
listen(duration: Duration \| None = None) attend ici pendant que les écouteurs travaillent : pendant cette durée, ou jusqu'à Ctrl+C ou stop_listening(). Donne une list[ListenCount], une par écouteur
stop_listening() ferme tous les écouteurs. Peut être appelé depuis un bloc. Les événements qui attendent encore ne sont pas traités

Après le retour de listen, les écouteurs sont fermés ; un programme qui veut écouter de nouveau les rouvre. À la fin de listen(duration), les blocs terminent d'abord ce qui attend déjà.

Membre de ListenCount Ce qu'il compte
.kind, .port quel écouteur
.received les paquets arrivés
.handled les événements pour lesquels un bloc s'est exécuté
.not_from les paquets rejetés : l'expéditeur n'est pas dans from (un expéditeur IPv6 aussi)
.not_matching les événements rejetés par matching
.unreadable les paquets, ou les ensembles d'enregistrements NetFlow, qui n'ont pas pu être lus
.too_many les événements rejetés parce que les blocs étaient trop lents

Relecture et essai à blanc

  • --replay FOLDER : aucun port n'est ouvert. Chaque écouteur lit ses événements dans FOLDER/listen/syslog.txt, trap.txt ou netflow.txt, les fait passer par les mêmes from et matching, et exécute les blocs. listen revient quand chaque événement enregistré a été traité, quelle que soit sa durée. Rien n'est rejeté pour cause de vitesse. Un écouteur sans fichier enregistré arrête le programme avec une erreur qui nomme le fichier manquant : un nom de dossier mal écrit ne doit pas ressembler à un réseau calme.
  • --save-replay FOLDER écrit ces fichiers à partir d'une exécution réelle. Un événement est enregistré après from et avant matching, pour qu'une relecture puisse essayer un autre matching. Une communauté n'entre jamais dans un fichier enregistré.
  • watch et les vérifications de service lisent les réponses enregistrées de la même façon.
  • --dry : écouter ne change rien, donc cela s'exécute. Un webhook ou un mail dans un bloc est affiché et pas envoyé.
  • Le journal d'exécution reçoit une ligne quand un écouteur s'ouvre et une quand il se ferme, avec ses compteurs ; pas une ligne par événement.

L'exemple syslog_listener compte les événements de deux équipements, avec on syslog port 5514 from devices as e:, et affiche ceux de gravité 3 ou pire. Son fichier enregistré contient huit événements, dont un venant d'un expéditeur qui n'est pas dans devices. Lancé avec --replay saved, il a donné :

Serious events as they arrive:
2027-01-15 09:02:13 +01:00  core-sw1  LINK-3-UPDOWN: Interface GigabitEthernet1/0/24, changed state to down
2027-01-15 09:04:42 +01:00  edge-rt2  LINK-3-UPDOWN: Interface GigabitEthernet0/0/1, changed state to down
2027-01-15 09:05:10 +01:00  edge-rt2  LINK-3-UPDOWN: Interface GigabitEthernet0/0/1, changed state to up

8 received, 7 handled, 1 from other senders, 0 unreadable

   1  core-sw1 severity 3
   3  core-sw1 severity 5
   2  edge-rt2 severity 3
   1  edge-rt2 severity 6

Les heures sont dans le fuseau de l'ordinateur qui l'a exécuté (UTC+1 ici).

Limites

  • Aucun équipement n'a envoyé de message syslog, de trap ou de flux à Bogolang. Les paquets des tests suivent les formes publiées ; les vrais fabricants s'en écartent.
  • Aucun programme n'a écouté sur le port 514 ou 162. Les tests utilisent des ports hauts.
  • La réponse à un inform a été vérifiée avec le paquet SNMP, pas par un équipement qui a cessé d'envoyer.
  • La vitesse de NetFlow face à un vrai exportateur chargé n'est pas mesurée. Ctrl+C sur un programme qui écoute n'a pas été pressé sur un vrai clavier.
  • IPv4 et UDP seulement : pas d'écouteur IPv6, pas de syslog sur TCP ou TLS, pas de trap de version 3, pas de sFlow.

Voir non prouvé.