Bitemporal
Every observation carries two time ranges: when it was true on the network (valid time) and when we believed it (transaction time) — canonical Snodgrass §2 shape. “As of T” queries are first-class on both axes.
l2trace
L2 traceroute, point-in-time replay, and an eight-detector audit suite
over a bitemporal CAM/MAC store. Three questions, one fabric, hop by hop.
The TUI in one glance
Section titled “The TUI in one glance”
The OPS dashboard answers “what’s broken right now?” at a glance — and the as-of header at the top means it answers the same question for any T.
What’s the point?
Section titled “What’s the point?”Existing OSS network tools (Netdisco, NetDB, NeDi, LibreNMS) answer “where is MAC X right now?” well. They struggle with three harder questions:
- What L2 path does a frame from A to B take through the fabric — hop by hop, now?
- Same question, but at 14:42 UTC three weeks ago?
- What’s currently inconsistent in this fabric that nobody noticed yet?
l2trace is built around those three questions.
Hop-by-hop
A Postgres recursive CTE walks adjacencies, filters STP-blocking edges, handles MLAG group collapse, passes through virtual-switch placeholders for gear we can’t poll, and terminates cleanly on flood / dead-end / loop.
Multi-source
gNMI streaming + per-vendor SNMP plugins (cisco / arista / juniper / nokia / mikrotik / hp / extreme) + SSH via napalm collect FDB + LLDP + STP + ARP in parallel. The reconciler converges them into one bitemporal log and surfaces cross-source mismatches as disagreements.
Audit suite
Seven operator-facing detectors over the bitemporal log surface real-world bugs: bidirectional LLDP, MAC flap, multi-VLAN MAC, STP-CAM cross-layer, STP root disagreement, ARP IP-collision, port-state vs CAM. → How the matrix is built
Simulation-measured
Bejerano-style parameterized random topologies + synthetic bug injection give per-category detection coverage at 100% in CI. Failing trials are reproducible from the seed alone.
Operator-first
Keyboard-driven Textual TUI with four modes (TRACE / HISTORY / OPS / AUDIT) and an ambient as-of timestamp picker. No browser, no clicking.
How the docs are organized
Section titled “How the docs are organized”These docs follow the Diátaxis framework — four kinds of writing, each answering a different question:
Tutorial
Learning by doing. Start from make up and end with your first
bitemporal traceroute. → Start here
How-to
Task-oriented recipes. “I want to find out who flapped this MAC last week.” Or, “I want to sweep the audit suite end-to-end.” → Run the audit suite · Other how-tos
Reference
Look-up facts. CLI flags, schema columns, event envelope fields. → Reference
Explanation
Why it works that way. The bitemporal model, the traceroute algorithm, the reconciler’s late-arrival rule. → Explanation