Skip to content

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

bogolang
FR

← Documentation

Logs and topology

Log events and the topology from neighbours.

All documentation pages

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 times is 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
Bogolang
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:

Bogolang
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"
Bogolang
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.net is access-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 .path or .neighbors_of that is not a node stops the program with an error.
Bogolang
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.