network-pinger 2.3.0

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

Pinger

Real-time network monitoring in your terminal

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

✴︎ Quick Start ▣ Feature Tour ⚒︎ Configure

_{Live metrics · Smart alerts · DNS insights · Prometheus-ready observability}

Works everywhere: Windows, Linux, and macOS with system ping and traceroute (tracert on Windows).

---

Highlights

✴︎ Ping & Latency Dual sparklines, jitter tracking, loss trends, and p95 insight.	✧ DNS Benchmark Cached / Uncached / DotCom tests with side-by-side providers.	⌁ Hop Health Traceroute-aware per-hop latency & loss heatmap.
⚑ Smart Alerts Sound + visual notifications with hysteresis & cooldowns.	✪ Problem Analysis Auto-diagnosis of ISP vs local vs DNS vs MTU issues.	☲ Route Tracking Change detection and auto traceroute when paths shift.

---

Quick Start

[!IMPORTANT] Python 3.10+ required plus system ping and traceroute (tracert on Windows).

✴︎ pipx (recommended)

pipx install network-pinger
pinger

Press Ctrl+C for graceful shutdown.

pipx upgrade network-pinger

▣ pip

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

⚒︎ From source

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

[!TIP] The app checks for new releases on startup and surfaces a Rich notification when an update is available.

---

Features

Six live panels keep the pulse of your link—from edge latency to observability endpoints.

✴︎ Ping Monitoring

• Real-time current / best / average / peak / median / jitter metrics.
• Dual sparklines + Unicode progress bars for at-a-glance drift detection.
• Packet-loss detection with consecutive loss counter and p95 latency insight.

✧ DNS Monitoring & Benchmark

• Parallel monitoring of A, AAAA, CNAME, MX, TXT, and NS records.
• Built-in benchmark suite:

Test	What it measures
Cached	DNS response from resolver cache (repeat query).
Uncached	Full recursive resolution using a random hostname.
DotCom	Response time for a popular .com domain.

• Statistics: min / avg / max / σ / reliability with green (fast) / yellow (slow) / red (failed) badges.
• Compare multiple providers side-by-side:

DNS_BENCHMARK_SERVERS = ["system", "1.1.1.1", "8.8.8.8"]

⚑ Smart Alerts

• Audio + visual alerts for latency, jitter, packet loss, and disconnects.
• Threshold hysteresis stops flicker; cooldown timers prevent alert spam.
• Alert feed keeps timestamps so you can correlate issues later.

✪ Problem Analysis & Prediction

• Auto-tags outages as ISP / local / DNS / MTU failures using signal patterns.
• Looks for repeating incidents and forecasts when they may return.
• Route context plus loss/jitter trends clarify root causes quickly.

⌁ Hop Health Monitoring

• Discovers hops via traceroute, then pings each hop in parallel.
• Table shows min / avg / last latency and per-hop loss with severity colors.
• Great for spotting where congestion or shaping occurs along the path.

☲ Route Analysis

• Detects route changes with configurable sensitivity + cooldowns.
• Auto-saves traceroute snapshots into traceroutes/ when trouble hits.
• Helps prove upstream routing shifts when filing ISP tickets.

⌂ Network Metrics

• Public IP change detection with geo/IP-AS lookups.
• MTU / Path MTU discovery plus fragmentation detection.
• TTL monitoring for hop-count estimation and anomaly detection.

▤ Observability

• /metrics Prometheus endpoint on port 8000 for scraping.
• /health + /ready endpoints on port 8001 for probes.
• Docker + Helm manifests cover local labs through full clusters.

☷ Localization

• Auto-detects system locale with Russian and English packs ready.
• Override anytime in config.py:

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

---

Interface Tour

[!NOTE] Every panel refreshes live; pair the screenshot above with this map to orient yourself quickly.

1. Header & Status Bar — Target IP, version badge + updater, connection lamp (● Connected / ▲ Degraded / ✕ Disconnected), and session uptime.
2. Latency Panel — Current / best / avg / peak / median latency, jitter, p95, and dual sparklines tracking the last minutes of activity.
3. Statistics Panel — Packet counters (sent / ok / lost), Unicode success bars, and a mini-trends strip (loss 30 m, jitter trend, hop count).
4. Analysis Panel — Problem classifier result, prediction badge, and route stability indicator with change counters.
5. Monitoring Panel — DNS record health, benchmark tiles, TTL / MTU / fragmentation state, and live alert feed.
6. Hop Health Panel — Per-hop min / avg / last latency + loss, color-coded (green / yellow / red) for instant hotspot spotting.

Panel	Signals you watch
Status bar	Connection state, target, uptime, current KPIs
Latency	Distribution metrics, jitter, sparklines
Statistics	Packet counts, success %, trends
Analysis	Root-cause classification, prediction, route state
Monitoring	DNS, benchmark, network stats, notifications
Hop Health	Hop-by-hop latency & loss matrix

---

Configuration

All knobs live in config.py—versioned defaults with inline comments.

[!TIP] Copy config.py next to your binary or set env vars to keep custom tweaks under version control.

⚙︎ Core

TARGET_IP = "8.8.8.8"          # Ping target
INTERVAL = 1                    # Ping interval (seconds)
WINDOW_SIZE = 1800              # Stats window (30 min)
LATENCY_WINDOW = 600            # Latency history (10 min)

⚑ Thresholds & Alerts

PACKET_LOSS_THRESHOLD = 5.0     # Packet loss warning (%)
AVG_LATENCY_THRESHOLD = 100     # Average latency warning (ms)
JITTER_THRESHOLD = 30           # Jitter warning (ms)
CONSECUTIVE_LOSS_THRESHOLD = 5   # Consecutive lost packets

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

✧ DNS Monitoring

ENABLE_DNS_MONITORING = True
DNS_TEST_DOMAIN = "cloudflare.com"
DNS_CHECK_INTERVAL = 10
DNS_SLOW_THRESHOLD = 100        # "Slow" 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 & Hop Monitoring

ENABLE_AUTO_TRACEROUTE = False   # Manual trigger 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

Health HTTP Server

Configuration

# Security: Defaults to localhost-only (127.0.0.1)
HEALTH_ADDR = "127.0.0.1"         # Bind address (127.0.0.1 = localhost-only)
HEALTH_PORT = 8001                  # Health endpoint port

# Authentication (REQUIRED if HEALTH_ADDR != 127.0.0.1):
# Method 1: Basic Auth
HEALTH_AUTH_USER = ""               # Username
HEALTH_AUTH_PASS = ""               # Password
# Method 2: Token Auth (simpler for load balancers/Prometheus)
HEALTH_TOKEN = ""                   # API token
HEALTH_TOKEN_HEADER = "X-Health-Token"  # Custom header name

Setting	Default	Description
HEALTH_ADDR	127.0.0.1	Bind to localhost only (secure by default)
HEALTH_PORT	8001	Health check port
HEALTH_AUTH_USER	-	Basic Auth username (with HEALTH_AUTH_PASS)
HEALTH_AUTH_PASS	-	Basic Auth password (with HEALTH_AUTH_USER)
HEALTH_TOKEN	-	Token for X-Health-Token header
HEALTH_TOKEN_HEADER	X-Health-Token	Custom header name for token

[!IMPORTANT] Security Requirement: If you set HEALTH_ADDR=0.0.0.0 (pod network), you MUST configure at least one authentication method (Basic Auth or Token). Without authentication, the server will refuse to start.

Token Auth (Recommended)

Token Auth is simpler for load balancers and Prometheus:

export HEALTH_TOKEN=your-secret-token

Prometheus configuration:

scrape_configs:
  - job_name: pinger-health
    metrics_path: /health
    static_configs:
      - targets: [pinger:8001]
    scheme: http
    http_headers:
      X-Health-Token: ${HEALTH_TOKEN}

---

Logging & Metrics

LOG_FILE = "~/.pinger/ping_monitor.log"
LOG_LEVEL = "INFO"
LOG_TRUNCATE_ON_START = True

ENABLE_METRICS = True           # Prometheus on :8000
ENABLE_HEALTH_ENDPOINT = True   # Health on :8001

---

Deployment

⚓︎ Docker Compose	♘ Kubernetes (Helm)
Local lab setup with baked-in Prometheus + health ports.	Cluster-ready chart with values overrides for prod.

⚓︎ Docker Compose

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 tweaks? See charts/pinger/README.md for image tags, secrets, and upgrade notes.

---

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 envs and locked deps.
2. Run poetry run pytest before opening a PR.
3. Follow CONTRIBUTING.md for release + tagging (remember to push git tags for update notifications).

---

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