I’ve been working on a Home Assistant app called AdGuard Log Viewer.
GitHub: GitHub - mefisto22/adguard_log_viewer · GitHub
I wanted something a bit more useful than just scrolling through AdGuard Home’s query log, especially when trying to answer questions like:
-
Which device is making these requests?
-
What domains does a specific person/device use most?
-
What is being blocked, and by which rule?
-
Which requests belong to YouTube, Google, telemetry, ads, tracking, IoT, etc.?
-
What happened during a specific time period?
So I ended up building a separate viewer and analyzer around the AdGuard Home query log.
What it does
The app imports DNS queries from AdGuard Home and stores them locally in SQLite. The web UI runs inside Home Assistant through Ingress.
Some of the current features:
-
Near real-time query log
-
Fast searchable/filterable log table
-
AND / OR filter builder with nested conditions
-
Saved filters
-
Filtering by domain, client, device, person, query type, status, blocked/allowed, AdGuard rule, upstream, response time and more
-
Automatic domain categorisation and tagging
-
Custom category/tag rules, including wildcard and regex matching
-
Manual tags for individual domains
-
Custom device names
-
Multiple devices can be assigned to the same person
-
Dashboard with timelines, top domains, blocked domains, devices, people, categories, tags, query types and upstream servers
-
Separate detail pages for domains, devices and people
-
English and Hungarian UI
-
Automatic language detection from Home Assistant
The log table is virtualised and most filtering/aggregation happens in SQLite, so it’s also designed to remain usable with fairly large query histories.
Home Assistant OS / AdGuard setup
There is one slightly unusual part of the installation.
Home Assistant OS does not allow one app to directly access another app’s /data directory, so the viewer cannot simply read AdGuard Home’s querylog.json.
Instead, it uses the AdGuard Home HTTP API.
Because of that, if you are using the official AdGuard Home app, you need to expose its Web Interface port (80/tcp) once. The README/DOCS has the setup steps.
After that, the app discovers the AdGuard installation through the Supervisor API and connects to it automatically.
Installation
Add the repository in:
Settings → Apps → Install app → ⋮ → Repositories
Repository:
Then install AdGuard Log Viewer and follow the one-time AdGuard setup described in the documentation.
The project is still fairly new, so feedback is very welcome — especially from people with larger AdGuard installations or setups different from mine.
If you run into a problem, feel free to open an issue on GitHub.
Screenshots:
