Metadata-Version: 2.4
Name: network-pinger
Version: 2.5.2.506
Summary: Async network monitoring tool with real-time terminal UI, alerts, and connection quality analysis
License: MIT
License-File: LICENSE
Keywords: network,monitoring,ping,cli,tui,dns,traceroute
Author: meshlg
Author-email: meshlgfox@gmail.com
Requires-Python: >=3.10,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Networking :: Monitoring
Classifier: Topic :: Utilities
Requires-Dist: dnspython (>=2.4.0,<3.0.0)
Requires-Dist: prometheus-client (>=0.16.0,<0.17.0)
Requires-Dist: pydantic (>=2.12.5,<3.0.0)
Requires-Dist: pydantic-settings (>=2.13.1,<3.0.0)
Requires-Dist: pythonping (>=1.1.0,<2.0.0)
Requires-Dist: requests (>=2.31.0,<3.0.0)
Requires-Dist: rich (>=13.7.0,<14.0.0)
Project-URL: Homepage, https://github.com/meshlg/_pinger
Project-URL: Repository, https://github.com/meshlg/_pinger.git
Description-Content-Type: text/markdown

<div align="center">

# Pinger

**Asynchronous network monitoring with real-time terminal interface**

[Русский](README.ru.md) · [English](README.md)

<p align="center">
  <a href="https://pypi.org/project/network-pinger/"><img src="https://img.shields.io/pypi/v/network-pinger?color=blue&label=PyPI" alt="PyPI"></a>
  <a href="python.org"><img src="https://img.shields.io/pypi/pyversions/network-pinger" alt="Python Versions"></a>
  <a href="LICENSE"><img src="https://img.shields.io/github/license/meshlg/_pinger" alt="License"></a>
  <a href=""><img src="https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey" alt="Platforms"></a>
  <br>
  <a href="https://github.com/meshlg/_pinger/stargazers"><img src="https://img.shields.io/github/stars/meshlg/_pinger?style=social" alt="GitHub Stars"></a>
  <a href="https://github.com/meshlg/_pinger/network"><img src="https://img.shields.io/github/forks/meshlg/_pinger?style=social" alt="GitHub Forks"></a>
  <a href="https://github.com/meshlg/_pinger/issues"><img src="https://img.shields.io/github/issues/meshlg/_pinger" alt="GitHub Issues"></a>
  <a href="https://pypi.org/project/network-pinger/"><img src="https://img.shields.io/pypi/dm/network-pinger" alt="PyPI Downloads"></a>
</p>

<p><em>Asynchronous network monitoring tool with Rich-based terminal interface, smart alerts, DNS benchmarks, hop health tracking, and automatic problem diagnosis.</em></p>

<p>
  <a href="#quick-start"><kbd>✴︎ Quick Start</kbd></a>
  <a href="#features"><kbd>▣ Features</kbd></a>
  <a href="#configuration"><kbd>⚒︎ Configuration</kbd></a>
  <a href="#deployment"><kbd>⚓︎ Deployment</kbd></a>
</p>

<div align="center">
  <sub>Real-time metrics · Smart alerts · DNS analytics · Prometheus-ready</sub>
</div>

![Pinger Interface](assets/screenshot.jpg)

</div>

> **Works everywhere:** Windows, Linux, and macOS with system `ping` and `traceroute` (`tracert` on Windows) commands.
>
> [!WARNING]
> **Security Notice:** Do not run Pinger as root/admin. It uses system commands (`ping`, `traceroute`) which do not require elevated privileges for basic operation. Running as root increases the risk of privilege escalation if a vulnerability is exploited.

---

## About

**Pinger** is a professional real-time network connection monitoring tool designed for system administrators, DevOps engineers, and enthusiasts who value network reliability and transparency.

### Key Benefits

| Benefit | Description |
|---------|-------------|
| **Real-time monitoring** | Visualization of latency, packet loss, jitter, and p95 metrics with updates every second |
| **Intuitive terminal interface** | Beautiful UI based on Rich library with color-coded statuses and progress bars |
| **Flexible configuration** | All settings via environment variables — easy to adapt to any requirements |
| **Multi-level diagnostics** | Automatic problem source detection (ISP/local network/DNS/MTU) based on patterns |
| **Prometheus integration** | Native metrics support for monitoring and alerting |
| **Docker/Kubernetes ready** | Helm chart and docker-compose for quick container deployment |
| **Localization** | Russian and English language support with automatic detection |
| **Security** | Mandatory authentication for public health endpoints |

### Who is this for

- **System administrators** — monitoring network infrastructure status
- **DevOps engineers** — integration with monitoring systems (Prometheus, Grafana)
- **Developers** — debugging network problems and routing analysis
- **Enthusiasts** — visualizing home connection quality

---

## Quick Start

> [!IMPORTANT]
> Python 3.10+ is required, as well as system `ping` and `traceroute` (`tracert` on Windows) commands.

### Installation via pipx (recommended)

```bash
pipx install network-pinger
pinger
```

Press `Ctrl+C` to stop gracefully.

```bash
pipx upgrade network-pinger
```

### Installation via pip

```bash
python -m pip install --upgrade network-pinger
pinger
```

### Installation from source

```bash
git clone https://github.com/meshlg/_pinger.git
cd _pinger
pip install -r requirements.txt
python pinger.py
```

---

## Features

Six real-time panels track your connection status — from edge latency to route analysis.

### ✴︎ Ping Monitoring

- Real-time metrics: current / best / average / peak / median / jitter / p95
- Dual sparkline charts and Unicode progress bars for drift visualization
- Packet loss detection with consecutive loss counter and p95 latency metric

### ✧ DNS Monitoring and Benchmarking

- Parallel monitoring of A, AAAA, CNAME, MX, TXT, and NS records
- Built-in test suite for benchmarking:

| Test | What it measures |
|------|------------------|
| **Cached** | DNS response from cache (repeat query) |
| **Uncached** | Full recursive resolution with random subdomain |
| **DotCom** | Response time of popular .com domain |

- Statistics: minimum / average / maximum / standard deviation / reliability
- Color badges: green (fast) / yellow (slow) / red (error)
- Comparison of multiple DNS resolvers in parallel

### ⚑ Smart Alerts
 
![Smart Alerts](assets/notifications.jpg)

- Audio + visual alerts for latency, jitter, packet loss, and connection drops
- Hysteresis to prevent flickering — alerts trigger only on state changes
- **Smart Features:**
  - **Deduplication** — prevents repetitive alerts for the same issue
  - **Grouping** — combines related alerts into a single notification
  - **Adaptive Thresholds** — automatically learns normal network behavior
  - **Fatigue Prevention** — suppresses alerts during prolonged incidents
  - **Quiet Hours** — schedule a maintenance window (`QUIET_HOURS_START` to `QUIET_HOURS_END`) when alert sounds are suppressed
- **Adaptive Warm-up Status** — `WARM-UP: X/Y` UI indicator tracking the progress of adaptive thresholds learning
- Alert feed with timestamps for problem correlation

### ✪ Problem Analysis and Prediction

- Automatic problem classification: ISP / local network / DNS / MTU
- Detection of recurring incidents and prediction of their return
- Route context plus loss/jitter trends for quick root cause identification

### ⌁ Hop Health Monitoring

### ⌁ Hop Health Monitoring
 
 - Hop discovery via traceroute, then parallel ping of each hop
 - **Rich Diagnostics**: Sparkline history charts, jitter, and latency delta
 - **Geolocation**: Provider (ASN) and Country detection for each node
 - Table with color coding and status traffic-lights (🟢/🟡/🔴)
 - Perfect for identifying congestion, route changes, or backbone issues

### ☲ Route Analysis

- Route change detection with configurable sensitivity and cooldown timers
- Automatic traceroute snapshot saving to `traceroutes/` directory on problems
- Helps prove routing changes when contacting ISP support

### ⌂ Network Metrics

- **Public IP** — change tracking with geolocation and AS information
- **MTU / Path MTU** — detection and packet fragmentation
- **TTL** — hop count estimation and anomaly detection

### ▤ Observability

- **`/metrics`** — Prometheus endpoint on port 8000 for metrics collection
- **`/health`** and **`/ready`** — health probes on port 8001 for Kubernetes/Docker
- Docker + Helm manifests for container deployment

### ☷ Localization

- Automatic system locale detection with **Russian** and **English** language support
- Language override in `config.py`:

```python
# config.py
CURRENT_LANGUAGE = "en"  # or "ru"
```

---

## Interface

> [!NOTE]
> Each panel updates in real-time. Match the screenshot above with this map for quick orientation.

### 1. Header and Status Bar

- Target IP, version with update indicator, connection lamp (● Connected / ▲ Degraded / ✕ Disconnected), and uptime
- Current ping, 30-minute loss, uptime, and public IP

### 2. Latency Panel

- Current / best / average / peak / median / jitter / p95 metric
- Dual sparkline charts for latency and jitter with last value tracking

### 3. Statistics Panel

- Packet counters: sent / successful / lost
- Success percentage and 30-minute loss
- Progress bars and mini trends panel (30m loss, jitter trend, hop count)

### 4. Analysis Panel

- Problem classifier (ISP / local network / DNS / MTU / unknown)
- Forecast (stable / risk of problems)
- Problem pattern
- Route stability (changed / stable) and last change time

### 5. Monitoring Panel

- DNS record health (A, AAAA, CNAME, MX, TXT, NS)
- Benchmarking tiles (Cached / Uncached / DotCom) with statistics
- MTU / Path MTU / TTL status and fragmentation
- Active alerts feed

### 6. Hop Health Panel

### 6. Hop Health Panel
 
 - Route table with full diagnostics (Min/Avg/Last, Loss, Jitter)
 - Sparkline latency history charts directly in the table (all modes)
 - Provider (ASN) and Location (Loc) information for wide screens
 - Status indicators for instant node health assessment

---

## Configuration

All settings are in [`config.py`](config.py) with default values and comments.

> [!TIP]
> Copy `config.py` next to the binary file or use environment variables to keep custom settings under version control.

### ⚙︎ Basic Settings

```python
TARGET_IP = "8.8.8.8"          # Target IP for ping
INTERVAL = 1                    # Ping interval (seconds)
WINDOW_SIZE = 1800              # Statistics window (30 min)
LATENCY_WINDOW = 600            # Latency history (10 min)
ENABLE_PYTHONPING_FALLBACK = True # Enable pythonping fallback (requires root/admin)
```

### ⚑ Thresholds and Alerts

```python
PACKET_LOSS_THRESHOLD = 5.0     # Packet loss threshold (%)
AVG_LATENCY_THRESHOLD = 100     # Average latency threshold (ms)
JITTER_THRESHOLD = 30           # Jitter threshold (ms)
CONSECUTIVE_LOSS_THRESHOLD = 5   # Consecutive loss threshold

ENABLE_SOUND_ALERTS = True
ALERT_COOLDOWN = 5              # Minimum interval between sounds (seconds)

# Smart Features
ENABLE_SMART_ALERTS = True
ENABLE_ADAPTIVE_THRESHOLDS = True
ADAPTIVE_BASELINE_WINDOW_HOURS = 24
ENABLE_ALERT_DEDUPLICATION = True
ENABLE_ALERT_GROUPING = True
ENABLE_QUIET_HOURS = False
QUIET_HOURS_START = "23:00"
QUIET_HOURS_END = "08:00"
```
```

### ✧ DNS Monitoring

```python
ENABLE_DNS_MONITORING = True
DNS_TEST_DOMAIN = "cloudflare.com"
DNS_CHECK_INTERVAL = 10
DNS_SLOW_THRESHOLD = 100        # "Slow" response threshold (ms)
DNS_RECORD_TYPES = ["A", "AAAA", "CNAME", "MX", "TXT", "NS"]

ENABLE_DNS_BENCHMARK = True
DNS_BENCHMARK_SERVERS = ["system"]  # or ["1.1.1.1", "8.8.8.8"]
```

### ⌂ IP / MTU / TTL

```python
ENABLE_IP_CHANGE_ALERT = True
IP_CHECK_INTERVAL = 15

ENABLE_MTU_MONITORING = True
MTU_CHECK_INTERVAL = 30
```

### ⌁ Traceroute and Hop Monitoring

```python
ENABLE_AUTO_TRACEROUTE = False   # Manual launch or on route change
TRACEROUTE_TRIGGER_LOSSES = 3
TRACEROUTE_COOLDOWN = 300
TRACEROUTE_MAX_HOPS = 15

ENABLE_HOP_MONITORING = True
HOP_PING_INTERVAL = 1
HOP_PING_TIMEOUT = 0.5
HOP_LATENCY_GOOD = 50          # Green (ms)
HOP_LATENCY_WARN = 100         # Yellow (ms), above = red
```

### ✪ Analysis

```python
ENABLE_PROBLEM_ANALYSIS = True
PROBLEM_ANALYSIS_INTERVAL = 60

ENABLE_ROUTE_ANALYSIS = True
ROUTE_ANALYSIS_INTERVAL = 1800
ROUTE_CHANGE_CONSECUTIVE = 2
```

### 🔄 Version Check

```python
ENABLE_VERSION_CHECK = True
VERSION_CHECK_INTERVAL = 3600  # Check every hour (seconds)
```

![Version Check](assets/update.jpg)

The application automatically checks for updates every hour (configurable). When a new version is available, you'll see an indicator in the header:

- `v2.3.1 → v2.4.0` — Update available (yellow arrow)
- `v2.3.1 ✓` — Up to date (green checkmark)
- `v2.3.1` — No check performed yet

To disable version checking:

```bash
export ENABLE_VERSION_CHECK=false
```

To change the check interval (e.g., every 30 minutes):

```bash
export VERSION_CHECK_INTERVAL=1800
```

---

## Deployment

<div align="center">
<table>
  <tr>
    <td><strong>⚓︎ Docker Compose</strong></td>
    <td><strong>♘ Kubernetes (Helm)</strong></td>
  </tr>
  <tr>
    <td>Local lab with Prometheus and health ports.</td>
    <td>Cluster readiness with values overrides for production.</td>
  </tr>
</table>
</div>

### ⚓︎ Docker Compose

> [!WARNING]
> When binding health endpoint to `0.0.0.0`, authentication is **required**. The default `docker-compose.yml` uses Basic Auth with `HEALTH_AUTH_USER=admin` and `HEALTH_AUTH_PASS=${HEALTH_AUTH_PASS:-changeme}`. **Change the default password** via environment variable or `.env` file before deployment.

```bash
docker compose up -d
```

| Service | Port | Description |
|---------|------|-------------|
| `pinger` | `8000` | Prometheus metrics (`/metrics`). |
| `pinger` | `8001` | Health probes (`/health`, `/ready`). |
| `prometheus` | `9090` | Prometheus UI. |

### ♘ Kubernetes (Helm)

```bash
helm install pinger ./charts/pinger -f charts/pinger/values.yaml
```

Need customization? See [`charts/pinger/README.md`](charts/pinger/README.md) for image tags, secrets, and upgrade notes.

---

## FAQ

### ❓ How to diagnose connection problems?

Pinger automatically classifies problems in the analysis panel:

| Problem Type | Signs | What to do |
|--------------|-------|------------|
| **ISP** | High latency on hops 2-5, packet loss on route | Contact your ISP, show traceroute snapshots |
| **Local network** | Loss on first hop, router problems | Check cable, reboot router |
| **DNS** | Slow DNS queries but normal ping by IP | Change DNS server (1.1.1.1, 8.8.8.8) |
| **MTU** | Packet fragmentation, VPN problems | Reduce MTU on interface |

### ❓ Why does ping show packet loss but internet works?

This is normal for some ISPs:
- ICMP packets may have low priority
- Some routers limit ICMP traffic
- Check loss on hops — if only on one, this may be normal

### ❓ How to configure alerts?

```python
# config.py
ENABLE_SOUND_ALERTS = True
ALERT_COOLDOWN = 5              # Minimum interval between sounds (seconds)
PACKET_LOSS_THRESHOLD = 5.0     # Packet loss threshold (%)
AVG_LATENCY_THRESHOLD = 100     # Average latency threshold (ms)
JITTER_THRESHOLD = 30           # Jitter threshold (ms)
```

### ❓ How to integrate with Prometheus?

Pinger provides metrics on port 8000:

```yaml
# prometheus.yml
scrape_configs:
  - job_name: 'pinger'
    static_configs:
      - targets: ['localhost:8000']
```

### ❓ How to use in Kubernetes?

```bash
helm install pinger ./charts/pinger -f charts/pinger/values.yaml
```

Health endpoints are available on port 8001:
- `/health` — health check
- `/ready` — readiness check

### ❓ How to change interface language?

```python
# config.py
CURRENT_LANGUAGE = "en"  # or "ru"
```

Language is detected automatically based on system locale.

### ❓ How to save monitoring results?

Pinger automatically saves traceroute snapshots on problems to `traceroutes/` directory. For persistent logging, use Prometheus.

### ❓ How to run in background?

```bash
# Linux/macOS
nohup pinger > pinger.log 2>&1 &

# Windows
start /B pinger > pinger.log 2>&1
```

### ❓ How to check health endpoints?

```bash
# Health check
curl http://localhost:8001/health

# Readiness check
curl http://localhost:8001/ready

# Prometheus metrics
curl http://localhost:8000/metrics
```

### ❓ How to configure authentication for health endpoints?

```bash
# Basic Auth
export HEALTH_AUTH_USER=admin
export HEALTH_AUTH_PASS=secret

# Token Auth
export HEALTH_TOKEN=your-secret-token
export HEALTH_TOKEN_HEADER=X-Health-Token

# Trusted Proxies (for rate limiting behind reverse proxies)
export HEALTH_TRUSTED_PROXIES="127.0.0.1,10.0.0.0/8"
```

See [`SECURITY.md`](SECURITY.md) for more details.

---

## For Developers

```bash
pip install poetry
git clone https://github.com/meshlg/_pinger.git
cd _pinger
poetry install
poetry run pinger
```

1. Use Poetry for isolated environments and pinned dependencies.
2. Run `poetry run pytest` before opening a PR.
3. Follow [CONTRIBUTING.md](CONTRIBUTING.md) for releases and tagging (remember git tags for update notifications).

---

<div align="center">

**[MIT License](LICENSE)** · 2026 © meshlg  
✉︎ [Join Discord](https://discordapp.com/users/268440099828662274) · ⚑ [Report an issue](https://github.com/meshlg/_pinger/issues/new/choose) · ☆ [Star the repo](https://github.com/meshlg/_pinger/stargazers)

</div>

