AdguardHome Prometheus Exporter

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
      - server_port=9617
      - 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
      - server_port=9617
      - 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

mvadu/adguard-exporter