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
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.
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. Avecfor 5min, la surveillance se termine d'elle-même et le programme continue.every 2s for 5sdonne trois lectures et dure 5 secondes : un tour ne commence jamais une fois le temps écoulé.for 0sdonne 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
everypendant 3 minutes. Un seul tour faux remet le compte à zéro.for 0slève l'alerte au premier tour vrai. - Une alerte levée s'efface au premier tour faux.
perdonne à 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èsperest unDevice, un texte, une adresse ou une interface.Gi1/0/24etGigabitEthernet1/0/24sont une seule mémoire. L'équipementr1et le texte"r1"en sont deux.asnomme uneAlert, 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 |
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.
fromest un filtre, pas une preuve. Pour cette raison, un blocchangedans un bloconest 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 runse termine avec un code d'échec. - Quand le programme atteint la fin de
mainavec 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.
.severityvient de la priorité, c'est donc toujours un nombre ici. Quand un code Cisco et la priorité donnent deux gravités,.severityest celle de la priorité et.codegarde le code tel qu'il est écrit..facilityest 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)..deviceest le nom de l'inventaire quand l'expéditeur est un équipement de la listefrom, sinon le nom d'hôte écrit dans le message..timeest 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.
.byteset.packetssont 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
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 dansFOLDER/listen/syslog.txt,trap.txtounetflow.txt, les fait passer par les mêmesfrometmatching, et exécute les blocs.listenrevient 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èsfromet avantmatching, pour qu'une relecture puisse essayer un autrematching. Une communauté n'entre jamais dans un fichier enregistré.watchet 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. Unwebhookou unmaildans 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é.