netpulse-cli 0.1.1

A zero-config, single-binary network quality monitor with percentile stats, jitter, and MTR-style traceroute
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86

# NetPulse
*Continuous network quality monitor — RTT percentiles, jitter, and burst-loss.*

`netpulse` is a single-binary, zero-config CLI that gives you a continuous, statistical picture of your network quality. It measures not just "is it alive" but "how degraded is it and when."

![TUI demo](https://via.placeholder.com/800x400.png?text=NetPulse+TUI+Preview)

## Features
- **Live TUI**: Real-time sparklines, percentiles, and health coloring.
- **Three Probe Types**:
  - `icmp`: Raw ICMP Echo (like classic `ping`).
  - `tcp`: TCP handshake latency (measures what HTTP clients actually feel).
  - `udp`: Traceroute-style ICMP port-unreachable latency (bypasses ICMP throttling).
- **Advanced Stats**: p50/p90/p95/p99 RTT, RFC 3393 packet jitter, loss percentage, burst-loss streaks, and reorder detection.
- **Multiple Exporters**: Live TUI, newline-delimited JSON (`ndjson`), CSV logging, and a built-in Prometheus `/metrics` HTTP server.
- **Zero Config**: Single binary, no background servers required.

## Installation

**Via Crates.io (Recommended):**
```bash
cargo install netpulse-cli
```
*(The binary installed will simply be called `netpulse`)*.

**Alternatively, via source:**
```bash
git clone https://github.com/rafaelcapeloo/Netpulse
cd netpulse
cargo build --release
```

## Usage

### 1. Traceroute Mode (MTR-style)
Provides a live, updating table of every hop in the network path, similar to `mtr`. It concurrently probes every discovered router along the path.

```bash
sudo ./target/release/netpulse trace google.com --probe icmp
sudo ./target/release/netpulse trace 8.8.8.8 --probe udp
```

### 1. Live TUI (Default)
Monitor Google, Cloudflare, and your local gateway simultaneously using TCP probes (no root required):
```bash
./target/release/netpulse monitor google.com 1.1.1.1 192.168.1.1 --probe tcp
```

Monitor with ICMP or UDP (requires root or `CAP_NET_RAW`):
```bash
sudo ./target/release/netpulse monitor 8.8.8.8 google.com --probe icmp
sudo ./target/release/netpulse monitor 1.1.1.1 8.8.8.8 --probe udp
```

### 2. Prometheus Exporter
Run headless, monitor ICMP, and expose metrics on `http://localhost:9898/metrics`:
```bash
sudo ./target/release/netpulse monitor 1.1.1.1 8.8.8.8 --output text --prometheus 9898
```

### 3. CSV Logging
Append stats every 10 probes to a CSV file while viewing the live TUI:
```bash
./target/release/netpulse monitor google.com --probe tcp --csv results.csv
```

### 4. JSON Streaming
Integrate into other tools via newline-delimited JSON:
```bash
./target/release/netpulse monitor 8.8.8.8 --probe tcp --output json
```

## Configuration
All options can be passed via CLI flags or a `netpulse.toml` file in the current directory:
```toml
interval_ms = 1000
timeout_ms = 3000
window_size = 300
probe_type = "tcp"
```
```bash
./target/release/netpulse monitor 8.8.8.8 -c my_config.toml
```

## License
MIT