{"id":13582332,"url":"https://github.com/eko/pihole-exporter","last_synced_at":"2025-04-10T20:53:01.470Z","repository":{"id":37851262,"uuid":"185683446","full_name":"eko/pihole-exporter","owner":"eko","description":"A Prometheus exporter for PI-Hole's Raspberry PI ad blocker","archived":false,"fork":false,"pushed_at":"2025-04-02T04:24:09.000Z","size":839,"stargazers_count":1000,"open_issues_count":39,"forks_count":111,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-04-03T13:43:59.076Z","etag":null,"topics":["docker","grafana","grafana-dashboard","hacktoberfest","pihole","prometheus","prometheus-exporter","raspberry-pi"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eko.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-05-08T21:44:42.000Z","updated_at":"2025-04-02T10:49:58.000Z","dependencies_parsed_at":"2023-11-11T09:21:33.231Z","dependency_job_id":"f1a675b7-25c7-40cd-b408-5d36d4f9f1b9","html_url":"https://github.com/eko/pihole-exporter","commit_stats":{"total_commits":202,"total_committers":36,"mean_commits":5.611111111111111,"dds":0.594059405940594,"last_synced_commit":"1e0f818cf5a335ef0d049b8ec204befaf8031096"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eko%2Fpihole-exporter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eko%2Fpihole-exporter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eko%2Fpihole-exporter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eko%2Fpihole-exporter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eko","download_url":"https://codeload.github.com/eko/pihole-exporter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248297012,"owners_count":21080309,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","grafana","grafana-dashboard","hacktoberfest","pihole","prometheus","prometheus-exporter","raspberry-pi"],"created_at":"2024-08-01T15:02:36.404Z","updated_at":"2025-04-10T20:53:01.419Z","avatar_url":"https://github.com/eko.png","language":"Go","funding_links":[],"categories":["Go","raspberry-pi"],"sub_categories":[],"readme":"# Pi-hole Prometheus Exporter\n\n![Build/Push (master)](\u003chttps://github.com/eko/pihole-exporter/workflows/Build/Push%20(master)/badge.svg\u003e)\n[![GoDoc](https://godoc.org/github.com/eko/pihole-exporter?status.png)](https://godoc.org/github.com/eko/pihole-exporter)\n[![GoReportCard](https://goreportcard.com/badge/github.com/eko/pihole-exporter)](https://goreportcard.com/report/github.com/eko/pihole-exporter)\n\nThis is a Prometheus exporter for [Pi-hole](https://pi-hole.net/)'s Raspberry PI ad blocker.\n\n![Grafana dashboard](https://raw.githubusercontent.com/eko/pihole-exporter/master/dashboard.jpg)\n\nAvailable Grafana Dasboards:\n\n- Prometheus: [Grafana Labs](https://grafana.com/grafana/dashboards/10176-pi-hole-exporter/) / [JSON/Github](https://raw.githubusercontent.com/eko/pihole-exporter/master/grafana/dashboard.json) --\u003e [Preview](https://raw.githubusercontent.com/eko/pihole-exporter/master/dashboard.jpg)\n- InfluxDB 2 (Flux): [Grafana Labs](https://grafana.com/grafana/dashboards/17094-pi-hole-exporter-influxdb-2/) / [JSON/Github](https://raw.githubusercontent.com/eko/pihole-exporter/master/grafana/dashboard-influxdb2.json) --\u003e [Preview](https://raw.githubusercontent.com/eko/pihole-exporter/master/dashboard-influxdb2.png)\n\n## Prerequisites\n\n- [Go](https://golang.org/doc/)\n\n## Installation\n\n### Download binary\n\nYou can download the latest version of the binary built for your architecture here:\n\n- Architecture **i386** [\n  [Linux](https://github.com/eko/pihole-exporter/releases/latest/download/pihole_exporter-linux-386) /\n  [Windows](https://github.com/eko/pihole-exporter/releases/latest/download/pihole_exporter-windows-386.exe)\n  ]\n- Architecture **amd64** [\n  [Darwin](https://github.com/eko/pihole-exporter/releases/latest/download/pihole_exporter-darwin-amd64) /\n  [Linux](https://github.com/eko/pihole-exporter/releases/latest/download/pihole_exporter-linux-amd64) /\n  [Windows](https://github.com/eko/pihole-exporter/releases/latest/download/pihole_exporter-windows-amd64.exe)\n  ]\n- Architecture **arm** [\n  [Darwin](https://github.com/eko/pihole-exporter/releases/latest/download/pihole_exporter-darwin-arm64) /\n  [Linux](https://github.com/eko/pihole-exporter/releases/latest/download/pihole_exporter-linux-arm)\n  ]\n\n### Using Docker\n\nThe exporter is also available as a [Docker image](https://hub.docker.com/r/ekofr/pihole-exporter).\nYou can run it using the following example and pass configuration environment variables:\n\n```\n$ docker run \\\n  -e 'PIHOLE_HOSTNAME=192.168.1.2' \\\n  -e 'PIHOLE_PASSWORD=mypassword' \\\n  -e 'PORT=9617' \\\n  -p 9617:9617 \\\n  ekofr/pihole-exporter:latest\n```\n\nOr use PiHole's `WEBPASSWORD` as an API token instead of the password\n\n```bash\n$ API_TOKEN=$(awk -F= -v key=\"WEBPASSWORD\" '$1==key {print $2}' /etc/pihole/setupVars.conf)\n$ docker run \\\n  -e 'PIHOLE_HOSTNAME=192.168.1.2' \\\n  -e \"PIHOLE_PASSWORD=$API_TOKEN\" \\\n  -e 'PORT=9617' \\\n  -p 9617:9617 \\\n  ekofr/pihole-exporter:latest\n```\n\nIf you are running pi-hole behind https, you must both set the `PIHOLE_PROTOCOL` environment variable\nas well as include your ssl certificates to the docker image as it does not have any baked in:\n\n```\n$ docker run \\\n  -e 'PIHOLE_PROTOCOL=https' \\\n  -e 'PIHOLE_HOSTNAME=192.168.1.2' \\\n  -e 'PIHOLE_PASSWORD=mypassword' \\\n  -e 'PORT=9617' \\\n  -v '/etc/ssl/certs:/etc/ssl/certs:ro' \\\n  -p 9617:9617 \\\n  ekofr/pihole-exporter:latest\n```\n\nA single instance of pihole-exporter can monitor multiple pi-holes instances.\nTo do so, you can specify a list of hostnames, protocols, passwords/API tokens and ports by separating them with commas in their respective environment variable:\n\n```\n$ docker run \\\n  -e 'PIHOLE_PROTOCOL=http,http,http\" \\\n  -e 'PIHOLE_HOSTNAME=192.168.1.2,192.168.1.3,192.168.1.4\"' \\\n  -e \"PIHOLE_PASSWORD=$API_TOKEN1,$API_TOKEN2,$API_TOKEN3\" \\\n  -e \"PIHOLE_PORT=8080,8081,8080\" \\\n  -e 'PORT=9617' \\\n  -p 9617:9617 \\\n  ekofr/pihole-exporter:latest\n```\n\nIf port, protocol and API token/password is the same for all instances, you can specify them only once:\n\n```\n$ docker run \\\n  -e 'PIHOLE_PROTOCOL=http\" \\\n  -e 'PIHOLE_HOSTNAME=192.168.1.2,192.168.1.3,192.168.1.4\"' \\\n  -e \"PIHOLE_PASSWORD=$API_TOKEN\" \\\n  -e \"PIHOLE_PORT=8080\" \\\n  -e 'PORT=9617' \\\n  -p 9617:9617 \\\n  ekofr/pihole-exporter:latest\n```\n\n### From sources\n\nOptionally, you can download and build it from the sources. You have to retrieve the project sources by using one of the following way:\n\n```bash\n$ go install github.com/eko/pihole-exporter@latest\n# or\n$ git clone https://github.com/eko/pihole-exporter.git\n```\n\nInstall the needed vendors:\n\n```\n$ go mod vendor\n```\n\nThen, build the binary (here, an example to run on Raspberry PI ARM architecture):\n\n```bash\n$ GOOS=linux GOARCH=arm GOARM=7 go build -o pihole_exporter .\n```\n\n## Usage\n\nIn order to run the exporter, type the following command (arguments are optional):\n\nUsing a password\n\n```bash\n$ ./pihole_exporter -pihole_hostname 192.168.1.10 -pihole_password azerty\n```\n\nOr use PiHole's `WEBPASSWORD` as an API token instead of the password\n\n```bash\n$ API_TOKEN=$(awk -F= -v key=\"WEBPASSWORD\" '$1==key {print $2}' /etc/pihole/setupVars.conf)\n$ ./pihole_exporter -pihole_hostname 192.168.1.10 -pihole_password $API_TOKEN\n```\n\n```bash\n2019/05/09 20:19:52 ------------------------------------\n2019/05/09 20:19:52 -  Pi-hole exporter configuration  -\n2019/05/09 20:19:52 ------------------------------------\n2019/05/09 20:19:52 PIHoleHostname : 192.168.1.10\n2019/05/09 20:19:52 PIHolePassword : azerty\n2019/05/09 20:19:52 Port : 9617\n2019/05/09 20:19:52 Timeout : 5s\n2019/05/09 20:19:52 ------------------------------------\n2019/05/09 20:19:52 New Prometheus metric registered: domains_blocked\n2019/05/09 20:19:52 New Prometheus metric registered: dns_queries_today\n2019/05/09 20:19:52 New Prometheus metric registered: ads_blocked_today\n2019/05/09 20:19:52 New Prometheus metric registered: ads_percentag_today\n2019/05/09 20:19:52 New Prometheus metric registered: unique_domains\n2019/05/09 20:19:52 New Prometheus metric registered: queries_forwarded\n2019/05/09 20:19:52 New Prometheus metric registered: queries_cached\n2019/05/09 20:19:52 New Prometheus metric registered: clients_ever_seen\n2019/05/09 20:19:52 New Prometheus metric registered: unique_clients\n2019/05/09 20:19:52 New Prometheus metric registered: dns_queries_all_types\n2019/05/09 20:19:52 New Prometheus metric registered: reply\n2019/05/09 20:19:52 New Prometheus metric registered: top_queries\n2019/05/09 20:19:52 New Prometheus metric registered: top_ads\n2019/05/09 20:19:52 New Prometheus metric registered: top_sources\n2019/05/09 20:19:52 New Prometheus metric registered: forward_destinations\n2019/05/09 20:19:52 New Prometheus metric registered: querytypes\n2019/05/09 20:19:52 New Prometheus metric registered: status\n2019/05/09 20:19:52 New Prometheus metric registered: queries_last_10min\n2019/05/09 20:19:52 New Prometheus metric registered: ads_last_10min\n2019/05/09 20:19:52 Starting HTTP server\n2019/05/09 20:19:54 New tick of statistics: 648 ads blocked / 66796 total DNS querie\n...\n```\n\nOnce the exporter is running, you also have to update your `prometheus.yml` configuration to let it scrape the exporter:\n\n```yaml\nscrape_configs:\n    - job_name: \"pihole\"\n      static_configs:\n          - targets: [\"localhost:9617\"]\n```\n\n## Available CLI options\n\n```bash\n# Hostname of the host(s) where Pi-hole is installed\n  -pihole_hostname string (optional) (default \"127.0.0.1\")\n\n# Password defined on the Pi-hole interface\n  -pihole_password string (optional)\n\n# Timeout to connect and retrieve data from a Pi-hole instance\n  -timeout duration (optional) (default 5s)\n\n# WEBPASSWORD / api token defined on the Pi-hole interface at `/etc/pihole/setupVars.conf`\n  -pihole_password string (optional)\n\n# Address to be used for the exporter\n  -bind_addr string (optional) (default \"0.0.0.0\")\n\n# URL Context (first segments of URL path) to the PI-hole admin application\n  -pihole_admin_context string (optional) (default \"admin\")\n\n# Port to be used for the exporter\n  -port string (optional) (default \"9617\")\n```\n\n## Available Prometheus metrics\n\n|         Metric name          | Description                                                                               |\n| :--------------------------: | ----------------------------------------------------------------------------------------- |\n| pihole_domains_being_blocked | This represent the number of domains being blocked                                        |\n|   pihole_dns_queries_today   | This represent the number of DNS queries made over the current day                        |\n|   pihole_ads_blocked_today   | This represent the number of ads blocked over the current day                             |\n| pihole_ads_percentage_today  | This represent the percentage of ads blocked over the current day                         |\n|    pihole_unique_domains     | This represent the number of unique domains seen                                          |\n|   pihole_queries_forwarded   | This represent the number of queries forwarded                                            |\n|    pihole_queries_cached     | This represent the number of queries cached                                               |\n|   pihole_clients_ever_seen   | This represent the number of clients ever seen                                            |\n|    pihole_unique_clients     | This represent the number of unique clients seen                                          |\n| pihole_dns_queries_all_types | This represent the number of DNS queries made for all types                               |\n|         pihole_reply         | This represent the number of replies made for all types                                   |\n|      pihole_top_queries      | This represent the number of top queries made by Pi-hole by domain                        |\n|        pihole_top_ads        | This represent the number of top ads made by Pi-hole by domain                            |\n|      pihole_top_sources      | This represent the number of top sources requests made by Pi-hole by source host          |\n| pihole_forward_destinations  | This represent the number of forward destinations requests made by Pi-hole by destination |\n|      pihole_querytypes       | This represent the number of queries made by Pi-hole by type                              |\n|        pihole_status         | This represent if Pi-hole is enabled                                                      |\n|      queries_last_10min      | This represent the number of queries in the last full slot of 10 minutes                  |\n|        ads_last_10min        | This represent the number of ads in the last full slot of 10 minutes                      |\n\n## Pihole-Exporter Helm Chart\n\n[Link](https://github.com/SiM22/pihole-exporter-helm-chart)\n\nThis is a simple Helm Chart to deploy the exporter in a kubernetes cluster.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feko%2Fpihole-exporter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feko%2Fpihole-exporter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feko%2Fpihole-exporter/lists"}