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

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

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:

• 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

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.

⚙︎ 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

docker compose up -d

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

❓ 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).