18 KiB
18 KiB
Feature Research
Domain: Real-time network monitoring CLI/TUI tools (top-like) Researched: 2026-03-21 Confidence: HIGH
Feature Landscape
Table Stakes (Users Expect These)
Features users assume exist. Missing these = product feels incomplete.
| Feature | Why Expected | Complexity | Notes |
|---|---|---|---|
| Real-time per-connection table | Core promise of "top for networking" -- every competitor (nethogs, iftop, bandwhich, BCC tcptop) has this | MEDIUM | Requires kernel-level data source feeding a TUI table. Refresh rate ~1s is standard |
| Bytes sent/received per connection | Universal metric across all tools (BCC tcptop shows TX_KB/RX_KB, bandwhich shows bandwidth, iftop shows 2s/10s/40s averages) | LOW | Aggregate at the eBPF level to minimize overhead |
| Process correlation (PID + process name) | nethogs and bandwhich made this their core feature; BCC tcptop shows PID/COMM columns. Users expect to answer "which process is using bandwidth?" | MEDIUM | Linux: /proc filesystem or eBPF socket-to-PID mapping. macOS: lsof or libproc. Platform-divergent |
| Local/remote address and port display | Every tool shows LADDR/RADDR. Users need to identify which connection is which | LOW | IPv4 and IPv6 support both needed (BCC tcptop has -4/-6 flags) |
| TCP connection state | ss shows ESTABLISHED/LISTEN/TIME_WAIT etc. Users expect state visibility for debugging | LOW | Available from kernel socket structs via eBPF |
| Sort by column | iftop sorts by source/dest/bandwidth (keys: <, >, 1, 2, 3). htop/btop sort by any column. Unsortable tables are unusable for finding heavy hitters | LOW | Standard TUI table pattern. Default sort by bandwidth (descending) |
| Summary header row | BCC tcptop shows load averages; top/htop show aggregate CPU/memory. tcptop needs aggregate connection count, total bandwidth in/out | LOW | Summarize from per-connection data |
| Filter by port | BCC tcptop filters by PID but not port natively. iftop uses BPF filter expressions. Port filtering is the most common "show me only HTTPS traffic" workflow | LOW | CLI flag --port and/or runtime filter |
| Filter by process (PID or name) | BCC tcptop has -p PID. nethogs groups by process. Essential for "what is Firefox doing?" | LOW | CLI flag --pid/--process and/or runtime filter |
| Configurable refresh interval | BCC tcptop accepts interval arg (default 1s). iftop refreshes every 2s. Users need control over update frequency | LOW | CLI flag, default 1 second |
| Graceful privilege handling | All eBPF/pcap tools need root. nethogs supports capability-based non-root. Must not crash cryptically without root | LOW | Check privileges at startup, emit clear error with instructions |
| CLI help and man page | Standard expectation for any Unix tool | LOW | clap auto-generates --help; man page is a separate artifact |
| TCP and UDP support | PROJECT.md explicitly requires both. Most tools are TCP-only (BCC tcptop, nethogs) which is a gap. ss shows both | HIGH | UDP is connectionless -- need to synthesize "connections" from src/dst tuples with timeouts. Significant design challenge |
| Keyboard quit (q/Ctrl-C) | Universal TUI convention | LOW | Trivial |
Differentiators (Competitive Advantage)
Features that set the product apart. Not required, but valuable.
| Feature | Value Proposition | Complexity | Notes |
|---|---|---|---|
| Per-connection RTT/latency estimates | No CLI tool shows RTT per connection in real-time. ss can show RTT but only as a snapshot, not live. NetworkLatencyView (Windows-only) does this passively. This is tcptop's strongest differentiator | HIGH | TCP: measure via eBPF tracepoints on ACK round-trips. UDP: extremely hard (no built-in ACK), likely scope-reduce to TCP-only RTT |
| CSV logging mode | Most tools are interactive-only. BCC tcptop has -C (no-clear) for scriptable output but not structured CSV. bandwhich has -r (raw) mode. Structured CSV export for offline analysis is uncommon and valuable for SREs | MEDIUM | --log output.csv flag. Write header + rows periodically. Must work alongside TUI or as headless mode |
| Cross-platform (Linux + macOS) | nethogs is Linux-only for process correlation. bandwhich supports macOS but uses pcap (not eBPF). BCC tcptop is Linux-only. True cross-platform with eBPF on Linux + DTrace/alternative on macOS is rare | HIGH | Architecture must abstract the data collection backend. macOS eBPF is non-existent; need DTrace, Network Extension, or libpcap+lsof fallback |
| Packet count per connection | BCC tcptop only shows bytes, not packets. Packet count reveals small-packet storms, SYN floods, DNS chattiness | LOW | Count in eBPF programs alongside byte counters |
| Bandwidth rate display (not just cumulative bytes) | iftop shows 2s/10s/40s rolling averages. BCC tcptop shows cumulative KB only. Rate-over-time is more actionable than cumulative totals | MEDIUM | Calculate delta between intervals. Show as KB/s or MB/s. Consider short and long rolling windows |
| Reverse DNS resolution (with toggle) | iftop and bandwhich resolve IPs to hostnames. Useful for identifying services. Must be toggleable (resolution is slow and noisy) | MEDIUM | Background async DNS lookups. Toggle via -n/--no-resolve flag and runtime key. Cache results |
| Runtime filter/search | RustNet and some TUI tools support '/' to search/filter live. iftop has 'l' for pattern filter. Powerful for narrowing view without restarting | MEDIUM | Vim-style '/' key to enter filter mode. Filter by IP, port, process name. Regex or simple substring |
| Interface selection | iftop and bandwhich accept -i interface. On multi-homed servers, users need to pick which NIC to watch | LOW | --interface flag. Default to all or auto-detect primary |
| Color-coded bandwidth (heat map style) | btop uses color gradients for resource usage. Visually scanning for heavy connections is faster with color cues | LOW | Ratatui supports styled text. Color by bandwidth percentile |
| Freeze/pause display | htop supports space to tag, and most TUIs allow pausing updates. Useful for inspecting a specific moment | LOW | 'p' key to pause/resume updates. Display "PAUSED" indicator |
| Connection duration / age | No common CLI tool shows how long a connection has been alive. Useful for finding stale connections | MEDIUM | Track first-seen timestamp per connection tuple. Display as elapsed time |
Anti-Features (Commonly Requested, Often Problematic)
Features that seem good but create problems.
| Feature | Why Requested | Why Problematic | Alternative |
|---|---|---|---|
| Layer 7 / application protocol inspection (HTTP, DNS, TLS) | Users want to see "which URLs are being fetched" | Massive scope expansion. Requires deep packet inspection, TLS decryption is ethically/legally fraught, completely different tool category (wireshark/mitmproxy territory) | Stay at L4. Show port numbers; users can infer protocol (443=HTTPS, 53=DNS). Label well-known ports in display |
| Built-in graphing / sparklines | btop has beautiful graphs. Seems like a natural addition | Graphs consume terminal real estate that is better used for the connection table. A network tool's primary value is the table. Graphs add complexity without proportional value for a per-connection tool | CSV export for offline graphing in dedicated tools (gnuplot, Excel, Grafana). If demand is high, consider a minimal aggregate bandwidth sparkline in the header only |
| JSON output format | "JSON is more modern than CSV" | For v1, CSV is simpler to implement, universally importable, and sufficient. JSON adds complexity to the output pipeline and is harder to stream (need JSON Lines or array wrapping) | CSV for v1. JSON Lines (JSONL) could be a v2 addition if users request it |
| Windows support | "Why not Windows?" | Windows has no eBPF, no DTrace. Would need entirely separate ETW-based backend. Three platform backends is untenable for a small project | Linux + macOS only. Windows users can use WSL2 (which runs Linux eBPF) |
| Historical data storage / database | "I want to see what happened yesterday" | Turns a monitoring tool into a time-series database. Massive scope creep. vnStat already fills this niche | CSV logging covers offline analysis. Users can pipe to InfluxDB/Prometheus if they want historical storage |
| Promiscuous mode / sniffing other hosts' traffic | iftop supports -p for promiscuous mode | tcptop's value is per-process correlation on the local host. Promiscuous mode captures others' traffic but cannot correlate to local processes. Different use case entirely | Out of scope. Users wanting network-wide visibility should use iftop, ntopng, or a proper network tap |
| Real-time alerting / thresholds | "Alert me when bandwidth exceeds X" | Adds notification system, threshold configuration, state machine complexity. Monitoring tools observe; alerting tools alert | Users can script alerts on top of CSV output or use proper alerting systems |
| UDP RTT estimation | "You show RTT for TCP, why not UDP?" | UDP has no built-in acknowledgment mechanism. Any RTT estimate would be application-protocol-specific (e.g., DNS query-response timing) and unreliable for general UDP | Show RTT column as N/A for UDP connections. Document limitation clearly. TCP RTT is the valuable metric |
Feature Dependencies
[eBPF/kernel data collection backend]
├──requires──> [Per-connection bytes/packets counting]
│ ├──enables──> [Bandwidth rate calculation]
│ ├──enables──> [Sort by bandwidth]
│ └──enables──> [CSV logging]
├──requires──> [Process correlation (PID/name)]
│ └──enables──> [Filter by process]
├──requires──> [TCP state tracking]
└──requires──> [RTT measurement (TCP only)]
[TUI framework (Ratatui)]
├──requires──> [Connection table display]
│ ├──enables──> [Column sorting]
│ ├──enables──> [Runtime filter/search]
│ ├──enables──> [Color-coded bandwidth]
│ └──enables──> [Freeze/pause]
├──requires──> [Summary header]
└──requires──> [Keyboard navigation]
[Platform abstraction layer]
├──requires──> [Linux eBPF backend]
└──requires──> [macOS backend (DTrace/libpcap+lsof)]
[CLI argument parsing (clap)]
├──enables──> [--port filter]
├──enables──> [--pid/--process filter]
├──enables──> [--interface selection]
├──enables──> [--log CSV output]
└──enables──> [--interval refresh rate]
[Reverse DNS resolution]
└──conflicts-with──> [Low-latency display updates] (must be async/background)
[UDP "connection" synthesis]
└──requires──> [Timeout-based tuple tracking] (no kernel state for UDP flows)
Dependency Notes
- All data display requires eBPF backend: The kernel data collection is the foundation. Nothing works without it. Must be built and validated first.
- TUI and data collection are independent: TUI can be developed with mock data while eBPF backend is built separately.
- Platform abstraction must come early: Architecture decision that affects every data path. Defining the trait/interface between backends and display is a prerequisite for parallel Linux/macOS work.
- Reverse DNS conflicts with responsiveness: DNS lookups can take 100ms+. Must be fully async with caching, or the TUI will stutter. Toggle (--no-resolve) is essential.
- UDP connection synthesis is independent complexity: Unlike TCP where the kernel tracks connections, UDP requires userspace flow tracking with configurable idle timeouts. This is a separate design problem from the core eBPF work.
- CSV logging can work headless or alongside TUI: Design as a separate output sink that receives the same data stream as the TUI, not as a TUI feature.
MVP Definition
Launch With (v1)
Minimum viable product -- what's needed to validate the core "top for network connections" concept.
- Linux eBPF backend with per-connection TCP stats (bytes in/out, packets, state) -- the foundation
- Process correlation (PID + command name) on Linux -- core differentiator vs raw iftop
- Ratatui TUI with sortable connection table -- the user-facing product
- Summary header (total connections, aggregate bandwidth) -- provides context
- Sort by any column (default: bandwidth descending) -- essential for finding heavy hitters
- Filter by port (--port) and process (--pid) via CLI flags -- minimum viable filtering
- Configurable refresh interval (--interval, default 1s) -- basic customization
- Graceful root/privilege check with clear error message -- must not confuse users
- --help via clap -- table stakes for any CLI tool
Add After Validation (v1.x)
Features to add once core TCP monitoring on Linux is working and validated.
- TCP RTT/latency per connection -- strongest differentiator, add once core metrics are stable
- Bandwidth rate display (KB/s with rolling window) -- upgrade from cumulative bytes
- CSV logging mode (--log output.csv) -- enables offline analysis use case
- Runtime filter/search ('/' key) -- productivity boost for power users
- Reverse DNS resolution with toggle (-n) -- nice-to-have, async implementation needed
- UDP flow tracking -- significant complexity, add after TCP is solid
- Pause/freeze display ('p' key) -- low effort, high utility
- Color-coded bandwidth cells -- visual polish
- Connection duration/age -- useful debugging info
Future Consideration (v2+)
Features to defer until product-market fit is established.
- macOS backend (DTrace or libpcap+lsof) -- high complexity, different kernel APIs entirely
- IPv6 support -- BCC tcptop has -4/-6 flags; important but can defer if v1 focuses on IPv4
- Interface selection (--interface) -- multi-NIC servers need this eventually
- JSON Lines output format -- if CSV proves insufficient for structured consumers
- Packaging (Homebrew, cargo install, .deb/.rpm) -- distribution, not functionality
- Man page -- documentation polish
Feature Prioritization Matrix
| Feature | User Value | Implementation Cost | Priority |
|---|---|---|---|
| Per-connection table with bytes/packets | HIGH | MEDIUM | P1 |
| Process correlation (PID/name) | HIGH | MEDIUM | P1 |
| TCP connection state | HIGH | LOW | P1 |
| Sort by column | HIGH | LOW | P1 |
| Summary header | MEDIUM | LOW | P1 |
| Filter by port (CLI) | HIGH | LOW | P1 |
| Filter by process (CLI) | HIGH | LOW | P1 |
| Refresh interval config | MEDIUM | LOW | P1 |
| Privilege handling | MEDIUM | LOW | P1 |
| TCP RTT/latency | HIGH | HIGH | P2 |
| Bandwidth rate (KB/s) | HIGH | MEDIUM | P2 |
| CSV logging | MEDIUM | MEDIUM | P2 |
| Runtime search/filter | MEDIUM | MEDIUM | P2 |
| UDP flow tracking | MEDIUM | HIGH | P2 |
| Reverse DNS | MEDIUM | MEDIUM | P2 |
| Pause/freeze | MEDIUM | LOW | P2 |
| Color-coded cells | LOW | LOW | P2 |
| Connection age | MEDIUM | MEDIUM | P2 |
| macOS backend | MEDIUM | HIGH | P3 |
| IPv6 support | MEDIUM | MEDIUM | P3 |
| Interface selection | LOW | LOW | P3 |
| JSON Lines output | LOW | MEDIUM | P3 |
| Packaging/distribution | MEDIUM | MEDIUM | P3 |
Priority key:
- P1: Must have for launch (Linux TCP monitoring with TUI)
- P2: Should have, add iteratively (differentiators and polish)
- P3: Nice to have, future consideration (platform expansion and distribution)
Competitor Feature Analysis
| Feature | BCC tcptop | nethogs | iftop | bandwhich | ss | Our Approach |
|---|---|---|---|---|---|---|
| Per-connection table | Yes (PID/COMM/LADDR/RADDR/TX/RX) | Per-process only (not per-connection) | Per host-pair (not per-process) | Per-process, per-connection, per-remote | Snapshot only (not live) | Per-connection with PID -- combines best of tcptop + nethogs |
| Process correlation | Yes (PID/COMM) | Yes (core feature) | No | Yes | Yes (with -p flag) | Yes, via eBPF socket-to-PID mapping |
| TCP state | No | No | No | No | Yes (core feature) | Yes -- unique among live monitoring tools |
| RTT/latency | No | No | No | No | Yes (snapshot only) | Yes, live -- primary differentiator |
| UDP support | No (TCP only) | Partial | Yes | Yes | Yes | Yes (synthesized flows with timeout) |
| Sort | No (static output) | By sent/received | By src/dst/bandwidth | No interactive sort | No (CLI output) | Sort by any column, keyboard driven |
| Filtering | -p PID, -4/-6 | No | BPF filter expressions | No | State/protocol filters | Port, PID, process name (CLI + runtime) |
| CSV/structured export | No (use -C for scriptable) | Tracing mode | No | -r raw mode | No | --log CSV with headers |
| Cross-platform | Linux only | Linux only (macOS partial) | Linux + BSD | Linux, macOS, Windows | Linux only | Linux (v1), macOS (v2) |
| Bandwidth rate | No (cumulative KB) | Yes (KB/s) | Yes (2s/10s/40s avg) | Yes (current rate) | No | Yes (rolling window rate) |
| DNS resolution | No | No | Yes (default on) | Yes (default on) | No | Yes (off by default, toggle on) |
| TUI framework | None (plain text) | ncurses | ncurses | crossterm | None (CLI) | Ratatui (modern Rust TUI) |
| eBPF based | Yes | No (pcap/proc) | No (pcap) | No (pcap/proc) | No (netlink) | Yes -- low overhead, kernel-level accuracy |
| Color/theming | No | No | No | Basic | No | Yes (Ratatui supports full color) |
Sources
- nethogs GitHub -- mature Linux per-process bandwidth monitor
- bandwhich GitHub -- Rust cross-platform bandwidth monitor (passive maintenance)
- BCC tcptop man page -- eBPF TCP monitoring tool from BCC suite
- iftop man page -- interface bandwidth monitor by host pair
- ss man page -- socket statistics snapshot tool
- bpftop Netflix announcement -- Rust/eBPF/Ratatui tool (validates stack choice)
- Brendan Gregg on BCC tcptop -- original tcptop design rationale
- htop/btop comparison -- TUI interaction patterns and best practices
Feature research for: real-time network monitoring CLI/TUI tools Researched: 2026-03-21