piholelongtermstats 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (20) hide show
  1. piholelongtermstats-0.2.0/LICENSE +21 -0
  2. piholelongtermstats-0.2.0/PKG-INFO +316 -0
  3. piholelongtermstats-0.2.0/README.md +288 -0
  4. piholelongtermstats-0.2.0/piholelongtermstats/__init__.py +3 -0
  5. piholelongtermstats-0.2.0/piholelongtermstats/app.py +1237 -0
  6. piholelongtermstats-0.2.0/piholelongtermstats/assets/favicon.ico +0 -0
  7. piholelongtermstats-0.2.0/piholelongtermstats/assets/logo_phlts.png +0 -0
  8. piholelongtermstats-0.2.0/piholelongtermstats/assets/style.css +341 -0
  9. piholelongtermstats-0.2.0/piholelongtermstats/db.py +143 -0
  10. piholelongtermstats-0.2.0/piholelongtermstats/plot.py +144 -0
  11. piholelongtermstats-0.2.0/piholelongtermstats/process.py +87 -0
  12. piholelongtermstats-0.2.0/piholelongtermstats/stats.py +439 -0
  13. piholelongtermstats-0.2.0/piholelongtermstats.egg-info/PKG-INFO +316 -0
  14. piholelongtermstats-0.2.0/piholelongtermstats.egg-info/SOURCES.txt +18 -0
  15. piholelongtermstats-0.2.0/piholelongtermstats.egg-info/dependency_links.txt +1 -0
  16. piholelongtermstats-0.2.0/piholelongtermstats.egg-info/entry_points.txt +2 -0
  17. piholelongtermstats-0.2.0/piholelongtermstats.egg-info/requires.txt +11 -0
  18. piholelongtermstats-0.2.0/piholelongtermstats.egg-info/top_level.txt +1 -0
  19. piholelongtermstats-0.2.0/pyproject.toml +49 -0
  20. piholelongtermstats-0.2.0/setup.cfg +4 -0
piholelongtermstats-0.2.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Davis Thomas Daniel
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
piholelongtermstats-0.2.0/PKG-INFO ADDED
@@ -0,0 +1,316 @@
1
+ Metadata-Version: 2.4
2
+ Name: piholelongtermstats
3
+ Version: 0.2.0
4
+ Summary: A dashboard to explore long-term DNS query data from Pi-hole FTL database files.
5
+ Author-email: Davis Thomas Daniel <davisthomasdaniel@gmail.com>
6
+ Maintainer-email: Davis Thomas Daniel <davisthomasdaniel@gmail.com>
7
+ License-Expression: MIT
8
+ Project-URL: Homepage, https://github.com/davistdaniel/PiHoleLongTermStats
9
+ Project-URL: Documentation, https://readthedocs.org
10
+ Project-URL: Repository, https://github.com/davistdaniel/PiHoleLongTermStats.git
11
+ Project-URL: Bug Tracker, https://github.com/davistdaniel/PiHoleLongTermStats/issues
12
+ Keywords: dashboard,pihole,visualization,plotly,dash
13
+ Classifier: Programming Language :: Python
14
+ Requires-Python: >=3.11
15
+ Description-Content-Type: text/markdown
16
+ License-File: LICENSE
17
+ Requires-Dist: dash==3.0.4
18
+ Requires-Dist: pandas==2.2.3
19
+ Requires-Dist: plotly==6.0.1
20
+ Requires-Dist: psutil==7.1.2
21
+ Provides-Extra: develop
22
+ Requires-Dist: pytest==9.0.1; extra == "develop"
23
+ Requires-Dist: ruff; extra == "develop"
24
+ Requires-Dist: build==1.3.0; extra == "develop"
25
+ Requires-Dist: twine==6.2.0; extra == "develop"
26
+ Requires-Dist: pytest-cov==7.0.0; extra == "develop"
27
+ Dynamic: license-file
28
+
29
+ # Pi Hole Long Term Statistics v.0.2.0
30
+
31
+ A dashboard built with **Dash** and **Plotly** to explore long-term DNS query data from **Pi-hole v.6** FTL database files. Visualize allowed vs blocked domains, top clients, and query trends over time. I originally made this for my own use, but if you find it useful, a ⭐ would be awesome!
32
+
33
+
34
+ **Disclaimer : This is an unofficial, third-party project. The Pi Hole team and the development of [PiHole](https://pi-hole.net/) software is not related to this project.**
35
+
36
+
37
+ <div align="center">
38
+ <img src="https://raw.githubusercontent.com/davistdaniel/PiHoleLongTermStats/main/screenshots/screenshot1.png" alt="Demo Gif" width="600">
39
+ </div>
40
+
41
+ <div align="center">
42
+ <img src="https://raw.githubusercontent.com/davistdaniel/PiHoleLongTermStats/main/screenshots/demo.gif" alt="Demo Gif" width="600">
43
+ </div>
44
+
45
+ See more [screenshots](https://github.com/davistdaniel/PiHoleLongTermStats/blob/main/screenshots/screenshots.md). (The screenshots use a mock database.)
46
+
47
+ ## 🧰 Features
48
+ - ➕ Combine multiple databases and visualize consolidated stats.
49
+ - 🗂️ Info cards : Query stats, Activity stats, Day and Night stats. See [all supported metrics](https://github.com/davistdaniel/PiHoleLongTermStats?tab=readme-ov-file#supported-metrics).
50
+ - 📈 Interactive charts for query trends and client behavior, heatmaps showing day-hour stats, reply-times visualisation and more.
51
+ - 🔍 Filter queries by client.
52
+ - 🌐 View any number of top blocked/allowed domains, top clients.
53
+ - 📅 Analyze queries and compute stats over a custom date range and visualize them.
54
+ - ❌ Exclude domains using regex patterns before computing stats.
55
+
56
+ ## 📦 Dependencies
57
+
58
+ - Python (>=3.11). See `requirements.txt` for dependencies.
59
+ - Pi-hole (> v.6) FTL database file (pihole-FTL.db)
60
+
61
+ ## 🚀 Getting Started
62
+
63
+ > [!WARNING]
64
+ > Using your actual Pi-hole FTL db file for querying is **not** recommended and it is advised to use a copy. Place the copy in the project root or specify its path using the `--db_path` argument or `PIHOLE_LT_STATS_DB_PATH` environment variable. In any case, PiHoleLongTermStats does not monitor for changes in the Pi-hole FTL db file even if you mount it.
65
+
66
+ > [!TIP]
67
+ > * You can set up a cron job to periodically copy the FTL database to the `db_path` `PIHOLE_LT_STATS_DB_PATH` location, ensuring your stats are updated without touching the live database. Use the reload button in the dashboard to refresh the stats.
68
+ > * Set your timezone (e.g "Europe/Berlin") using `--timezone` or `PIHOLE_LT_STATS_TIMEZONE`.
69
+
70
+ > [!IMPORTANT]
71
+ > * PiHoleLongTermStats reloads the Pi-hole FTL database and recalculates stats whenever the dashboard is refreshed or the reload button is clicked.
72
+ > * If no date range is selected, it uses the default period set by `--days` or `PIHOLE_LT_STATS_DAYS`.
73
+ > * Large date ranges may lead to increased memory usage.
74
+ > * When multiple database files are provided, PiHoleLongTermStats concatenates them into a single dataframe and sorts the combined data by timestamp. Duplicate entries are **not** removed for calculating stats. Consolidating multiple databases can lead to increased memory usage.
75
+
76
+ > [!TIP]
77
+ > There are multiple ways to run the dashboard: using Python or Docker.
78
+
79
+ ### 🐳 Using Docker
80
+
81
+ <details>
82
+ <summary>Click to expand.</summary>
83
+
84
+
85
+ If you have a copy of your `pihole-FTL.db` file, you can quickly run the dashboard using Docker Compose.
86
+
87
+ 1. Make a directory for PiHoleLongtermStats:
88
+ ```bash
89
+ mkdir PiHoleLongTermStats
90
+ cd PiHoleLongTermStats
91
+ ```
92
+
93
+ 2. Make a copy/backup of your `pihole-FTL.db` (**Important!**) and place it in the PiHoleLongTermStats directory:
94
+
95
+ ```bash
96
+ # Example: Copy from the default Pi-hole location
97
+ sudo cp /etc/pihole/pihole-FTL.db .
98
+ # Ensure the user running the app has read permissions
99
+ sudo chown $USER:$USER pihole-FTL.db
100
+ ```
101
+ 3. Make a docker-compose.yml file in the same directory:
102
+
103
+ ```docker
104
+ services:
105
+ pihole-long-term-stats:
106
+ image: ghcr.io/davistdaniel/piholelongtermstats:latest
107
+ container_name: pihole-lt-stats
108
+ ports:
109
+ - "9292:9292" # Map host port to container port
110
+ volumes:
111
+ - ./pihole-FTL.db:/app/pihole-FTL.db:ro # Path to your Pi-hole DB file (adjust if it's not in current directory)
112
+ # To include additional Pi-hole databases, mount each one similarly:
113
+ #- ./pihole-FTL-2.db:/app/pihole-FTL-2.db:ro
114
+ environment:
115
+ - PIHOLE_LT_STATS_DB_PATH=/app/pihole-FTL.db # Path inside the container to the mounted DB file
116
+
117
+ # Provide multiple databases by listing their container paths as a
118
+ # comma-separated string, e.g.:
119
+ #- PIHOLE_LT_STATS_DB_PATH=/app/pihole-FTL.db,/app/pihole-FTL-2.db
120
+
121
+ - PIHOLE_LT_STATS_DAYS=31 # Number of days from now of data to analyze; change if desired
122
+ - PIHOLE_LT_STATS_PORT=9292 # Port the app listens to inside container; keep in sync with ports mapping
123
+ - PIHOLE_LT_STATS_NCLIENTS=10 # Number of clients to show in top clients plots
124
+ - PIHOLE_LT_STATS_NDOMAINS=10 # Number of domains to show in top domains plots
125
+ - PIHOLE_LT_STATS_TIMEZONE=UTC # timezone for display
126
+ #- PIHOLE_LT_STATS_IGNORE_DOMAINS=.*\.local # regex patterns for excluding domains. Example: to exclude all .local domains use .*\.local
127
+
128
+ # To ignore multiple domain patterns, separate each regex with a comma.
129
+ # example definition below ignores: anything ending in .local, anything starting with ads, exactly example.com
130
+ #- PIHOLE_LT_STATS_IGNORE_DOMAINS=.*\.local,^ads\.,^example\.com$
131
+
132
+ restart: unless-stopped
133
+ ```
134
+ and run using :
135
+
136
+ ```bash
137
+ sudo docker compose up -d
138
+ ```
139
+ 4. Open your browser and visit [http://localhost:9292](http://localhost:9292)
140
+ </details>
141
+
142
+
143
+ ### 🐍 Using Python
144
+
145
+ If installing using python, you can install from this git repo or as a package from PyPi.
146
+
147
+ #### Install from PyPi :
148
+
149
+ <details>
150
+ <summary>Click to expand.</summary>
151
+
152
+ 1. Install PiHoleLongTermStats from PyPi
153
+
154
+ ```bash
155
+ python -m pip install piholelongtermstats
156
+ ````
157
+
158
+ 2. Make a directory for PiHoleLongtermStats (optional):
159
+
160
+ ```bash
161
+ mkdir PiHoleLongTermStats
162
+ cd PiHoleLongTermStats
163
+ ```
164
+
165
+ 3. Make a copy/backup of your `pihole-FTL.db` (**Important!**) and place it in the PiHoleLongTermStats directory:
166
+
167
+ ```bash
168
+ # Example: Copy from the default Pi-hole location
169
+ sudo cp /etc/pihole/pihole-FTL.db .
170
+ # Ensure the user running the app has read permissions
171
+ sudo chown $USER:$USER pihole-FTL.db
172
+ ```
173
+ 4. Run the app:
174
+
175
+ ```bash
176
+ piholelongtermstats [OPTIONS]
177
+ ```
178
+ 5. Open your browser and visit [http://localhost:9292](http://localhost:9292)
179
+
180
+
181
+ <details>
182
+ <summary><b>Examples for python (Click to expand.)</b></summary>
183
+
184
+ To start the dashboard and visualize a single pihole-FTL database file for the last 15 days, with top 20 clients and top 15 domains on port 9292 while ingoring all domains which end with ".local":
185
+
186
+ ```bash
187
+ piholelongtermstats --db_path pihole-FTL.db --days 15 --n_clients 20 --n_domains 15 --port 9292 --ignore-domains ".*\.local"
188
+ ```
189
+ To combine two databases, provide paths as comma-separated strings:
190
+
191
+ ```bash
192
+ piholelongtermstats --db_path pihole-FTL.db,pihole-FTL-2.db
193
+ ```
194
+ To exclude multiple domains, provide comma-separated regex patterns:
195
+
196
+ ```bash
197
+ piholelongtermstats --ignore-domains ".*\.local,.*\.apple.com"
198
+ ```
199
+ </details>
200
+
201
+ </details>
202
+
203
+ #### Install from source :
204
+
205
+ <details>
206
+ <summary>Click to expand.</summary>
207
+
208
+ 1. Clone this repository and move into the project folder:
209
+
210
+ ```bash
211
+ git clone https://github.com/davistdaniel/PiHoleLongTermStats.git
212
+ cd PiHoleLongTermStats
213
+ ```
214
+
215
+ 2. Install dependencies using pip:
216
+
217
+ ```bash
218
+ pip install -r requirements.txt
219
+ ```
220
+
221
+ 3. Make a copy/backup of your `pihole-FTL.db` (**Important!**) and place it in the PiHoleLongTermStats directory:
222
+ ```bash
223
+ # Example: Copy from the default Pi-hole location
224
+ sudo cp /etc/pihole/pihole-FTL.db .
225
+ # Ensure the user running the app has read permissions
226
+ sudo chown $USER:$USER pihole-FTL.db
227
+ ```
228
+
229
+ 4. Run the app:
230
+
231
+ ```bash
232
+ python piholelongtermstats/app.py [OPTIONS]
233
+ ```
234
+
235
+ See the Configuration section below for available options.
236
+
237
+ 5. Open your browser and visit [http://localhost:9292](http://localhost:9292)
238
+
239
+
240
+ <details>
241
+ <summary><b>Examples for python (Click to expand.)</b></summary>
242
+
243
+ To start the dashboard and visualize a single pihole-FTL database file for the last 15 days, with top 20 clients and top 15 domains on port 9292 while ingoring all domains which end with ".local":
244
+
245
+ ```bash
246
+ python piholelongtermstats/app.py --db_path pihole-FTL.db --days 15 --n_clients 20 --n_domains 15 --port 9292 --ignore-domains ".*\.local"
247
+ ```
248
+ To combine two databases, provide paths as comma-separated strings:
249
+
250
+ ```bash
251
+ python piholelongtermstats/app.py --db_path pihole-FTL.db,pihole-FTL-2.db
252
+ ```
253
+ To exclude multiple domains, provide comma-separated regex patterns:
254
+
255
+ ```bash
256
+ python piholelongtermstats/app.py --ignore-domains ".*\.local,.*\.apple.com"
257
+ ```
258
+ </details>
259
+ </details>
260
+
261
+ ## ⚙️ Configuration
262
+
263
+ You can configure the application using command-line arguments or environment variables:
264
+
265
+ | Command-Line Argument | Environment Variable | Default Value | Description |
266
+ |-----------------------|------------------------------|-----------------|--------------------------------------------------|
267
+ | `--db_path` | `PIHOLE_LT_STATS_DB_PATH` | `pihole-FTL.db` | Path to the copied Pi-hole database file. Multiple databases can be combined by providing paths as comma-separated strings. |
268
+ | `--days` | `PIHOLE_LT_STATS_DAYS` | `31` | Number of days back from today to analyze. |
269
+ | `--port` | `PIHOLE_LT_STATS_PORT` | `9292` | Port number to serve the Dash app on. |
270
+ | `--n_clients` | `PIHOLE_LT_STATS_NCLIENTS` | `10` | Number of top clients to show in top clients plots. |
271
+ | `--n_domains` | `PIHOLE_LT_STATS_NDOMAINS` | `10` | Number of top clients to show in top clients plots. |
272
+ | `--port` | `PIHOLE_LT_STATS_TIMEZONE` | `UTC` | Timezone for displaying times in the dashboard. |
273
+ | `--ignore-domains` | `PIHOLE_LT_STATS_IGNORE_DOMAINS` | `""` | Comma-separated regex patterns to exclude domains from from stats (e.g to exlcude all .local domains, use ".*\.local") |
274
+
275
+ ## 🧑‍💻 Contributing
276
+
277
+ Any contribution, feature ideas or bug fixes are always welcome.
278
+
279
+ ## Star History
280
+
281
+ [![Star History Chart](https://api.star-history.com/svg?repos=davistdaniel/PiHoleLongTermStats&type=date&legend=top-left)](https://www.star-history.com/#davistdaniel/PiHoleLongTermStats&type=date&legend=top-left)
282
+
283
+ ## Supported metrics
284
+ | Metric | Description |
285
+ |--------|-------------|
286
+ | Allowed Queries | Total number of queries that were allowed through the Pi-hole. |
287
+ | Blocked Queries | Total number of queries that were blocked by the Pi-hole. |
288
+ | Top Allowed Domain | The domain which was allowed the most |
289
+ | Top Blocked Domain | The domain which was blocked the most |
290
+ | Total Unique Clients | The total number of unique devices that made queries. |
291
+ | Total Queries | Total number of queries processed by the Pi-hole. |
292
+ | Highest number of queries were on | The date with the peak query count. |
293
+ | Lowest number of queries were on | The date with the lowest query count. |
294
+ | Average reply time | The average time it takes for the Pi-hole to respond to a query. |
295
+ | Most Active Hour | The hour with the highest number of queries. |
296
+ | Least Active Hour | The hour with the lowest number of queries. |
297
+ | Most Active Day of the Week | The day with the highest query activity. |
298
+ | Least Active Day of the Week | The day with the lowest query activity. |
299
+ | Longest Blocking Streak | The longest consecutive period where queries were blocked. |
300
+ | Longest Allowing Streak | The longest consecutive period where queries were allowed. |
301
+ | Total queries during the day | Total number of queries made during daytime hours (06:00 to 23:59). |
302
+ | Total queries during the night | Total number of queries made during nighttime hours. |
303
+ | Top allowed domain during the day | The most allowed domain during the day. |
304
+ | Top blocked domain during the day | The most blocked domain during the day. |
305
+ | Top allowed domain during the night | The most allowed domain during the night. |
306
+ | Top blocked domain during the night | The most blocked domain during the night. |
307
+ | Most Persistent Client | The client that made the highest number of queries. |
308
+ | Most Diverse Client | The client that queried a blocked domain the most times. |
309
+ | Longest Idle Period | The longest period without any queries. |
310
+ | Slowest Responding Domain | The domain with the highest average response time. |
311
+ | Average Time Between Blocked Queries | Average interval between consecutive blocked queries. |
312
+ | Average Time Between Allowed Queries | Average interval between consecutive allowed queries. |
313
+
314
+
315
+ ## 📄 License
316
+ [MIT](LICENSE)
piholelongtermstats-0.2.0/README.md ADDED
@@ -0,0 +1,288 @@
1
+ # Pi Hole Long Term Statistics v.0.2.0
2
+
3
+ A dashboard built with **Dash** and **Plotly** to explore long-term DNS query data from **Pi-hole v.6** FTL database files. Visualize allowed vs blocked domains, top clients, and query trends over time. I originally made this for my own use, but if you find it useful, a ⭐ would be awesome!
4
+
5
+
6
+ **Disclaimer : This is an unofficial, third-party project. The Pi Hole team and the development of [PiHole](https://pi-hole.net/) software is not related to this project.**
7
+
8
+
9
+ <div align="center">
10
+ <img src="https://raw.githubusercontent.com/davistdaniel/PiHoleLongTermStats/main/screenshots/screenshot1.png" alt="Demo Gif" width="600">
11
+ </div>
12
+
13
+ <div align="center">
14
+ <img src="https://raw.githubusercontent.com/davistdaniel/PiHoleLongTermStats/main/screenshots/demo.gif" alt="Demo Gif" width="600">
15
+ </div>
16
+
17
+ See more [screenshots](https://github.com/davistdaniel/PiHoleLongTermStats/blob/main/screenshots/screenshots.md). (The screenshots use a mock database.)
18
+
19
+ ## 🧰 Features
20
+ - ➕ Combine multiple databases and visualize consolidated stats.
21
+ - 🗂️ Info cards : Query stats, Activity stats, Day and Night stats. See [all supported metrics](https://github.com/davistdaniel/PiHoleLongTermStats?tab=readme-ov-file#supported-metrics).
22
+ - 📈 Interactive charts for query trends and client behavior, heatmaps showing day-hour stats, reply-times visualisation and more.
23
+ - 🔍 Filter queries by client.
24
+ - 🌐 View any number of top blocked/allowed domains, top clients.
25
+ - 📅 Analyze queries and compute stats over a custom date range and visualize them.
26
+ - ❌ Exclude domains using regex patterns before computing stats.
27
+
28
+ ## 📦 Dependencies
29
+
30
+ - Python (>=3.11). See `requirements.txt` for dependencies.
31
+ - Pi-hole (> v.6) FTL database file (pihole-FTL.db)
32
+
33
+ ## 🚀 Getting Started
34
+
35
+ > [!WARNING]
36
+ > Using your actual Pi-hole FTL db file for querying is **not** recommended and it is advised to use a copy. Place the copy in the project root or specify its path using the `--db_path` argument or `PIHOLE_LT_STATS_DB_PATH` environment variable. In any case, PiHoleLongTermStats does not monitor for changes in the Pi-hole FTL db file even if you mount it.
37
+
38
+ > [!TIP]
39
+ > * You can set up a cron job to periodically copy the FTL database to the `db_path` `PIHOLE_LT_STATS_DB_PATH` location, ensuring your stats are updated without touching the live database. Use the reload button in the dashboard to refresh the stats.
40
+ > * Set your timezone (e.g "Europe/Berlin") using `--timezone` or `PIHOLE_LT_STATS_TIMEZONE`.
41
+
42
+ > [!IMPORTANT]
43
+ > * PiHoleLongTermStats reloads the Pi-hole FTL database and recalculates stats whenever the dashboard is refreshed or the reload button is clicked.
44
+ > * If no date range is selected, it uses the default period set by `--days` or `PIHOLE_LT_STATS_DAYS`.
45
+ > * Large date ranges may lead to increased memory usage.
46
+ > * When multiple database files are provided, PiHoleLongTermStats concatenates them into a single dataframe and sorts the combined data by timestamp. Duplicate entries are **not** removed for calculating stats. Consolidating multiple databases can lead to increased memory usage.
47
+
48
+ > [!TIP]
49
+ > There are multiple ways to run the dashboard: using Python or Docker.
50
+
51
+ ### 🐳 Using Docker
52
+
53
+ <details>
54
+ <summary>Click to expand.</summary>
55
+
56
+
57
+ If you have a copy of your `pihole-FTL.db` file, you can quickly run the dashboard using Docker Compose.
58
+
59
+ 1. Make a directory for PiHoleLongtermStats:
60
+ ```bash
61
+ mkdir PiHoleLongTermStats
62
+ cd PiHoleLongTermStats
63
+ ```
64
+
65
+ 2. Make a copy/backup of your `pihole-FTL.db` (**Important!**) and place it in the PiHoleLongTermStats directory:
66
+
67
+ ```bash
68
+ # Example: Copy from the default Pi-hole location
69
+ sudo cp /etc/pihole/pihole-FTL.db .
70
+ # Ensure the user running the app has read permissions
71
+ sudo chown $USER:$USER pihole-FTL.db
72
+ ```
73
+ 3. Make a docker-compose.yml file in the same directory:
74
+
75
+ ```docker
76
+ services:
77
+ pihole-long-term-stats:
78
+ image: ghcr.io/davistdaniel/piholelongtermstats:latest
79
+ container_name: pihole-lt-stats
80
+ ports:
81
+ - "9292:9292" # Map host port to container port
82
+ volumes:
83
+ - ./pihole-FTL.db:/app/pihole-FTL.db:ro # Path to your Pi-hole DB file (adjust if it's not in current directory)
84
+ # To include additional Pi-hole databases, mount each one similarly:
85
+ #- ./pihole-FTL-2.db:/app/pihole-FTL-2.db:ro
86
+ environment:
87
+ - PIHOLE_LT_STATS_DB_PATH=/app/pihole-FTL.db # Path inside the container to the mounted DB file
88
+
89
+ # Provide multiple databases by listing their container paths as a
90
+ # comma-separated string, e.g.:
91
+ #- PIHOLE_LT_STATS_DB_PATH=/app/pihole-FTL.db,/app/pihole-FTL-2.db
92
+
93
+ - PIHOLE_LT_STATS_DAYS=31 # Number of days from now of data to analyze; change if desired
94
+ - PIHOLE_LT_STATS_PORT=9292 # Port the app listens to inside container; keep in sync with ports mapping
95
+ - PIHOLE_LT_STATS_NCLIENTS=10 # Number of clients to show in top clients plots
96
+ - PIHOLE_LT_STATS_NDOMAINS=10 # Number of domains to show in top domains plots
97
+ - PIHOLE_LT_STATS_TIMEZONE=UTC # timezone for display
98
+ #- PIHOLE_LT_STATS_IGNORE_DOMAINS=.*\.local # regex patterns for excluding domains. Example: to exclude all .local domains use .*\.local
99
+
100
+ # To ignore multiple domain patterns, separate each regex with a comma.
101
+ # example definition below ignores: anything ending in .local, anything starting with ads, exactly example.com
102
+ #- PIHOLE_LT_STATS_IGNORE_DOMAINS=.*\.local,^ads\.,^example\.com$
103
+
104
+ restart: unless-stopped
105
+ ```
106
+ and run using :
107
+
108
+ ```bash
109
+ sudo docker compose up -d
110
+ ```
111
+ 4. Open your browser and visit [http://localhost:9292](http://localhost:9292)
112
+ </details>
113
+
114
+
115
+ ### 🐍 Using Python
116
+
117
+ If installing using python, you can install from this git repo or as a package from PyPi.
118
+
119
+ #### Install from PyPi :
120
+
121
+ <details>
122
+ <summary>Click to expand.</summary>
123
+
124
+ 1. Install PiHoleLongTermStats from PyPi
125
+
126
+ ```bash
127
+ python -m pip install piholelongtermstats
128
+ ````
129
+
130
+ 2. Make a directory for PiHoleLongtermStats (optional):
131
+
132
+ ```bash
133
+ mkdir PiHoleLongTermStats
134
+ cd PiHoleLongTermStats
135
+ ```
136
+
137
+ 3. Make a copy/backup of your `pihole-FTL.db` (**Important!**) and place it in the PiHoleLongTermStats directory:
138
+
139
+ ```bash
140
+ # Example: Copy from the default Pi-hole location
141
+ sudo cp /etc/pihole/pihole-FTL.db .
142
+ # Ensure the user running the app has read permissions
143
+ sudo chown $USER:$USER pihole-FTL.db
144
+ ```
145
+ 4. Run the app:
146
+
147
+ ```bash
148
+ piholelongtermstats [OPTIONS]
149
+ ```
150
+ 5. Open your browser and visit [http://localhost:9292](http://localhost:9292)
151
+
152
+
153
+ <details>
154
+ <summary><b>Examples for python (Click to expand.)</b></summary>
155
+
156
+ To start the dashboard and visualize a single pihole-FTL database file for the last 15 days, with top 20 clients and top 15 domains on port 9292 while ingoring all domains which end with ".local":
157
+
158
+ ```bash
159
+ piholelongtermstats --db_path pihole-FTL.db --days 15 --n_clients 20 --n_domains 15 --port 9292 --ignore-domains ".*\.local"
160
+ ```
161
+ To combine two databases, provide paths as comma-separated strings:
162
+
163
+ ```bash
164
+ piholelongtermstats --db_path pihole-FTL.db,pihole-FTL-2.db
165
+ ```
166
+ To exclude multiple domains, provide comma-separated regex patterns:
167
+
168
+ ```bash
169
+ piholelongtermstats --ignore-domains ".*\.local,.*\.apple.com"
170
+ ```
171
+ </details>
172
+
173
+ </details>
174
+
175
+ #### Install from source :
176
+
177
+ <details>
178
+ <summary>Click to expand.</summary>
179
+
180
+ 1. Clone this repository and move into the project folder:
181
+
182
+ ```bash
183
+ git clone https://github.com/davistdaniel/PiHoleLongTermStats.git
184
+ cd PiHoleLongTermStats
185
+ ```
186
+
187
+ 2. Install dependencies using pip:
188
+
189
+ ```bash
190
+ pip install -r requirements.txt
191
+ ```
192
+
193
+ 3. Make a copy/backup of your `pihole-FTL.db` (**Important!**) and place it in the PiHoleLongTermStats directory:
194
+ ```bash
195
+ # Example: Copy from the default Pi-hole location
196
+ sudo cp /etc/pihole/pihole-FTL.db .
197
+ # Ensure the user running the app has read permissions
198
+ sudo chown $USER:$USER pihole-FTL.db
199
+ ```
200
+
201
+ 4. Run the app:
202
+
203
+ ```bash
204
+ python piholelongtermstats/app.py [OPTIONS]
205
+ ```
206
+
207
+ See the Configuration section below for available options.
208
+
209
+ 5. Open your browser and visit [http://localhost:9292](http://localhost:9292)
210
+
211
+
212
+ <details>
213
+ <summary><b>Examples for python (Click to expand.)</b></summary>
214
+
215
+ To start the dashboard and visualize a single pihole-FTL database file for the last 15 days, with top 20 clients and top 15 domains on port 9292 while ingoring all domains which end with ".local":
216
+
217
+ ```bash
218
+ python piholelongtermstats/app.py --db_path pihole-FTL.db --days 15 --n_clients 20 --n_domains 15 --port 9292 --ignore-domains ".*\.local"
219
+ ```
220
+ To combine two databases, provide paths as comma-separated strings:
221
+
222
+ ```bash
223
+ python piholelongtermstats/app.py --db_path pihole-FTL.db,pihole-FTL-2.db
224
+ ```
225
+ To exclude multiple domains, provide comma-separated regex patterns:
226
+
227
+ ```bash
228
+ python piholelongtermstats/app.py --ignore-domains ".*\.local,.*\.apple.com"
229
+ ```
230
+ </details>
231
+ </details>
232
+
233
+ ## ⚙️ Configuration
234
+
235
+ You can configure the application using command-line arguments or environment variables:
236
+
237
+ | Command-Line Argument | Environment Variable | Default Value | Description |
238
+ |-----------------------|------------------------------|-----------------|--------------------------------------------------|
239
+ | `--db_path` | `PIHOLE_LT_STATS_DB_PATH` | `pihole-FTL.db` | Path to the copied Pi-hole database file. Multiple databases can be combined by providing paths as comma-separated strings. |
240
+ | `--days` | `PIHOLE_LT_STATS_DAYS` | `31` | Number of days back from today to analyze. |
241
+ | `--port` | `PIHOLE_LT_STATS_PORT` | `9292` | Port number to serve the Dash app on. |
242
+ | `--n_clients` | `PIHOLE_LT_STATS_NCLIENTS` | `10` | Number of top clients to show in top clients plots. |
243
+ | `--n_domains` | `PIHOLE_LT_STATS_NDOMAINS` | `10` | Number of top clients to show in top clients plots. |
244
+ | `--port` | `PIHOLE_LT_STATS_TIMEZONE` | `UTC` | Timezone for displaying times in the dashboard. |
245
+ | `--ignore-domains` | `PIHOLE_LT_STATS_IGNORE_DOMAINS` | `""` | Comma-separated regex patterns to exclude domains from from stats (e.g to exlcude all .local domains, use ".*\.local") |
246
+
247
+ ## 🧑‍💻 Contributing
248
+
249
+ Any contribution, feature ideas or bug fixes are always welcome.
250
+
251
+ ## Star History
252
+
253
+ [![Star History Chart](https://api.star-history.com/svg?repos=davistdaniel/PiHoleLongTermStats&type=date&legend=top-left)](https://www.star-history.com/#davistdaniel/PiHoleLongTermStats&type=date&legend=top-left)
254
+
255
+ ## Supported metrics
256
+ | Metric | Description |
257
+ |--------|-------------|
258
+ | Allowed Queries | Total number of queries that were allowed through the Pi-hole. |
259
+ | Blocked Queries | Total number of queries that were blocked by the Pi-hole. |
260
+ | Top Allowed Domain | The domain which was allowed the most |
261
+ | Top Blocked Domain | The domain which was blocked the most |
262
+ | Total Unique Clients | The total number of unique devices that made queries. |
263
+ | Total Queries | Total number of queries processed by the Pi-hole. |
264
+ | Highest number of queries were on | The date with the peak query count. |
265
+ | Lowest number of queries were on | The date with the lowest query count. |
266
+ | Average reply time | The average time it takes for the Pi-hole to respond to a query. |
267
+ | Most Active Hour | The hour with the highest number of queries. |
268
+ | Least Active Hour | The hour with the lowest number of queries. |
269
+ | Most Active Day of the Week | The day with the highest query activity. |
270
+ | Least Active Day of the Week | The day with the lowest query activity. |
271
+ | Longest Blocking Streak | The longest consecutive period where queries were blocked. |
272
+ | Longest Allowing Streak | The longest consecutive period where queries were allowed. |
273
+ | Total queries during the day | Total number of queries made during daytime hours (06:00 to 23:59). |
274
+ | Total queries during the night | Total number of queries made during nighttime hours. |
275
+ | Top allowed domain during the day | The most allowed domain during the day. |
276
+ | Top blocked domain during the day | The most blocked domain during the day. |
277
+ | Top allowed domain during the night | The most allowed domain during the night. |
278
+ | Top blocked domain during the night | The most blocked domain during the night. |
279
+ | Most Persistent Client | The client that made the highest number of queries. |
280
+ | Most Diverse Client | The client that queried a blocked domain the most times. |
281
+ | Longest Idle Period | The longest period without any queries. |
282
+ | Slowest Responding Domain | The domain with the highest average response time. |
283
+ | Average Time Between Blocked Queries | Average interval between consecutive blocked queries. |
284
+ | Average Time Between Allowed Queries | Average interval between consecutive allowed queries. |
285
+
286
+
287
+ ## 📄 License
288
+ [MIT](LICENSE)
piholelongtermstats-0.2.0/piholelongtermstats/__init__.py ADDED
@@ -0,0 +1,3 @@
1
+ ## Author : Davis T. Daniel
2
+ ## PiHoleLongTermStats v.0.2.0
3
+ ## License : MIT