--- title: Pi-hole description: Integration to collect default Pi-hole metrics breadcrumbs: Docs > Integrations > Pi-hole --- # Pi-hole Supported OS Integration version3.15.0 ## Overview{% #overview %} This check monitors [Pi-hole](https://pi-hole.net/) through the Datadog Agent. ## Setup{% #setup %} The Pi-hole check is not included in the [Datadog Agent](https://app.datadoghq.com/account/settings/agent/latest) package, so you need to install it. ### Installation{% #installation %} For Agent v7.21+ / v6.21+, follow the instructions below to install the Pi-hole check on your host. See [Use Community Integrations](https://docs.datadoghq.com/agent/guide/use-community-integrations/) to install with the Docker Agent or earlier versions of the Agent. 1. Run the following command to install the Agent integration: ```shell sudo -u dd-agent -- datadog-agent integration install -t datadog-pihole== ``` 1. Configure your integration similar to core [integrations](https://docs.datadoghq.com/getting_started/integrations/). ### Configuration{% #configuration %} 1. Edit the `pihole.d/conf.yaml` file, in the `conf.d/` folder at the root of your Agent's configuration directory to start collecting your Pi-hole performance data. See the [sample pihole.d/conf.yaml](https://github.com/DataDog/integrations-extras/blob/master/pihole/datadog_checks/pihole/data/conf.yaml.example) for all available configuration options. 1. [Restart the Agent](https://docs.datadoghq.com/agent/guide/agent-commands/#start-stop-and-restart-the-agent). ### Validation{% #validation %} Run the [Agent's status subcommand](https://docs.datadoghq.com/agent/guide/agent-commands/#agent-status-and-information) and look for `pihole` under the Checks section. ### Log collection{% #log-collection %} Enable logs collection for Datadog Agent in `/etc/datadog-agent/datadog.yaml` on Linux platforms. On other platforms, see the [Agent Configuration Files guide](https://docs.datadoghq.com/agent/guide/agent-configuration-files/) for the location of your configuration file: ```yaml logs_enabled: true ``` - Enable this configuration block to your `pihole.d/conf.yaml` file to start collecting Logs: ```yaml logs: - type: file path: /var/log/pihole.log source: pihole ``` ## Data Collected{% #data-collected %} ### Metrics{% #metrics %} | | | | | **pihole.queries.blocked**(gauge) | Number of queries that were blocked (i.e. matched gravity block lists/regex/ denylist or upstream blocking). | | **pihole.queries.cached**(gauge) | Number of queries answered from Pihole cache. | | **pihole.queries.clients.active**(gauge) | Number of currently active clients (recent queries). | | **pihole.queries.clients.total**(gauge) | Total number of clients observed. | | **pihole.queries.forwarded**(gauge) | Number of queries forwarded to upstream DNS servers (i.e. allowed queries). | | **pihole.queries.frequency**(gauge) | Query frequency or rate (e.g. queries per second). | | **pihole.queries.gravity.domains\_being\_blocked**(gauge) | Number of domains currently blocked by the gravity blocklist. | | **pihole.queries.percent\_blocked**(gauge) | Percentage of total queries that were blocked. | | **pihole.queries.replies.BLOB**(gauge) | Replies containing binary blob data. | | **pihole.queries.replies.CNAME**(gauge) | Replies that return a CNAME (alias). | | **pihole.queries.replies.DOMAIN**(gauge) | Replies with a domain name. | | **pihole.queries.replies.DNSSEC**(gauge) | Replies indicating DNSSEC-specific status. | | **pihole.queries.replies.IP**(gauge) | Replies that return an IP (A or AAAA record). | | **pihole.queries.replies.NODATA**(gauge) | Replies that return 'No Data' (empty response). | | **pihole.queries.replies.NONE**(gauge) | Replies dropped intentionally (no response). | | **pihole.queries.replies.NOTIMP**(gauge) | Replies with 'Not Implemented' status. | | **pihole.queries.replies.NXDOMAIN**(gauge) | Replies that return NXDOMAIN (non-existent domain). | | **pihole.queries.replies.OTHER**(gauge) | Replies of types not otherwise classified. | | **pihole.queries.replies.REFUSED**(gauge) | Replies with 'Refused' status. | | **pihole.queries.replies.RRNAME**(gauge) | Replies that indicate the domain name in the query (RRNAME). | | **pihole.queries.replies.SERVFAIL**(gauge) | Replies with 'Server Failure' status. | | **pihole.queries.replies.UNKNOWN**(gauge) | Replies with unknown type (no reply yet). | | **pihole.queries.status.CACHE**(gauge) | Queries answered from cache. | | **pihole.queries.status.CACHE\_STALE**(gauge) | Queries answered from a stale cached response. | | **pihole.queries.status.DBBUSY**(gauge) | Queries blocked because the internal database was busy. | | **pihole.queries.status.DENYLIST**(gauge) | Queries blocked by an exact denylist entry. | | **pihole.queries.status.DENYLIST\_CNAME**(gauge) | Queries blocked during deep CNAME inspection due to denylist. | | **pihole.queries.status.EXTERNAL\_BLOCKED\_EDE15**(gauge) | Queries blocked by upstream server with EDE code 15. | | **pihole.queries.status.EXTERNAL\_BLOCKED\_IP**(gauge) | Queries blocked by upstream server via IP blocking. | | **pihole.queries.status.EXTERNAL\_BLOCKED\_NXRA**(gauge) | Queries blocked when upstream returns NXDOMAIN with RA bit unset. | | **pihole.queries.status.EXTERNAL\_BLOCKED\_NULL**(gauge) | Queries blocked due to upstream returning null (0.0.0.0 / ::) response. | | **pihole.queries.status.FORWARDED**(gauge) | Queries allowed and forwarded to upstream resolver. | | **pihole.queries.status.GRAVITY**(gauge) | Queries blocked by the gravity blocklist. | | **pihole.queries.status.GRAVITY\_CNAME**(gauge) | Queries blocked during deep CNAME inspection in gravity list. | | **pihole.queries.status.IN\_PROGRESS**(gauge) | Queries currently in progress (not yet resolved). | | **pihole.queries.status.REGEX**(gauge) | Queries blocked by regex filters. | | **pihole.queries.status.REGEX\_CNAME**(gauge) | Queries blocked during deep CNAME inspection due to regex. | | **pihole.queries.status.RETRIED**(gauge) | Queries that were retried (e.g. after failure). | | **pihole.queries.status.RETRIED\_DNSSEC**(gauge) | Queries retried during DNSSEC validation. | | **pihole.queries.status.SPECIAL\_DOMAIN**(gauge) | Queries about special domains (e.g. Apple Private Relay/ canary domains). | | **pihole.queries.status.UNKNOWN**(gauge) | Queries whose status is 'Unknown' (not yet classified). | | **pihole.queries.total**(gauge) | Total number of DNS queries received by Pihole (all types). | | **pihole.queries.types.A**(gauge) | Count of DNS queries of type A (IPv4 address record). | | **pihole.queries.types.AAAA**(gauge) | Count of DNS queries of type AAAA (IPv6 address record). | | **pihole.queries.types.ANY**(gauge) | Count of DNS queries of type ANY (request for all record types). | | **pihole.queries.types.DNSKEY**(gauge) | Count of DNS queries of type DNSKEY (DNSSEC public key). | | **pihole.queries.types.DS**(gauge) | Count of DNS queries of type DS (delegation signer/ DNSSEC). | | **pihole.queries.types.HTTPS**(gauge) | Count of DNS queries of type HTTPS (HTTPS service binding). | | **pihole.queries.types.MX**(gauge) | Count of DNS queries of type MX (mail exchange record). | | **pihole.queries.types.NAPTR**(gauge) | Count of DNS queries of type NAPTR (name authority pointer). | | **pihole.queries.types.NS**(gauge) | Count of DNS queries of type NS (name server record). | | **pihole.queries.types.OTHER**(gauge) | Count of queries of types not in the standard set. | | **pihole.queries.types.PTR**(gauge) | Count of DNS queries of type PTR (pointer records/ typically reverse DNS). | | **pihole.queries.types.RRSIG**(gauge) | Count of DNS queries of type RRSIG (DNSSEC signature record). | | **pihole.queries.types.SOA**(gauge) | Count of DNS queries of type SOA (start of authority). | | **pihole.queries.types.SRV**(gauge) | Count of DNS queries of type SRV (service locator record). | | **pihole.queries.types.SVCB**(gauge) | Count of DNS queries of type SVCB (service binding). | | **pihole.queries.types.TXT**(gauge) | Count of DNS queries of type TXT (text records). | | **pihole.queries.unique\_domains**(gauge) | Number of unique domain names queried in the measured period. | | **pihole.queries\_forwarded**(gauge) | Queries not blocked (legacy check only)*Shown as query* | | **pihole.domains\_being\_blocked**(gauge) | Domains that are currently being blocked (legacy check only) | | **pihole.ads\_percent\_blocked**(gauge) | Percentage of ads blocked today (legacy check only)*Shown as percent* | | **pihole.ads\_blocked\_today**(gauge) | Number of ads blocked today (legacy check only) | | **pihole.dns\_queries\_today**(gauge) | Amount of queries made to Pi-hole (legacy check only) | | **pihole.clients\_ever\_seen**(gauge) | Total clients (legacy check only) | | **pihole.unique\_clients**(gauge) | Total number of unique clients (legacy check only) | | **pihole.queries\_cached**(gauge) | Number of cached queries (legacy check only)*Shown as query* | | **pihole.unique\_domains**(gauge) | Number of unique domains seen (legacy check only) | | **pihole.reply\_nodata**(gauge) | Number of no data replies (legacy check only) | | **pihole.reply\_cname**(gauge) | Number of cname replies (legacy check only) | | **pihole.reply\_ip**(gauge) | Number of ip replies (legacy check only) | | **pihole.reply\_nxdomain**(gauge) | Number of nxdomain replies (legacy check only) | | **pihole.dns\_queries\_all\_types**(gauge) | Amount of queries made to Pi-hole of all types (legacy check only) | ### Events{% #events %} Pi-hole does not include any events. ### Service Checks{% #service-checks %} **pihole.running** Returns `CRITICAL` if the check can't access pihole, `OK` otherwise. *Statuses: ok, critical* ## Troubleshooting{% #troubleshooting %} Need help? Contact [Datadog support](https://docs.datadoghq.com/help/).