82 lines
7.0 KiB
Markdown
82 lines
7.0 KiB
Markdown
# Network spike monitor
|
|
|
|
Linux (including Linux Mint 22.3/Ubuntu 24.04) or Windows 7 SP1 or newer, with Python 3.8 or newer (use Python 3.8 on Windows 7). No Python packages required. Running the monitor does not require administrator rights.
|
|
|
|
### Linux Mint / Ubuntu setup
|
|
|
|
Install the system commands once:
|
|
|
|
```bash
|
|
sudo apt install python3 iputils-ping traceroute
|
|
```
|
|
|
|
Start monitoring from the repository directory:
|
|
|
|
```bash
|
|
python3 network_monitor.py
|
|
```
|
|
|
|
Linux uses `ping` and unprivileged UDP `traceroute`, with reverse DNS enabled. Windows uses `ping.exe` and `tracert.exe` (ICMP); different probe protocols can receive different responses from firewalls and routers. Linux command output is forced to the C locale for consistent parsing. Missing commands produce an installation hint at startup.
|
|
|
|
For the examples below, use `python3` instead of `python` on Linux. `Start Monitor.cmd` is the Windows launcher.
|
|
|
|
### Windows 7 setup
|
|
|
|
Install [Python 3.8.10](https://www.python.org/downloads/release/python-3810/) using its **Windows installer (32-bit)** or **Windows installer (64-bit)** to match your system. Select **Add Python 3.8 to PATH** during installation, then open a new command prompt. Use the traditional installer listed under Files, not the newer Python install manager. Python 3.8 is the last branch compatible with Windows 7; 3.8.10 is its last release with official Windows installers. Windows 7 must have Service Pack 1 and the updates needed by the Python installer.
|
|
|
|
Check `python --version` reports Python 3.8.x on Windows 7. On newer Windows, a newer supported Python release is fine. The monitor's ping and tracert options, trace cancellation, and logging use Python 3.8-compatible APIs. Python 3.8 is no longer maintained. Compatibility tests run on Python 3.8 on a newer Windows system; a physical Windows 7 installation has not been tested.
|
|
|
|
### Start monitoring
|
|
|
|
Double-click **Start Monitor.cmd**, or run:
|
|
|
|
```powershell
|
|
python network_monitor.py
|
|
```
|
|
|
|
Continuously runs route traces to `1.1.1.1` from startup, one at a time, with a 2-second pause between traces (`--trace-retry`). Tracing continues after capturing a spike and does not wait for ping spikes, qualifying periods, or a cooldown. Windows uses `tracert`; Linux uses `traceroute`. Ctrl+C stops monitoring and cancels the active trace.
|
|
|
|
Pings also run once per second to maintain a healthy latency baseline. A spike is a reply of at least 100 ms, or (after 10 healthy samples) at least 3 times the healthy median AND 40 ms above it. Missing ping replies are logged as loss. Each trace uses the baseline available when it starts; until 10 healthy ping samples exist, traces use only the absolute threshold. Only traces containing measured slow replies are saved.
|
|
|
|
Customize the target, sensitivity, and pause between traces:
|
|
|
|
```powershell
|
|
python network_monitor.py --target 8.8.8.8 --threshold 80 --trace-retry 1
|
|
```
|
|
|
|
`--trace-now` and `--cooldown` remain accepted for compatibility but have no effect. `--required`, `--period`, and `--consecutive` affect ping period summaries only; they do not control tracing.
|
|
|
|
Use `python network_monitor.py --help` for all options. Hostnames resolve to a single IPv4 address at startup so ping and route tracing use the same destination. This measures the path to the selected target; it does not measure every Internet service. Run separate instances with separate `--log-dir` directories to compare destinations.
|
|
|
|
## Preserved evidence
|
|
|
|
Reverse DNS is enabled: raw logs show hop hostnames alongside their IP addresses when available, for example `hop1.subsystem2.spectrum.com [192.0.2.1]`. JSON hop records include both `hostname` and `ip`. Routers without reverse DNS show only an IP; routers that do not reply may show only stars. DNS lookup can make each trace take longer.
|
|
|
|
All logs go to `logs` beside the program by default, or the directory supplied with `--log-dir`:
|
|
|
|
- Only traces that capture a spike are retained. Each has a timestamped `trace_YYYYMMDD_HHMMSS_microseconds.txt` containing the **entire, unmodified stdout and stderr**, plus a matching `.json` with hop timings, command, attempt number, and assessment.
|
|
- While a trace runs, output streams to `.pending.txt`. If it captures a spike, this file becomes the saved `.txt`; otherwise it is deleted, including on normal cancellation without measured spikes. A forced process kill or power failure may leave a temporary `.pending.txt`.
|
|
- `events.jsonl` appends individual spikes/lost replies, period summaries, and brief trace results between runs. Healthy pings appear only in the console and are not written to disk. Discarded attempts do not retain their full output or hop arrays here.
|
|
- Existing logs from earlier versions are left in place. Raw output preserves the command's original bytes.
|
|
|
|
No logs are automatically deleted or rotated. A long-running session can grow large; archive logs after stopping the monitor. Probe intervals are best effort; timeouts may make a cycle longer than the requested interval. Values below 1 ms are represented as 0.5 ms for calculations. Parsing requires the ping reply's `TTL`/`ttl` field and `ms` timings; unrecognized successful replies produce an explicit error.
|
|
|
|
## Interpreting reports
|
|
|
|
A trace is retained when **any individual timed probe at any hop** meets the spike threshold: 100 ms by default, or the relative ping threshold based on the healthy baseline frozen when each trace starts. A single slow probe counts even if the other two replies are fast, downstream hops recover, or the destination never replies. Partial/cancelled traces are also retained if they contain measured slow replies; timeouts alone do not qualify. This captures evidence without claiming the responding router is faulty.
|
|
|
|
Saved JSON includes the individual `spike_probes` with hop, hostname, IP, and RTT. Compact event summaries include `peak_probe_ms`, `spike_limit_ms`, and `spike_probe_count` so you can see why an attempt was kept or discarded. Hop medians and `--hop-jump` are used only for the separate tentative segment assessment, not to decide whether to save a trace.
|
|
|
|
The report looks for an RTT jump that remains elevated through subsequent responding hops, including the destination. It identifies a possible segment, not a proven faulty router. These are round-trip measurements taken at different times, not per-link transit times. Return paths and ICMP prioritization can differ. A spike can end while tracert is still running. Missing hops are not evidence of packet loss in forwarded traffic.
|
|
|
|
Microsoft documents that some routers do not answer traceroute probes: [TRACERT troubleshooting](https://learn.microsoft.com/en-us/troubleshoot/windows-server/networking/trace-route-troubleshoot-tcp-ip-problems).
|
|
|
|
## Verification
|
|
|
|
```powershell
|
|
python -m unittest -v
|
|
python network_monitor.py --target 127.0.0.1 --count 3 --trace-now
|
|
```
|
|
|
|
`--count` ends monitoring after the requested probe count and cancels an active trace. A healthy loopback diagnostic should leave no saved trace files. On Linux, run these commands with `python3`; the integration test runs when both `ping` and `traceroute` are installed.
|