Regenerate integrations docs (#19816)
Co-authored-by: ilyam8 <22274335+ilyam8@users.noreply.github.com>
Netdata bot committed
Mar 10, 2025 at 07:54 UTC
e3484260d375a4066574bdffdd692d13f68374ae
1 file changed
+39
-22
src/go/plugin/go.d/collector/pihole/integrations/pi-hole.md
+39
-22
@@ -21,10 +21,11 @@ Module: pihole
21
22
## Overview
23
24
-This collector monitors Pi-hole instances using [PHP API](https://github.com/pi-hole/AdminLTE).
24
+This collector monitors Pi-hole instances using [Pi-hole API 6.0](https://ftl.pi-hole.net/master/docs/).
25
26
-The data provided by the API is for the last 24 hours. All collected values refer to this time period and not to the
27
-module's collection interval.
26
+It collects DNS query statistics including total queries, blocked domains, query types, resolution status, and client information.
27
+
28
+**Note**: This collector is not compatible with Pi-hole versions earlier than v6.0.
29
30
31
@@ -38,7 +39,14 @@ This collector supports collecting metrics from multiple instances of this integ
39
40
#### Auto-Detection
41
41
-This integration doesn't support auto-detection.
42
+By default, it detects Pi-hole instances running on:
43
+
44
+- localhost that are listening on port 80
45
+- within Docker containers
46
+
47
+> **Note that the Pi-hole API 6.0 requires a password**.
48
+> While Netdata can automatically detect Pi-hole instances and create data collection jobs, these jobs will fail unless you provide the necessary credentials.
49
+
50
51
#### Limits
52
@@ -67,15 +75,15 @@ Metrics:
75
76
| Metric | Dimensions | Unit |
77
|:------|:----------|:----|
70
-| pihole.dns_queries_total | queries | queries |
71
-| pihole.dns_queries | cached, blocked, forwarded | queries |
72
-| pihole.dns_queries_percentage | cached, blocked, forwarded | percentage |
73
-| pihole.unique_clients | unique | clients |
74
-| pihole.domains_on_blocklist | blocklist | domains |
75
-| pihole.blocklist_last_update | ago | seconds |
76
-| pihole.unwanted_domains_blocking_status | enabled, disabled | status |
77
-| pihole.dns_queries_types | a, aaaa, any, ptr, soa, srv, txt | percentage |
78
-| pihole.dns_queries_forwarded_destination | cached, blocked, other | percentage |
78
+| pihole.dns_queries_total | queries | queries/s |
79
+| pihole.dns_queries_blocked_percent | blocked | percent |
80
+| pihole.dns_queries_by_destination | cached, blocked, forwarded | queries/s |
81
+| pihole.dns_queries_by_type | A, AAA, ANY, SRV, SOA, PTR, TXT, NAPTR, MX, DS, RRSIG, DNSKEY, NS, SVCB, HTTPS, OTHER | queries/s |
82
+| pihole.dns_queries_by_status | UNKNOWN, GRAVITY, FORWARDED, CACHE, REGEX, DENYLIST, EXTERNAL_BLOCKED_IP, EXTERNAL_BLOCKED_NULL, EXTERNAL_BLOCKED_NXRA, GRAVITY_CNAME, REGEX_CNAME, DENYLIST_CNAME, RETRIED, RETRIED_DNSSEC, IN_PROGRESS, DBBUSY, SPECIAL_DOMAIN, CACHE_STALE, EXTERNAL_BLOCKED_EDE15 | queries/s |
83
+| pihole.dns_replies_by_status | UNKNOWN, NODATA, NXDOMAIN, CNAME, IP, DOMAIN, RRNAME, SERVFAIL, REFUSED, NOTIMP, DNSSEC, NONE, OTHER | replies/s |
84
+| pihole.active_clients | active | clients |
85
+| pihole.gravity_list_blocked_domains | blocked | domains |
86
+| pihole.gravity_list_last_update_time_ago | last_update_ago | seconds |
87
88
89
@@ -86,15 +94,23 @@ The following alerts are available:
94
95
| Alert name | On metric | Description |
96
|:------------|:----------|:------------|
89
-| [ pihole_blocklist_last_update ](https://github.com/netdata/netdata/blob/master/src/health/health.d/pihole.conf) | pihole.blocklist_last_update | gravity.list (blocklist) file last update time |
90
-| [ pihole_status ](https://github.com/netdata/netdata/blob/master/src/health/health.d/pihole.conf) | pihole.unwanted_domains_blocking_status | unwanted domains blocking is disabled |
97
+| [ pihole_gravity_list_last_update ](https://github.com/netdata/netdata/blob/master/src/health/health.d/pihole.conf) | pihole.gravity_list_last_update_time_ago | gravity.list (blocklist) file last update time |
98
99
100
## Setup
101
102
### Prerequisites
103
97
-No action required.
104
+#### Pi-hole v6.0 or newer
105
+
106
+This collector requires Pi-hole v6.0 or newer as it uses the [Pi-hole API 6.0](https://ftl.pi-hole.net/master/docs/).
107
+
108
+
109
+#### Authentication credentials
110
+
111
+Pi-hole administrator password is required for API authentication. Make sure to configure this in the collector settings even when using auto-detection.
112
+
113
+
114
115
### Configuration
116
@@ -119,13 +135,12 @@ The following options can be defined globally: update_every, autodetection_retry
135
136
| Name | Description | Default | Required |
137
|:----|:-----------|:-------|:--------:|
122
-| update_every | Data collection frequency. | 5 | no |
138
+| update_every | Data collection frequency. | 1 | no |
139
| autodetection_retry | Recheck interval in seconds. Zero means no recheck will be scheduled. | 0 | no |
140
| url | Server URL. | http://127.0.0.1 | yes |
125
-| setup_vars_path | Path to setupVars.conf. This file is used to get the web password. | /etc/pihole/setupVars.conf | no |
126
-| timeout | HTTP request timeout. | 5 | no |
141
+| timeout | HTTP request timeout. | 1 | no |
142
| username | Username for basic HTTP authentication. | | no |
128
-| password | Password for basic HTTP authentication. | | no |
143
+| password | Password for basic HTTP authentication. | | yes |
144
| proxy_url | Proxy URL. | | no |
145
| proxy_username | Username for proxy basic HTTP authentication. | | no |
146
| proxy_password | Password for proxy basic HTTP authentication. | | no |
@@ -152,6 +167,7 @@ A basic example configuration.
167
jobs:
168
- name: local
169
url: http://127.0.0.1
170
+ password: Gv7#pQm9Xy
171
172
```
173
</details>
@@ -167,7 +183,7 @@ jobs:
183
- name: local
184
url: https://203.0.113.11
185
tls_skip_verify: yes
170
- password: 1ebd33f882f9aa5fac26a7cb74704742f91100228eb322e41b7bd6e6aeb8f74b
186
+ password: bT4@zK1wVr
187
188
```
189
</details>
@@ -185,10 +201,11 @@ Collecting metrics from local and remote instances.
201
jobs:
202
- name: local
203
url: http://127.0.0.1
204
+ password: Gv7#pQm9Xy
205
206
- name: remote
207
url: http://203.0.113.10
191
- password: 1ebd33f882f9aa5fac26a7cb74704742f91100228eb322e41b7bd6e6aeb8f74b
208
+ password: bT4@zK1wVr
209
210
```
211
</details>