subtlepseudonym/pihole-exporter repository overview

⁠Pihole Exporter

⁠Running the container

docker create \
	--name pihole-exporter \
	--env "PIHOLE_DSN=file:/pihole/pihole-FTL.db?_query_only" \
	--volume "/local/path/to/ftl.db:/pihole/pihole-FTL.db:ro" \
	subtlepseudonym/pihole-exporter:latest

⁠Building this project

This project is intended to be run in docker.

docker build \
	--tag subtlepseudonym/pihole-exporter:latest \
	--file ./Dockerfile \
	.

Alternatively, you can run make docker if you've cloned the repo. This will automatically tag the image as well.

NOTE: you should have vtag from subtlepseudonym/utilities⁠ installed for auto-tagging to work properly. Without it, docker version tag will be 0.0.1-unknown

⁠Metrics

⁠Motivation

As of creating this project, the top two hits on google for pihole exporter use only gauges to represent the data scraped from Pihole. It has been expressed that scraped metrics should be instrumented from the point of view of the thing being instrumented⁠, implying that the use of gauges is the correct way to instrument the pihole API. Despite this, I hewed closer to the first-party prometheus instrumentation guidelines⁠ and sought to provide metrics whose type better represented the nature of the value being measured.

Specifically, there are many values exposed by the pihole API that perform daily counts. These daily counts are generated with a rolling stepwise function such that all queries (or blocked ads, clients, etc) in the last 23 hours plus those since the last hour are counted and the value is updated every hour. In practice, this leads to values that decrease by the amount of queries received during the upcoming one hour block, yesterday. I believe that this doesn't do a very good job of representing what should be monotonically increasing values; you can't un-make a DNS request. To retrieve absolute counts, I chose to make requests against the FTL database rather than the pihole API. This makes requests to the /metrics endpoint take a bit longer and require that this exporter has access to the pihole database file (which could be a prohibitive requirement depending upon your setup), but I believe it provides better metrics.