10 KiB
10 KiB
AdguardHome Prometheus Exporter
/badge.svg?branch=master){kind=icon}
This is a Prometheus exporter for AdguardHome's Raspberry PI ad blocker. It is based on the famous pihole-exporter available here
Grafana dashboard is available here on the Grafana dashboard website and also here on the GitHub repository.
Prerequisites
Installation
Download binary
You can download the latest version of the binary built for your architecture here:
- Architecture i386 [ Darwin / FreeBSD / Linux / Windows ]
- Architecture amd64 [ Darwin / FreeBSD / Linux / Windows ]
- Architecture arm [ Linux ]
- Architecture arm64 [ Linux ]
From sources
Optionally, you can download and build it from the sources. You have to retrieve the project sources by using one of the following way:
$ go get -u github.com/ebrianne/adguard-exporter
# or
$ git clone https://github.com/ebrianne/adguard-exporter.git
Install the needed vendors:
$ GO111MODULE=on go mod vendor
Then, build the binary (here, an example to run on Raspberry PI ARM architecture):
$ GOOS=linux GOARCH=arm GOARM=7 go build -o adguard_exporter .
Using Docker
The exporter has been made available as a docker image. You can simply run it by the following command and pass the configuration with environment variables:
docker run \
-e 'adguard_protocol=http' \
-e 'adguard_hostname=192.168.10.252' \
-e 'adguard_username=admin' \
-e 'adguard_password=mypassword' \
-e 'adguard_port=' \ #optional if adguard is not using port 80 (http)/443 (https)
-e 'interval=10s' \
-e 'log_limit=10000' \
-e 'server_port=9617' \
-p 9617:9617 \
ebrianne/adguard-exporter:latest
If you prefer you can use an .env file where the environment variables are defined and using the command:
docker run --env-file=.env -p 9617:9617 \
ebrianne/adguard-exporter:latest
You can also use docker-compose passing the environment file or using secrets locally
Local with environment file
version: "3.7"
services:
adguard_exporter:
image: ebrianne/adguard-exporter:latest
restart: always
ports:
- "9617:9617"
env_file:
- .env
Local with secret file (compose version 3 minimum)
version: "3.7"
secrets:
my-adguard-pass:
file: ./my-adguard-pass.txt
services:
adguard_exporter:
image: ebrianne/adguard-exporter:latest
restart: always
secrets:
- my-adguard-pass
ports:
- "9617:9617"
environment:
- adguard_protocol=http
- adguard_hostname=192.168.10.252
- adguard_username=admin
- adguard_password=/run/secrets/my-adguard-pass
- adguard_port= #optional
- interval=10s
- log_limit=10000
Swarm mode (docker swarm init)
echo "mypassword" | docker secret create my-adguard-pass -
Here is an example of docker-compose file.
version: "3.7"
secrets:
my-adguard-pass:
external: true
services:
adguard_exporter:
image: ebrianne/adguard-exporter:latest
restart: always
secrets:
- my-adguard-pass
ports:
- "9617:9617"
environment:
- adguard_protocol=http
- adguard_hostname=192.168.10.252
- adguard_username=admin
- adguard_password=/run/secrets/my-adguard-pass
- adguard_port= #optional
- interval=10s
- log_limit=10000
Usage
In order to run the exporter, type the following command (arguments are optional):
Using a password
$ ./adguard_exporter -adguard_protocol https -adguard_hostname 192.168.10.252 -adguard_username admin -adguard_password qwerty -log_limit 10000
2020/11/04 17:16:14 ---------------------------------------
2020/11/04 17:16:14 - AdGuard Home exporter configuration -
2020/11/04 17:16:14 ---------------------------------------
2020/11/04 17:16:14 AdguardProtocol : https
2020/11/04 17:16:14 AdguardHostname : 192.168.10.252
2020/11/04 17:16:14 AdguardUsername : admin
2020/11/04 17:16:14 AdGuard Authentication Method : AdguardPassword
2020/11/04 17:16:14 ServerPort : 9617
2020/11/04 17:16:14 Interval : 10s
2020/11/04 17:16:14 LogLimit : 10000
2020/11/04 17:16:14 ---------------------------------------
2020/11/04 17:16:14 New Prometheus metric registered: avg_processing_time
2020/11/04 17:16:14 New Prometheus metric registered: num_dns_queries
2020/11/04 17:16:14 New Prometheus metric registered: num_blocked_filtering
2020/11/04 17:16:14 New Prometheus metric registered: num_replaced_parental
2020/11/04 17:16:14 New Prometheus metric registered: num_replaced_safebrowsing
2020/11/04 17:16:14 New Prometheus metric registered: num_replaced_safesearch
2020/11/04 17:16:14 New Prometheus metric registered: top_queried_domains
2020/11/04 17:16:14 New Prometheus metric registered: top_blocked_domains
2020/11/04 17:16:14 New Prometheus metric registered: top_clients
2020/11/04 17:16:14 New Prometheus metric registered: query_types
2020/11/04 17:16:14 New Prometheus metric registered: running
2020/11/04 17:16:14 New Prometheus metric registered: protection_enabled
2020/11/04 17:16:14 Starting HTTP server
2020/11/04 17:16:30 New tick of statistics: 3824 ads blocked / 36367 total DNS queries
Once the exporter is running, you also have to update your prometheus.yml configuration to let it scrape the exporter:
scrape_configs:
- job_name: 'adguard'
static_configs:
- targets: ['localhost:9617']
Available CLI options
# Interval of time the exporter will fetch data from Adguard
-interval duration (optional) (default 10s)
# Protocol to use to query Adguard
-adguard_protocol string (optional: "http", "https") (default "http")
# Hostname of the Raspberry PI where Adguard is installed
-adguard_hostname string (optional) (default "127.0.0.1")
# Username to login to Adguard Home
-adguard_username string (optional)
# Password defined on the Adguard interface
-adguard_password string (optional)
# Port to use to communicate with Adguard API
-adguard_port string (optional)
# Limit for the return log data
-log_limit string (optional) (default "1000")
# Port to be used for the exporter
-server_port string (optional) (default "9617")
Available Prometheus metrics
| Metric name | Description |
|---|---|
| adguard_avg_processing_time | This represent the average DNS query processing time |
| adguard_num_blocked_filtering | This represent the number of blocked DNS queries |
| adguard_num_dns_queries | This represent the number of DNS queries |
| adguard_num_replaced_parental | This represent the number of blocked DNS queries (parental) |
| adguard_num_replaced_safebrowsing | This represent the number of blocked DNS queries (safe browsing) |
| adguard_num_replaced_safesearch | This represent the number of blocked DNS queries (safe search) |
| adguard_top_blocked_domains | This represent the top blocked domains |
| adguard_top_clients | This represent the top clients |
| adguard_top_queried_domains | This represent the top domains that are queried |
| adguard_query_types | This represent the types of DNS queries |
| running | Is Adguard running? |
| protection_enabled | Is the protection enabled? |
Systemd file
Ubuntu
One can enable the program to work at startup by writing a systemd file. You can put this file in /etc/systemd/system/adguard-home.service
[Unit]
Description=AdGuard-Exporter
After=syslog.target network-online.target
Requires=AdGuardHome.Service
[Service]
ExecStart=/opt/adguard_exporter/adguard_exporter-linux-arm -adguard_protocol http -adguard_hostname <hostname> -adguard_username <username> -adguard_password <password> -log_limit 5000
Restart=on-failure
RestartSec=10s
[Install]
WantedBy=multi-user.target
Then do this command to start the service:
$ sudo systemctl start adguard-home.service
To enable the service at startup:
$ sudo systemctl enable adguard-home.service