https://github.com/panoc/pihole-latency-stats
Pi-hole Latency Stats is a lightweight Bash script to analyze your Pi-hole's and Unbound DNS response times. It reads directly from the FTL database to visualize how fast your local DNS is resolving queries.
https://github.com/panoc/pihole-latency-stats
bash-script dashboard dns dns-benchmark dns-delay dns-latency home-assistant latency monitoring network network-monitoring pi-hole pihole statistics stats unbound
Last synced: 4 months ago
JSON representation
Pi-hole Latency Stats is a lightweight Bash script to analyze your Pi-hole's and Unbound DNS response times. It reads directly from the FTL database to visualize how fast your local DNS is resolving queries.
- Host: GitHub
- URL: https://github.com/panoc/pihole-latency-stats
- Owner: panoc
- License: gpl-3.0
- Created: 2026-01-15T10:21:01.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-01-26T07:10:11.000Z (5 months ago)
- Last Synced: 2026-01-26T09:58:26.530Z (5 months ago)
- Topics: bash-script, dashboard, dns, dns-benchmark, dns-delay, dns-latency, home-assistant, latency, monitoring, network, network-monitoring, pi-hole, pihole, statistics, stats, unbound
- Language: Shell
- Homepage: https://panoc.github.io/pihole-latency-stats/
- Size: 950 KB
- Stars: 10
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Analyze your Pi-hole and Unbound DNS response times.
**Pi-hole Latency Stats** is a lightweight, zero-dependency Bash script that analyzes your **Pi-hole**'s performance. It calculates latency percentiles (Median, 95th), groups query speeds into "Tiers" (buckets), monitors your **Unbound** recursive DNS server, and presents everything in a **modern, responsive web dashboard**.
This tool helps you answer: *"Is my DNS slow because of my upstream provider, or is it just my local network?"* and *"Is Unbound performing efficiently?"*
---
## ✨ Key Features
**🔍 Latency Analysis** Calculates **Average**, **Median**, and **P95** latency to spot jitters.
**📈 Tiered Grouping** Groups query speeds into "Tiers" (e.g., `<10ms`, `10-50ms`) for easy analysis.
**🔄 Unbound Integration** Auto-detects Unbound to report **Cache Hit Ratio**, **Prefetching**, and **RAM Usage**.
**📸 Snapshot Mode** Safely copies the database before analysis to prevent `Database Locked` errors.
**🎯 Smart Filtering** Filter by **Time** (24h, 7d), **Status** (Blocked/Forwarded), or **Domain** (Wildcards supported).
**🤖 Automation Ready** Native **JSON output** for Home Assistant, Grafana, or Node-RED integration.
---
## Requirements
* `sqlite3` (usually installed by default)
* *(Optional)* `unbound` and `unbound-host` (for Unbound statistics)
---
## Quick Start (One-Step Install)
To install the core script, the web dashboard, and all required dependencies, run:
```bash
wget -O install_phls.sh https://github.com/panoc/pihole-latency-stats/releases/latest/download/install_phls.sh && sudo bash install_phls.sh
```
### 👉 [Manual Installation Guide](https://github.com/panoc/pihole-latency-stats/blob/main/docs/MANUAL_INSTALLATION.md)
---
## 📊 Visual Dashboard
Includes a modern, responsive browser dashboard powered by **Chart.js**.
*Features: Auto-refresh, Dark Mode, Historical Trends, and Multi-Profile support.*
---
## 🛠️ Real-World Use Cases
### 1. Diagnosing "Is it me or the ISP?"
Speed tests measure bandwidth, not latency. DNS lag is the primary cause of sluggish browsing.
* **The Test:** Compare your **Local** speed vs **Upstream** speed.
* `./pihole_stats.sh -pi` (Cached/Local answers)
* `./pihole_stats.sh -up` (Cloudflare/Google/ISP answers)
> **💡 The Insight**
> * If **`-pi` is slow (> 10ms):** Your Raspberry Pi might be overloaded or using a slow SD card.
> * If **`-up` is slow (> 100ms):** Your ISP or upstream DNS provider is having issues.
>
>
### 2. Optimizing Unbound Performance
If you run Unbound as a recursive resolver, blind trust isn't enough. Verify your efficiency.
* **The Strategy:** Run `./pihole_stats.sh -up` to strictly analyze upstream resolution speed. Compare the **Average** against a standard forwarder (like `1.1.1.1`).
* **Deep Inspection:** Use the `-ucc` flag to count the exact number of **Messages** and **RRsets** in RAM.
> **💡 The Insight**
> If your **Cache Hit Ratio** stays low (< 50%) after 24 hours, consider increasing `cache-min-ttl` in your Unbound config.
### 3. Domain-Specific Debugging
Services like work VPNs or streaming sites often behave differently than general traffic.
* **The Test:** Filter stats for specific domains.
* `./pihole_stats.sh -dm "netflix"` (Matches `netflix.com`, `nflxso.net`, etc.)
* `./pihole_stats.sh -edm "my-work-vpn.com"` (Exact match only)
> **💡 The Insight**
> You might find that while your global average is **20ms**, specific queries are hitting **Tier 8 (>1000ms)**, indicating a routing timeout.
### 4. Long-Term Health Monitoring
Spot trends before they become problems by automating data collection.
* **The Setup:** Add the script to Cron to run nightly.
* `./pihole_stats.sh -24h -j -f "daily_stats.json" -rt 30`
* **The Insight:**
* **JSON Output:** Ingest this into **Home Assistant**, **Grafana**, or **Node-RED** to visualize latency over weeks.
* **Auto-Retention (`-rt`):** Keeps your disk clean by automatically deleting reports older than 30 days.
---
## 📖 Full Documentation
Detailed information on CLI flags, automation, and advanced tuning can be found here:
### 👉 [Detailed Usage & Command Guide](https://github.com/panoc/pihole-latency-stats/blob/main/docs/USAGE.md)
---