Skip to content

Version 0.1.0 is a first version, for trial. See what is not proven →

bogolang
FR

← Documentation

Watching and listening

watch, alert when, and the listeners for syslog, traps and NetFlow.

All documentation pages

This page covers the statements and commands that run over time: watch draws a value live, every repeats a block, alert when raises and clears an alert, and the on blocks listen for syslog, SNMP traps and NetFlow. The examples watch_alert and syslog_listener use them.

Everything here only reads or listens. Nothing changes a device. The new words (watch, every, alert, per, on, port, address, matching) are special only in their own place; elsewhere they are ordinary names. The language page lists every new statement.

every

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

The block runs, waits until one period after the start of the last run, and runs again, until the program is stopped or the block leaves with break. Ctrl+C ends the program. In a replay an every block still waits its period: a program that should end needs a break, or uses watch ... for or listen(duration).

watch

watch EXPR every DURATION [for DURATION]

watch works the value out again at each period and draws it. It is one line, with no block.

Bogolang
watch ping(192.0.2.10) every 1s for 10s
The value What is drawn
PingResult loss and latency now, their lowest, average and highest, a small history line of the average latency; a turn with no reply is an x
A quantity or a number (Rate, Power, Duration, Percent, int, float) the value now, lowest, average, highest, a history line
bool yes or no, and the time of the last change
Text, or anything else the value, and the time of the last change
dict[str, V], with V one of the above one line per key, so several hosts are watched at once; a key that goes away is shown once as gone
  • Without for the watch runs until Ctrl+C, and Ctrl+C ends the program. With for 5min the watch ends by itself and the program goes on. every 2s for 5s gives three readings and lasts 5 seconds: a turn never starts once the time is up. for 0s gives one reading.
  • At the end one line per name stays: the number of readings, the lowest, the average and the highest. It is printed on every end: the normal one, Ctrl+C and an error.
  • An error while working out the value is shown in place of the value for that turn. The watch goes on, and the last line counts the turns with an error.
  • On a terminal the drawing is redrawn in place. When the output is not a terminal (a file, a pipe), the watch prints one plain line per reading, with the time.
  • The average of a power or a gain is the average of its dB figures, not of the milliwatts.

The example watch_alert watches a dict of losses, one key per host, with watch w.losses(w.hosts) every 1s for 3s. Run with --replay saved, its output went to a file, so it is the plain form:

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 has not drawn on a real terminal yet: the tests draw into text. The Windows console, Windows Terminal and a real Ctrl+C are not proven.

alert when

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

Inside an every block, the block of alert when runs once when the condition has been true for the time given, and once when it clears.

  • The condition is "true for 3 minutes" when it was true on every turn of the every block during 3 minutes. One false turn starts the count again. for 0s raises on the first true turn.
  • A raised alert clears on the first false turn.
  • per gives each value its own memory. One alert line inside a loop over devices serves every device, and each needs its own "true since when". The value after per is a Device, a text, an address or an interface. Gi1/0/24 and GigabitEthernet1/0/24 are one memory. The device r1 and the text "r1" are two.
  • as names an Alert, so the block knows why it runs:
Member of Alert Type What it holds
.raised bool true for the raise, false for the clear
.cleared bool the opposite of .raised
.since Moment when the condition became true, in the zone of the computer
.lasted Duration from then to this turn, to the tenth of a second
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}")

The check refuses, before the program runs:

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:

A while loop counts as a loop, as a for loop does. A change block inside an alert block is refused too: an alert arrives when nobody is watching, and a change wants a person or a planned window. The block can still tell a person, with mail or webhook (see tables, reports and mail and APIs).

alert when becomes an if, so break and continue written in its block act on the engineer's own loop. Each raise and each clear is a line of the run record, naming the per value, or alert when there is none.

Limits:

  • The memory of an alert lives in the running program. When the program is stopped and started again, a raised alert is forgotten and its "cleared" block never runs.
  • There is no separate "clear after" time. A value that swings around its limit raises at most once per period, because raising needs the whole period again.

The example watch_alert gave, on its saved answers (the second host loses half its pings on every turn):

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

Listeners: on syslog, on trap, on netflow

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

An on block stands in the body of a class, beside its methods. Its listener opens when the class is read, so before main is called. In a method, a loop or at the top of a file it is refused:

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.

Inside the block, a field of the class is reached through the class: SyslogListener.counts. An on line with a mistake that shows only when it runs (an empty from list, a port already taken) stops the program before main.

Part What it does
port NUMBER The UDP port. Without it: 514 for syslog, 162 for traps, 2055 for NetFlow
address IP The one address of this computer to listen on. It stands after the port, or after the kind when no port is given. IPv4 only. Without it the listener opens on every address of the computer
from EXPR Who is listened to: a Device, a list of devices, an IP, a Net, or a list of these. Required
matching STRING Syslog: keeps the messages that hold this text, capitals as written. Traps: keeps the traps whose OID starts with these numbers. Refused on NetFlow
as NAME The name the block gives the event

About from:

  • A packet from anybody else is dropped and counted. To listen to everybody, write from 0.0.0.0/0: it must be written, it is never assumed.
  • A device is known by the address of its inventory line. A device that sends from another of its addresses is dropped. The cure is on the device (set its source interface) or in the program (give the Net).
  • The sender address of a UDP packet can be forged. from is a filter, not a proof. For this reason a change block inside an on block is refused.

About ports: Linux lets only an administrator open a port below 1024, and another program may already hold a port. Both give an error that names the reason and offers a port 5000 higher, such as on syslog port 5514. Two on lines on one port stop the program at the second. When a listener opens it prints one line on standard error, with its kind and port, and says that a silent listener is most often the firewall of the computer. Bogolang does not touch that firewall.

How the blocks run

  • One block runs at a time, in the order the events arrived, while the rest of the program goes on.
  • At most 10,000 events wait for the blocks. More are dropped and counted in .too_many. Memory cannot fill up.
  • An error in a block stops the handling of that one event. It is shown with the event, the listener goes on, and bogo run ends with a failure code.
  • When the program reaches the end of main with a listener open, it keeps listening until Ctrl+C, and says so.

Syslog

The block gets a SyslogEvent: a LogEvent (see logs and topology) with .source: IP and .received: Moment, both always known.

  • Every message is an event, from any maker, in the old form (RFC 3164, with the Cisco variants) and the new one (RFC 5424). A packet with no priority at its head is unreadable.
  • .severity comes from the priority, so it is always a number here. When a Cisco code and the priority give two severities, .severity is the priority's and .code keeps the code as written.
  • .facility is the facility of a Cisco code when the message has one; otherwise the program that wrote the line (sshd), or the standard name of the facility number (local7).
  • .device is the inventory name when the sender is a device of the from list, else the host name written in the message.
  • .time is the time the device wrote, read in the zone of this computer when the message names none. When the message has no readable time it is the arrival time. Times are shown in the zone of the computer.

Traps

The block gets a Trap:

Field Type
.source IP
.device str, the inventory name of the sender, or empty
.oid str, which trap it is, in numbers
.uptime Duration \| None
.values list[SnmpValue]
.received Moment
  • Version 1 and version 2c traps are read. A version 2c inform is answered, so the device does not send it again.
  • When a version 2c SNMP login is stored for the device, the community of the trap must match. If not, the trap is counted as "not from". The community is never shown.
  • Version 3 traps are not in this version.

NetFlow

The block gets a Flow, one per flow record:

Field Type
.exporter IP
.src, .dst IP \| None
.src_port, .dst_port int
.protocol str: "tcp", "udp", "icmp", or the number as text
.bytes Size
.packets int
.start, .end Moment \| None
.in_if, .out_if int, the SNMP numbers of the interfaces
.tos int
.next_hop IP \| None
.received Moment
  • NetFlow version 5, version 9 and IPFIX are read.
  • Versions 9 and IPFIX describe their records in a template the exporter sends from time to time. Records that arrive before their template cannot be read: they are counted in .unreadable.
  • A value the exporter does not send is empty or zero. Nothing is guessed.
  • Many routers export one packet in N. .bytes and .packets are what the exporter wrote: Bogolang does not multiply them.
  • The block runs once per record. Bogolang is a tool to look at flows, not a flow collector for a whole network. sFlow is not in this version.

A program with three listeners

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 and stop_listening

Command Does
listen(duration: Duration \| None = None) waits here while the listeners work: for that long, or until Ctrl+C or stop_listening(). Gives a list[ListenCount], one per listener
stop_listening() closes every listener. May be called from inside a block. Events that still wait are not handled

After listen returns, the listeners are closed; a program that wants to listen again opens them again. At the end of listen(duration) the blocks first finish what already waits.

Member of ListenCount What it counts
.kind, .port which listener
.received packets that arrived
.handled events a block ran for
.not_from packets dropped: the sender is not in from (an IPv6 sender too)
.not_matching events dropped by matching
.unreadable packets, or NetFlow sets of records, that could not be read
.too_many events dropped because the blocks were too slow

Replay and dry run

  • --replay FOLDER: no port is opened. Each listener reads its events from FOLDER/listen/syslog.txt, trap.txt or netflow.txt, passes them through the same from and matching, and runs the blocks. listen returns when every saved event has been handled, whatever its duration. Nothing is dropped for speed. A listener with no saved file stops the program with an error that names the missing file: a misspelt folder must not look like a quiet network.
  • --save-replay FOLDER writes those files from a live run. An event is saved after from and before matching, so a replay can try another matching. A community never enters a saved file.
  • watch and the service checks read saved answers in the same way.
  • --dry: listening changes nothing, so it runs. A webhook or a mail in a block is shown and not sent.
  • The run record gets one line when a listener opens and one when it closes, with its counts; not one line per event.

The example syslog_listener counts the events of two devices, with on syslog port 5514 from devices as e:, and prints those of severity 3 or worse. Its saved file holds eight events, one of them from a sender not in devices. Run with --replay saved, it gave:

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

The times are in the zone of the computer that ran it (UTC+1 here).

Limits

  • No device has sent a syslog message, a trap or a flow to Bogolang. The packets of the tests follow the published forms; real makers bend them.
  • No program has listened on port 514 or 162. The tests use high ports.
  • The answer to an inform was checked with the SNMP package, not by a device that stopped sending.
  • The speed of NetFlow under a real, busy exporter is not measured. Ctrl+C on a listening program was not pressed on a real keyboard.
  • IPv4 and UDP only: no IPv6 listener, no syslog over TCP or TLS, no version 3 trap, no sFlow.

See not proven.