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
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.
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
forthe watch runs until Ctrl+C, and Ctrl+C ends the program. Withfor 5minthe watch ends by itself and the program goes on.every 2s for 5sgives three readings and lasts 5 seconds: a turn never starts once the time is up.for 0sgives 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
everyblock during 3 minutes. One false turn starts the count again.for 0sraises on the first true turn. - A raised alert clears on the first false turn.
pergives 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 afterperis aDevice, a text, an address or an interface.Gi1/0/24andGigabitEthernet1/0/24are one memory. The devicer1and the text"r1"are two.asnames anAlert, 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 |
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.
fromis a filter, not a proof. For this reason achangeblock inside anonblock 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 runends with a failure code. - When the program reaches the end of
mainwith 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.
.severitycomes from the priority, so it is always a number here. When a Cisco code and the priority give two severities,.severityis the priority's and.codekeeps the code as written..facilityis 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)..deviceis the inventory name when the sender is a device of thefromlist, else the host name written in the message..timeis 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.
.bytesand.packetsare 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
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 fromFOLDER/listen/syslog.txt,trap.txtornetflow.txt, passes them through the samefromandmatching, and runs the blocks.listenreturns 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 FOLDERwrites those files from a live run. An event is saved afterfromand beforematching, so a replay can try anothermatching. A community never enters a saved file.watchand the service checks read saved answers in the same way.--dry: listening changes nothing, so it runs. Awebhookor amailin 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.