fb8463507c
All 3 phases shipped (8 plans, 29 requirements). macOS backend dropped from v1 scope. Archives created in .planning/milestones/. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
84 lines
4.0 KiB
Markdown
84 lines
4.0 KiB
Markdown
# tcptop
|
|
|
|
## What This Is
|
|
|
|
A polished command-line utility that provides a real-time, `top`-like TUI for layer 4 (TCP/UDP) network statistics. It shows per-connection data — bytes, packets, latency, and state — in a sortable table with an aggregate summary header. It also supports CSV logging for offline analysis. Built in Rust using eBPF for kernel-level connection tracing on Linux.
|
|
|
|
## Core Value
|
|
|
|
Live, accurate, per-connection network visibility from the terminal — the network equivalent of `top`.
|
|
|
|
## Requirements
|
|
|
|
### Validated
|
|
|
|
- [x] eBPF-based kernel-level data collection for accurate, low-overhead tracing — v1.0
|
|
- [x] Per-connection stats: bytes in/out, packets in/out, RTT/latency estimates, connection state — v1.0
|
|
- [x] TCP and UDP protocol support — v1.0
|
|
- [x] Real-time TUI with summary header (total connections, aggregate bandwidth) and sortable connection table — v1.0
|
|
- [x] Filter by port (e.g., `--port 443`) — v1.0
|
|
- [x] Filter by process (PID or process name) — v1.0
|
|
- [x] CSV file logging mode (`--log output.csv`) — v1.0
|
|
- [x] Installable distribution (cargo install, .deb/.rpm) — v1.0
|
|
- [x] Man page / CLI help documentation — v1.0
|
|
- [x] Test coverage for core functionality — v1.0
|
|
|
|
### Active
|
|
|
|
(None — all v1 requirements shipped. Define next milestone requirements with `/gsd:new-milestone`.)
|
|
|
|
### Out of Scope
|
|
|
|
- GUI or web interface — this is a terminal tool
|
|
- Layer 7 / application protocol inspection — stays at L4
|
|
- Historical data storage or built-in graphing — CSV export covers offline analysis
|
|
- Windows support — Linux only for v1
|
|
- macOS support — PKTAP packet capture provides degraded data fidelity vs Linux eBPF; not worth the complexity for v1
|
|
- JSON log format — CSV is sufficient for v1
|
|
|
|
## Context
|
|
|
|
- Shipped v1.0 with 2,846 LOC Rust across 3 crates (tcptop, tcptop-ebpf, tcptop-common)
|
|
- Tech stack: Aya (eBPF), Ratatui (TUI), Tokio (async), clap (CLI), serde/csv (logging)
|
|
- 5 eBPF kernel programs: kprobes for tcp/udp send/recv + tracepoint for TCP state changes
|
|
- 15 automated tests covering aggregator, filtering, and CSV output
|
|
- Platform abstraction trait (`NetworkCollector`) exists for future cross-platform work
|
|
- macOS support dropped for v1 — PKTAP would provide degraded data fidelity vs eBPF
|
|
|
|
## Constraints
|
|
|
|
- **Privileges**: Requires root/elevated permissions for kernel tracing — must handle gracefully when not root
|
|
- **Platform**: Linux-only for v1. Platform abstraction trait exists for future cross-platform work
|
|
- **Language**: Rust (preferred for performance, safety, and eBPF ecosystem)
|
|
- **Overhead**: Must be low-impact on the system being observed — no heavy polling
|
|
|
|
## Key Decisions
|
|
|
|
| Decision | Rationale | Outcome |
|
|
|----------|-----------|---------|
|
|
| Rust as implementation language | Best eBPF ecosystem (Aya), performance, safety | Confirmed — v1.0 |
|
|
| eBPF for data collection | Most accurate, lowest overhead kernel-level tracing | Confirmed — v1.0 |
|
|
| CSV for log format | Simple, universal, easy to import into analysis tools | Confirmed — v1.0 |
|
|
| Summary + table TUI layout | Matches `top` mental model, provides both overview and detail | Confirmed — v1.0 |
|
|
| macOS dropped for v1 | PKTAP provides degraded fidelity vs eBPF; not worth complexity | Confirmed — v1.0 |
|
|
|
|
## Evolution
|
|
|
|
This document evolves at phase transitions and milestone boundaries.
|
|
|
|
**After each phase transition** (via `/gsd:transition`):
|
|
1. Requirements invalidated? → Move to Out of Scope with reason
|
|
2. Requirements validated? → Move to Validated with phase reference
|
|
3. New requirements emerged? → Add to Active
|
|
4. Decisions to log? → Add to Key Decisions
|
|
5. "What This Is" still accurate? → Update if drifted
|
|
|
|
**After each milestone** (via `/gsd:complete-milestone`):
|
|
1. Full review of all sections
|
|
2. Core Value check — still the right priority?
|
|
3. Audit Out of Scope — reasons still valid?
|
|
4. Update Context with current state
|
|
|
|
---
|
|
*Last updated: 2026-03-22 after v1.0 milestone — all 29 requirements shipped, 3 phases complete*
|