This page covers two groups of commands. The first reads log events from a device or from a saved file. The second reads the CDP and LLDP neighbours of devices and draws the topology they make.
Both only read. A device is reached through a read-only session, as on the
devices page. With bogo run --replay FOLDER the saved outputs are read and
nothing connects (see the tools).
Log events
| Command | Gives |
|---|---|
logs(d: Device, zone: str = 'local') |
list[LogEvent], read from the device |
read_logs(path: str, zone: str = 'local') |
list[LogEvent], read from a saved file |
logs(d) sends one command. On a Cisco device it is show logging. On a Junos device it is
show log messages | no-more. A Junos device that refuses the command, for example because the
user has no right to read the file, stops the program with a sentence that names the device and
the command.
read_logs(path) reads a file saved from a device or from a syslog server. Nothing in the file
raises an error: a line that cannot be read is skipped.
What a line must hold
- A Cisco line is an event only when it holds a message code such as
%LINK-3-UPDOWN:. ASA codes are read the same way. - A line in the usual syslog form (
Nov 18 07:36:33 host program[123]: text) is an event with no severity. A Junos file and a Linux file cannot be told apart, so both are read this way. When a Junos line carries its priority (%DAEMON-5-RPD_RT_HWM_NOTICE:), the severity is read from it. - A line
last message repeated N timesis skipped.
The LogEvent
| Field | Type | What it holds |
|---|---|---|
.time |
Moment \| None |
The time the device wrote; None when the line has none (an uptime stamp) |
.device |
str |
The device name: the one of logs(d), or the host written on the line of a server file |
.facility |
str |
On Cisco the part before the severity (LINK); on Junos and Linux the program (rpd, sshd) |
.severity |
int \| None |
0 (emergency) to 7 (debug); None when the line does not say |
.mnemonic |
str |
The last part of the code (UPDOWN) |
.code |
str |
The code as written, without the %: LINK-3-UPDOWN, AUTH-6, UI_COMMIT |
.message |
str |
The text after the code |
.raw |
str |
The whole line |
Time and zone
A device often writes no year and no zone.
- The zone is the one given with
zone=. It takes"local"(the zone of the computer),"UTC"or a full name such as"America/Bogota". A wrong name stops the program before anything is contacted. - A zone written on the line is used when Bogolang knows it. Otherwise the zone given is used.
- A stamp with no year takes the current year, or the year before when the current one would put the event more than a day in the future.
- In a file from a syslog server, the device's own time is used when the line has one, else the server's.
A device may write its log times in UTC while its clock shows local time. Bogolang cannot see
this from the lines, because they carry no zone. Then logs(d, zone="UTC") is the right call.
On IOS the line service timestamps log datetime localtime show-timezone on the device removes
the doubt.
An example
A file saved from a syslog server:
Nov 18 07:30:02 192.0.2.1 120: Nov 18 07:30:01.512: %LINK-3-UPDOWN: Interface GigabitEthernet1/0/24, changed state to down
Nov 18 07:30:03 192.0.2.1 121: Nov 18 07:30:02.514: %LINEPROTO-5-UPDOWN: Line protocol on Interface GigabitEthernet1/0/24, changed state to down
Nov 18 07:31:10 192.0.2.2 88: Nov 18 07:31:09: %SYS-5-CONFIG_I: Configured from console by admin on vty0 (198.51.100.7)
Nov 18 07:36:33 edge-fw1 sshd[812]: Accepted publickey for admin from 198.51.100.7 port 51515
this line is not a log event
events: list[LogEvent] = read_logs("syslog.log", zone="UTC")
for e in events:
print(e.time, e.device, e.code, e.severity, e.message)
table(events, ["time", "device", "code", "message"])
The output:
2026-11-18 07:30:01 UTC 192.0.2.1 LINK-3-UPDOWN 3 Interface GigabitEthernet1/0/24, changed state to down
2026-11-18 07:30:02 UTC 192.0.2.1 LINEPROTO-5-UPDOWN 5 Line protocol on Interface GigabitEthernet1/0/24, changed state to down
2026-11-18 07:31:09 UTC 192.0.2.2 SYS-5-CONFIG_I 5 Configured from console by admin on vty0 (198.51.100.7)
2026-11-18 07:36:33 UTC edge-fw1 None Accepted publickey for admin from 198.51.100.7 port 51515
time device code message
----------------------- --------- ------------------ -----------------------------------------------------------------------
2026-11-18 07:30:01 UTC 192.0.2.1 LINK-3-UPDOWN Interface GigabitEthernet1/0/24, changed state to down
2026-11-18 07:30:02 UTC 192.0.2.1 LINEPROTO-5-UPDOWN Line protocol on Interface GigabitEthernet1/0/24, changed state to down
2026-11-18 07:31:09 UTC 192.0.2.2 SYS-5-CONFIG_I Configured from console by admin on vty0 (198.51.100.7)
2026-11-18 07:36:33 UTC edge-fw1 Accepted publickey for admin from 198.51.100.7 port 51515
The fourth line has no Cisco code. It is an event with no severity, and its facility is
sshd. The fifth line is skipped.
Filtering and counting
Filtering is plain Bogolang. Because .severity may be None, the check refuses
e.severity <= 3 until the program says what an unknown severity means:
events: list[LogEvent] = read_logs("syslog.log")
serious: list[LogEvent] = [e for e in events if e.severity is not None and e.severity <= 3]
flaps: list[LogEvent] = [e for e in events if e.mnemonic == "UPDOWN"]
print(len(serious), "serious,", len(flaps), "up or down")
Inside an on syslog block the severity is always a number: a syslog packet always carries
one. That block gets a SyslogEvent, described on the
watching and listening page.
SyslogEvent
A SyslogEvent is a LogEvent with two more fields, both always known:
| Field | Type | What it holds |
|---|---|---|
.source |
IP |
The address the packet came from |
.received |
Moment |
When it arrived, by the clock of this computer |
An event read from a file or from show logging is a plain LogEvent. So a table of such
events keeps its eight columns.
Neighbours
| Command | Gives |
|---|---|
neighbors(d: Device) |
list[Neighbor], one entry per neighbour and local port, sorted by local port |
It opens one session and sends the CDP and LLDP commands the platform has:
| Platform | Commands |
|---|---|
ios, iosxe, nxos |
show cdp neighbors detail, show lldp neighbors detail |
aireos |
show cdp neighbors detail |
junos |
show lldp neighbors detail \| display xml |
asa |
none: neighbors refuses the device with a sentence that names the platforms that work |
A neighbour seen by both protocols is listed once. Its source is then "cdp+lldp": the CDP
values come first and LLDP fills the gaps. A protocol that is off on the device gives no
neighbours. It is not an error.
| Field | Type | What it holds |
|---|---|---|
.device |
str |
The local device |
.local_port |
Intf |
The local port |
.name |
str |
The neighbour's name, as it announces it |
.port |
str |
The neighbour's port, as it announces it |
.platform |
str |
The neighbour's platform, when announced |
.ip |
IP \| None |
Its management address, when announced |
.source |
str |
"cdp", "lldp" or "cdp+lldp" |
sw1: Device = Device(name="core-sw1", ip=192.0.2.1, platform="iosxe")
for n in neighbors(sw1):
print(n.local_port, n.name, n.port, n.platform, n.ip, n.source)
Run with --replay on saved outputs, it printed:
Gi1/0/1 access-sw2.example.net GigabitEthernet1/0/49 cisco C9300-48P 192.0.2.2 cdp
Gi1/0/48 edge-rt1 GigabitEthernet0/0/0 cisco ISR4331/K9 192.0.2.254 cdp+lldp
An LLDP neighbour that announces no system name is skipped. A local port whose name Bogolang cannot read is skipped too.
Topology
| Command | Gives |
|---|---|
topology(devices: list[Device], parallel: int = 10) |
Topology |
topology reads the neighbours of every device, parallel at a time. A device that fails does
not stop the others: it goes to .failed with the reason.
| Member | What it gives |
|---|---|
.nodes |
list[str]: every name seen, inventory devices and neighbours outside it |
.links |
list[Link]: each with .a, .a_port, .b, .b_port |
.failed |
list[tuple[str, str]]: the name and the reason of each device that could not be read |
.neighbors_of(name: str) |
list[str]: the names one cable away |
.path(a: str, b: str) |
list[str]: the names from a to b with the fewest hops, both ends included; [] when there is no way |
.save(path: str) |
writes .json, .csv or .dot, chosen by the file ending |
How the links are built:
- A cable seen from both ends is one link. Two cables between the same two devices are two links.
- A neighbour name is matched to an inventory name without its domain part and without regard
to capitals:
access-sw2.example.netisaccess-sw2. - When a neighbour announces its port in a form Bogolang cannot read, the two ends stay two one-sided links.
- A name asked of
.pathor.neighbors_ofthat is not a node stops the program with an error.
sw1: Device = Device(name="core-sw1", ip=192.0.2.1, platform="iosxe")
sw2: Device = Device(name="access-sw2", ip=192.0.2.2, platform="iosxe")
t: Topology = topology([sw1, sw2])
print(t)
for k in t.links:
print(k.a, k.a_port, "--", k.b, k.b_port)
print(t.path("access-sw2", "edge-rt1"))
print(t.failed)
t.save("topology.dot")
On the same saved outputs:
Topology(3 nodes, 2 links, 0 failed)
access-sw2 Gi1/0/49 -- core-sw1 Gi1/0/1
core-sw1 Gi1/0/48 -- edge-rt1 Gi0/0/0
['access-sw2', 'core-sw1', 'edge-rt1']
[]
edge-rt1 is not in the list given to topology. It is a node because core-sw1 sees it. The
file topology.dot:
graph topology {
"access-sw2";
"core-sw1";
"edge-rt1";
"access-sw2" -- "core-sw1" [taillabel="Gi1/0/49", headlabel="Gi1/0/1"];
"core-sw1" -- "edge-rt1" [taillabel="Gi1/0/48", headlabel="Gi0/0/0"];
}
A .dot file opens in Graphviz and in several drawing tools. Bogolang does not draw the picture
itself.
.path counts hops in what CDP and LLDP see: cables, not routing. It is not the path a packet
takes. For that, see the route lookup on the
planning, routes and access lists page.
Limits
- Log events, neighbours and topology have read one IOS-XE switch and two virtual Junos switches. Other releases and platforms may write time stamps and port names in forms the tests do not have.
- NX-OS and AireOS devices were never read for real. Their outputs in the tests were written for the tests. See not proven.
- An NX-OS neighbour often carries a serial number in its name. Such a name does not match the inventory and becomes an extra node.