Ping Reliability Monitor

A production-quality Python CLI tool for long-running network reliability measurements. Ping Reliability Monitor continuously pings a target host, records every sample to a crash-resistant CSV log, shows live latency trends, and exports summary analytics to Excel and PNG charts.

It is designed for practical diagnostics such as measuring ISP instability, Wi-Fi packet loss, gateway reliability, VPN latency, DNS reachability, and intermittent outages over runs of 24 hours or longer.

Features

• Cross-platform system ping engine for Windows and Linux
• No administrator privileges required
• Continuous CSV logging with flush-after-write durability
• Runtime statistics with dynamic in-place terminal updates
• Automatic outage detection with start/end time, duration, and failed sample count
• Rolling 1 minute, 5 minute, and 1 hour reliability statistics
• p50, p95, and p99 latency analytics
• Connection status classification: healthy, degraded, or down
• Live matplotlib latency chart with success and failure markers
• Sliding plot window to avoid unbounded memory growth
• Graceful Ctrl+C shutdown with final chart and Excel export
• Headless mode for servers and remote sessions
• Excel workbook with Summary and Raw Data sheets
• Self-contained HTML report with embedded chart and analytics tables
• Optional embedded Excel latency chart
• TOML configuration file support
• Configurable ping period, timeout, output directory, plot window, auto-save interval, thresholds, and run duration

Screenshots

Installation

Python 3.10 or newer is recommended.

git clone https://github.com/your-org/ping-reliability-monitor.git
cd ping-reliability-monitor
python -m venv .venv

Activate the virtual environment:

# Windows PowerShell
.venv\Scripts\Activate.ps1

# Linux/macOS
source .venv/bin/activate

Install dependencies:

pip install -r requirements.txt

Usage

Basic run using the default host 8.8.8.8:

python ping_monitor.py

Monitor a custom host:

python ping_monitor.py 192.168.1.1

Ping twice per second:

python ping_monitor.py 192.168.1.1 --period 0.5

Run without a GUI on a headless machine:

python ping_monitor.py example.com --no-plot

Run for exactly 24 hours and export automatically:

python ping_monitor.py 1.1.1.1 --duration 24h --no-plot

Use a TOML config file:

python ping_monitor.py --config monitor.toml

Save output files to a custom directory:

python ping_monitor.py 1.1.1.1 --log-dir measurements/provider-test

Command Line Arguments

Argument	Description	Default
host	Hostname or IP address to monitor	8.8.8.8
--period	Seconds between ping attempts	1.0
--timeout	Ping timeout in milliseconds	1000
--window-size	Number of samples shown in the live plot	300
--log-dir	Directory for generated output files	logs
--no-plot	Disable live matplotlib GUI	false
--auto-save-interval	Seconds between periodic PNG chart saves; use 0 to disable	300
--duration	Stop automatically after a duration such as 24h, 90m, or 3600s	none
--config	Load settings from a TOML config file	none
--latency-warning-ms	Recent p95 latency threshold for degraded status	100
--packet-loss-warning-percent	Recent packet loss threshold for degraded status	5
--down-after-failures	Consecutive failures needed for down status	3

Configuration File

Settings can be loaded from a TOML file. Command-line arguments override values from the config file.

[monitor]
host = "192.168.1.1"
period = 1.0
timeout = 1000
window_size = 600
log_dir = "logs/router-24h"
no_plot = true
auto_save_interval = 300
duration = "24h"
latency_warning_ms = 100
packet_loss_warning_percent = 5
down_after_failures = 3

Output Files

All output files are written under --log-dir.

CSV log:

ping_log_<host>_<timestamp>.csv

The CSV is written continuously with UTF-8 BOM encoding for Excel compatibility. Each record is flushed immediately to reduce data loss if the process or machine crashes.

Columns:

timestamp,sequence,host,success,response_time_ms,error,elapsed_s

Excel workbook:

ping_results_<host>_<timestamp>.xlsx

The workbook contains:

• Summary: total pings, success/failure counts, percentages, latency statistics, percentiles, outage totals, status, start/end time, and duration
• Rolling Windows: last 1 minute, 5 minute, and 1 hour success, loss, average latency, and p95 latency
• Outages: detected outage periods with start/end time, duration, and failed sample count
• Raw Data: the complete dataset loaded from the CSV log
• Embedded latency chart when data exists

HTML report:

ping_report_<host>_<timestamp>.html

The HTML report is self-contained and includes the PNG chart, summary metrics, rolling-window statistics, outage table, and a raw-data preview.

PNG chart:

ping_chart_<host>_<timestamp>.png

The chart is saved periodically when --auto-save-interval is enabled and again on exit.

Example Workflow

1. Start a 24-hour reliability measurement:

   python ping_monitor.py 192.168.1.1 --period 1 --timeout 1000 --duration 24h --log-dir logs/router-24h

2. Leave the process running. The terminal shows continuously updated totals, success rate, failure rate, min/average/max latency, last latency, and uptime.

3. Let --duration 24h stop the run automatically, or stop with Ctrl+C. The application saves the final PNG chart, exports the Excel workbook, writes the HTML report, closes the CSV file, and prints a final summary.

4. Open the CSV or XLSX in Excel. Use the raw data to filter outage windows, correlate spikes with other logs, or create custom pivot tables and charts.

Architecture

.
├── main.py          # CLI, runtime loop, graceful shutdown
├── ping_monitor.py  # Compatibility launcher
├── ping.py          # Cross-platform subprocess ping engine and PingRecord model
├── logger.py        # Durable CSV logging
├── stats.py         # Constant-memory runtime statistics
├── plotter.py       # Live matplotlib sliding-window chart
├── config.py        # TOML configuration loading
├── exporter.py      # Excel, HTML, and static PNG export
├── requirements.txt
└── README.md

The application writes raw samples directly to CSV. The live plot keeps only the configured sliding window. Runtime analytics keep aggregate counters, rolling-window samples, outage records, and a sorted latency series for percentile calculation.

Reliability Notes

Packet loss means the local ping command did not receive a valid reply before the timeout. This can be caused by link loss, routing issues, ICMP filtering, host overload, Wi-Fi interference, VPN instability, or an overloaded gateway.

Latency spikes should be interpreted in context. A single high-latency sample can be transient queueing, while repeated spikes or clusters of failures usually indicate congestion, radio interference, provider instability, or routing changes.

DNS failures are reported separately when the operating system ping command returns recognizable DNS resolution errors. For long-term ISP or LAN checks, prefer monitoring a stable IP address such as a router, resolver, or known external endpoint.

Status classification uses recent rolling statistics. A connection is down after the configured number of consecutive failures, degraded when recent packet loss or p95 latency crosses thresholds, and healthy otherwise.

How to Generate Screenshots

Screenshots are not committed by default. To generate them for your repository:

1. Run the monitor:

   python ping_monitor.py 8.8.8.8 --period 1

2. Capture the terminal while it is running and save it as:

   docs/screenshots/terminal_output.png
   

3. Capture the live matplotlib chart window and save it as:

   docs/screenshots/live_chart.png
   

4. Stop the monitor with Ctrl+C, open the generated Excel workbook, capture the Summary sheet, and save it as:

   docs/screenshots/excel_output.png
   

Future Improvements

• JSONL export for streaming ingestion
• Prometheus metrics endpoint
• Multiple concurrent hosts
• Alert hooks for sustained packet loss or latency thresholds

License

MIT