network-pinger 2.4.9.830

Async network monitoring tool with real-time terminal UI, alerts, and connection quality analysis

Pinger

Asynchronous network monitoring with real-time terminal interface

Русский · English

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

✴︎ Quick Start ▣ Features ⚒︎ Configuration ⚓︎ Deployment

_{Real-time metrics · Smart alerts · DNS analytics · Prometheus-ready}

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)

pipx install network-pinger
pinger

Press Ctrl+C to stop gracefully.

pipx upgrade network-pinger

Installation via pip

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

Installation from source

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

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

# 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 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

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

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

ENABLE_IP_CHANGE_ALERT = True
IP_CHECK_INTERVAL = 15

ENABLE_MTU_MONITORING = True
MTU_CHECK_INTERVAL = 30

⌁ Traceroute and Hop Monitoring

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

ENABLE_PROBLEM_ANALYSIS = True
PROBLEM_ANALYSIS_INTERVAL = 60

ENABLE_ROUTE_ANALYSIS = True
ROUTE_ANALYSIS_INTERVAL = 1800
ROUTE_CHANGE_CONSECUTIVE = 2

🔄 Version Check

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

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:

export ENABLE_VERSION_CHECK=false

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

export VERSION_CHECK_INTERVAL=1800

---

Deployment

⚓︎ Docker Compose	♘ Kubernetes (Helm)
Local lab with Prometheus and health ports.	Cluster readiness with values overrides for production.

⚓︎ 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.

docker compose up -d

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

♘ Kubernetes (Helm)

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

Need customization? See 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?

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

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

❓ How to use in Kubernetes?

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?

# 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?

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

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

❓ How to check health endpoints?

# 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?

# 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 for more details.

---

For Developers

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 for releases and tagging (remember git tags for update notifications).

---

MIT License · 2026 © meshlg
✉︎ Join Discord · ⚑ Report an issue · ☆ Star the repo