What is l2trace?
l2trace is an open-source tool that gathers CAM/MAC-address tables from network switches and stores them so you can answer path-shaped and time-shaped questions about your switching fabric:
- Where is MAC
aa:bb:cc:11:22:33? — easy, every tool does this. - Which trunks does a frame from host A to host B traverse, right now?
- Same question, but at 14:42 UTC three weeks ago?
- We rolled out new firmware on sw7 last night. What MACs disappeared between 21:00 and 22:00, and where did they reappear?
The headline distinguishing feature is bitemporality: every row in the
observation log carries two time ranges — when the fact was true on the
network (valid_during) and when our system believed it (recorded_during).
That second range is the one that makes belief revision an explicit event
instead of a silent overwrite. See Why bitemporal?
for the depth.
Who is this for?
Section titled “Who is this for?”Network operators who:
- Live in terminals. The primary interface is a keyboard-driven Textual TUI, not a web app. (Browse some screenshots.)
- Run multi-vendor fabrics (Cisco, Arista, Juniper, Nokia — gNMI streaming
is the primary collection path; SNMP polling and SSH (
show-command scraping via napalm) ship today as backstops for switches without gNMI). - Want to investigate, not just observe. Disagreement detection, quarantine events, and audit-time queries exist because chasing intermittent forwarding bugs at 03:00 is the worst.
What l2trace is deliberately not
Section titled “What l2trace is deliberately not”- Not a CMDB. Devices, ports, and adjacencies are inferred from telemetry, not configured by hand. No “click-through provisioning” workflow.
- Not a NetFlow / sFlow collector. L2 traceroute uses the CAM/MAC table
- STP state + LLDP adjacency — flow records are out of scope.
- Not a graphing / dashboarding tool. Prometheus metrics are emitted but the dashboards live elsewhere (Grafana, your existing observability stack).
Status
Section titled “Status”Alpha. Shipped + tested today:
- Bitemporal schema (mac_observation + adjacency tables, both axes)
- Reconciler + compactor (NATS JetStream consumer, late-arrival rule, LiveSet integrity)
- gNMI streaming collector (OpenConfig FDB + LLDP + chassis-id)
- SNMP polling collector (Q-BRIDGE-MIB + LLDP-MIB + chassis-id)
- SSH show-command collector via napalm (IOS-XE, NX-OS, with extensible driver registry for EOS/JunOS)
- Cross-source peer resolution via the
DeviceIdentifiedevent - L2 traceroute recursive-CTE with MLAG-collapse + STP-forwarding filter
- Bidirectional adjacency audit
- TUI: TRACE / HISTORY / OPS / AUDIT screens with ambient as-of picker
- URI-keyed secrets layer (env / file / literal backends) for collector credentials
On the roadmap:
- NETCONF collector as a fourth source
- Vaultwarden + HashiCorp Vault secrets backends
- Active validation (probe injection + sFlow/ERSPAN confirmation)
- HTTP read-API and web UI (the TUI remains the primary interface)