Pi-hole

Supported OS Linux Mac OS Windows

Integration version3.14.1

Overview

This check monitors Pi-hole through the Datadog Agent.

Setup

The Pi-hole check is not included in the Datadog Agent package, so you need to install it.

Installation

For Agent v7.21+ / v6.21+, follow the instructions below to install the Pi-hole check on your host. See 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:

    sudo -u dd-agent -- datadog-agent integration install -t datadog-pihole==<INTEGRATION_VERSION>

  2. Configure your integration similar to core integrations.

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 for all available configuration options.

  2. Restart the Agent.

Validation

Run the Agent’s status subcommand and look for pihole under the Checks section.

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 for the location of your configuration file:

logs_enabled: true
  • Enable this configuration block to your pihole.d/conf.yaml file to start collecting Logs:
    logs:
  - type: file
    path: /var/log/pihole.log
    source: pihole

Data Collected

Metrics

pihole.queries_forwarded
(gauge)		Queries not blocked
Shown as query
pihole.domains_being_blocked
(gauge)		Domains that are currently being blocked
pihole.ads_percent_blocked
(gauge)		Percentage of ads blocked today
Shown as percent
pihole.ads_blocked_today
(gauge)		Number of ads blocked today
pihole.dns_queries_today
(gauge)		Amount of queries made to Pi-hole
pihole.clients_ever_seen
(gauge)		Total clients
pihole.unique_clients
(gauge)		Total number of unique clients
pihole.queries_cached
(gauge)		Number of cached queries
Shown as query
pihole.unique_domains
(gauge)		Number of unique domains seen
pihole.reply_nodata
(gauge)		Number of no data replies
pihole.reply_cname
(gauge)		Number of cname replies
pihole.reply_ip
(gauge)		Number of ip replies
pihole.reply_nxdomain
(gauge)		Number of nxdomain replies
pihole.dns_queries_all_types
(gauge)		Amount of queries made to Pi-hole of all types

Events

Pi-hole does not include any events.

Service Checks

pihole.running
Returns CRITICAL if the check can’t access pihole, OK otherwise.
Statuses: ok, critical

Troubleshooting

Need help? Contact Datadog support.