Skip to content

Conversation

@mpreissner
Copy link

This integration collects DNS query logs and metrics from Pi-hole instances.

Features:

  • DNS query logs with full query details (client, upstream, DNSSEC, reply time)
  • Time-series metrics for query history and patterns
  • Summary statistics and blocking effectiveness metrics
  • Top clients and domains tracking (allowed and blocked)
  • Three comprehensive Kibana dashboards (Overview, Security & Blocking, DNS Analysis)
  • Three saved searches (Blocked Queries, DNSSEC Failures, Slow Queries)
  • Support for Pi-hole API v6+ with session-based authentication

Data streams:

  • dns_queries (logs): Individual DNS query records with timestamp-based pagination
  • query_history (metrics): 10-minute interval query volume trends
  • pihole_summary (metrics): Comprehensive DNS and blocking statistics
  • top_clients (metrics): Top 10 allowed and blocked clients
  • top_domains (metrics): Top 10 allowed and blocked domains

Technical details:

  • CEL input type for API integration
  • Time-series data streams with synthetic source for metrics
  • ECS field mappings for DNS data
  • Automatic session lifecycle management
  • Complete documentation with sample events

Type of change

  • Enhancement

Proposed commit message

Title: Add Pi-hole integration

Description:

What does this PR do?

Adds a new community integration for Pi-hole DNS server monitoring.

Why is it important?

Pi-hole is widely used for network-level DNS filtering and ad blocking. This integration enables users to:

  • Monitor DNS query patterns and traffic
  • Track blocking effectiveness
  • Identify top clients and domains
  • Analyze DNS response times
  • Detect potential security issues

Checklist

  • I have reviewed the contributing guidelines
  • Package builds successfully with elastic-package build
  • Package passes elastic-package lint
  • Tested in local dev environment
  • Tested in production environment
  • Documentation is complete
  • Screenshots included
  • Sample events provided for all data streams
  • ECS field mappings documented

Integration Details

Type: Community
Owner: elastic/integrations
Categories: security, custom, network
Version: 0.1.22
Requires: Kibana 9.1.0+, Elastic Basic license

Data Streams:

  • dns_queries (logs): Individual DNS query records
  • query_history (metrics): Time-series query volume
  • pihole_summary (metrics): Comprehensive statistics
  • top_clients (metrics): Top DNS clients
  • top_domains (metrics): Top queried domains

Kibana Assets:

  • 3 dashboards (Overview, Security & Blocking, DNS Analysis)
  • 3 saved searches (Blocked Queries, DNSSEC Failures, Slow Queries)
  • 5 data views/index patterns

@mpreissner mpreissner requested a review from a team as a code owner January 1, 2026 00:20
@cla-checker-service
Copy link

cla-checker-service bot commented Jan 1, 2026

💚 CLA has been signed

mpreissner added a commit to mpreissner/integrations that referenced this pull request Jan 1, 2026
@mpreissner
Copy link
Author

❌ Author of the following commits did not sign a Contributor Agreement: aa72bfa, 3d964be

Please, read and sign the above mentioned agreement if you want to contribute to this project

I’ve signed the agreement.

This integration collects DNS query logs and metrics from Pi-hole instances.

Features:
- DNS query logs with full query details (client, upstream, DNSSEC, reply time)
- Time-series metrics for query history and patterns
- Summary statistics and blocking effectiveness metrics
- Top clients and domains tracking (allowed and blocked)
- Three comprehensive Kibana dashboards (Overview, Security & Blocking, DNS Analysis)
- Three saved searches (Blocked Queries, DNSSEC Failures, Slow Queries)
- Support for Pi-hole API v6+ with session-based authentication

Data streams:
- dns_queries (logs): Individual DNS query records with timestamp-based pagination
- query_history (metrics): 10-minute interval query volume trends
- pihole_summary (metrics): Comprehensive DNS and blocking statistics
- top_clients (metrics): Top 10 allowed and blocked clients
- top_domains (metrics): Top 10 allowed and blocked domains

Technical details:
- CEL input type for API integration
- Time-series data streams with synthetic source for metrics
- ECS field mappings for DNS data
- Automatic session lifecycle management
- Complete documentation with sample events
Allows users to adjust the maximum number of DNS queries fetched per API request for high-volume Pi-hole instances, preventing data loss when query rates exceed the default 1000 queries per collection interval.
@mpreissner mpreissner force-pushed the add-pihole-integration branch from e842237 to 5f47400 Compare January 6, 2026 12:30
@andrewkroh andrewkroh added documentation Improvements or additions to documentation. Applied to PRs that modify *.md files. New Integration Issue or pull request for creating a new integration package. dashboard Relates to a Kibana dashboard bug, enhancement, or modification. labels Jan 8, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

dashboard Relates to a Kibana dashboard bug, enhancement, or modification. documentation Improvements or additions to documentation. Applied to PRs that modify *.md files. New Integration Issue or pull request for creating a new integration package.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants