netpulse-cli 0.1.0

A zero-config, single-binary network quality monitor with percentile stats, jitter, and MTR-style traceroute
Documentation

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

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):

cargo install netpulse-cli

(The binary installed will simply be called netpulse).

Alternatively, via source:

git clone https://github.com/yourusername/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.

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):

./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):

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:

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:

./target/release/netpulse monitor google.com --probe tcp --csv results.csv

4. JSON Streaming

Integrate into other tools via newline-delimited JSON:

./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:

interval_ms = 1000
timeout_ms = 3000
window_size = 300
probe_type = "tcp"

./target/release/netpulse monitor 8.8.8.8 -c my_config.toml

License

MIT