datadog-dns-integration

README documentation for datadog-dns-integration

stableRepositoryPythonprivate

4 min readUpdated Jul 24, 2026@observability-teamObservability

Source: ZoosGlobal/datadog-dns-integration Visibility: Private This page is automatically synchronized from the repository README. Do not edit this generated file directly.

Microsoft DNS Monitor for Datadog

Monitors Microsoft DNS Server health, resolution latency, forwarder availability, zone status, security/compliance posture, DNSSEC key health, and process health on Windows Server, and reports it to Datadog as metrics, service checks, and events.

Overview

Microsoft DNS Server is critical shared infrastructure — when it degrades, the impact is immediate and organization-wide, yet most environments have no proactive monitoring for it. This integration closes that gap with:

Service health — is the DNS service running, is it set to auto-start
Resolution latency — real UDP/53 probes against the local server and any number of configured domains, each independently thresholded
Forwarder availability — direct UDP/53 probes to every configured upstream forwarder, not just a port-open check, with an event on every up/down transition
Zone health — zone counts, pause state, AD-integration/replication scope, DNSSEC signing, and dynamic-update security posture
Performance counters and statistics — query volume, recursion, cache, zone transfers, dynamic updates, TSIG/DNSSEC validation, via PDH and Get-DnsServerStatistics
Security & compliance posture — recursion, Response Rate Limiting, socket pool size, EDNS probing, cache pollution protection, and continuous configuration-drift detection — reported as metrics and events, never as an opinionated pass/fail alert (see docs/compliance.md)
DNSSEC key health — signing key inventory and rollover posture per zone, so a missing or non-rolling key surfaces before it causes a validation outage
Process health — dns.exe memory, CPU, handles, uptime
Its own health — config validity, Windows/PowerShell/DNS-role environment checks, and a dedicated _health service check per collector, plus overall collection success

See metadata.csv for the full metric reference and docs/architecture.md for how the pieces fit together. This integration never reads DNS record content, zone data, client IPs, or any identity information — see docs/compliance.md.

Architecture

Datadog Agent  →  checks.d/dns_monitor.py (thin shim, re-exports the check)
               →  datadog_checks/dns_monitor/check.py (DnsMonitorCheck,
                   a standard AgentCheck)
                     ├─ config.py / validation.py   — parse & validate conf.yaml
                     ├─ environment.py              — Windows/PowerShell/DNS-role probes
                     ├─ powershell.py               — the only module touching subprocess
                     ├─ dns_protocol.py             — raw UDP/53 probing
                     └─ service.py, perfmon.py, statistics.py, resolution.py,
                        forwarders.py, zones.py, process.py, events.py,
                        scavenging.py, cache.py, dnssec.py, security.py,
                        configuration.py, audit.py  — one collector module each
               →  self.gauge() / self.count() / self.service_check() (Agent API)
               →  Datadog

This is a native Datadog Agent Check. There is no external binary, no DogStatsD client of its own, and no wrapper layer around a collector — the AgentCheck subclass is the collector. Collection happens via Python’s socket/subprocess stdlib and Windows-native utilities (powershell.exe, sc.exe, typeperf.exe). Full detail: docs/architecture.md.

Setup

Requirements

Windows Server 2016/2019/2022/2025 with the DNS Server role installed
Datadog Agent v7+ (ships its own Python 3 runtime — no separate Python install needed)
A service account with DNS Admins, Performance Log Users, and Event Log Readers group membership — Domain Admin, Local Administrator, and SYSTEM are all unnecessary. See docs/permissions.md for the exact per-collector mapping.

Install

git clone https://github.com/ZoosGlobal/datadog-dns-integration
cd datadog-dns-integration

PowerShell.exe -ExecutionPolicy Bypass -File .\scripts\setup.ps1

The installer copies checks.d/dns_monitor.py, the datadog_checks/dns_monitor/ package, and a single conf.d/dns_monitor.d/conf.yaml, then restarts the Agent. There is nothing to compile and nothing else to stage — see docs/configuration.md for every available conf.yaml key.

Verify

datadog-agent check dns_monitor

Expect dns_monitor.config_valid, dns_monitor.windows_supported, dns_monitor.dns_role_present, dns_monitor.powershell_available, and dns_monitor.collection all [OK]. Then confirm metrics in the Datadog Metrics Explorer: dns.service.up.

Upgrading

See docs/upgrade_guide.md — v3.2.0 is a production-hardening pass (locale-safety fixes, an aggregate per-cycle collection deadline, and a process-launch reduction; all additive, no breaking changes); v3.1.0 added security/compliance posture, DNSSEC key health, cache configuration health, and configuration-drift detection; v3.0.0 removed the Go collector binary entirely in favor of native Python collection; v2.0.0 unified configuration into a single file.

Documentation

Doc	Contents
docs/architecture.md	Component design, data flow, extensibility
docs/configuration.md	Full `conf.yaml` reference
docs/troubleshooting.md	Service checks, structured logs, common issues
docs/security.md	Threat model, subprocess safety, validation-as-security-boundary
docs/compliance.md	What is and is never collected; regulatory framing
docs/permissions.md	Minimum required Windows privilege per collector
docs/events.md	Every Datadog Event this integration emits, and why
docs/performance.md	Overhead, caching, tuning at scale
docs/best_practices.md	Rollout, tuning, and alerting recommendations
docs/limitations.md	Known limitations
docs/faq.md	Frequently asked questions
docs/upgrade_guide.md	Version migration guides

Pre-built dashboards ship under assets/dashboards/ (Overview, plus Security & Compliance) and monitors under assets/monitors/; see manifest.json for how they map to the Datadog Marketplace tile.

See PRODUCTION_READINESS_REVIEW.md for the standing pre-GA audit (cardinality, performance budget, localization, threat model, compliance matrix, and ranked recommendations) and its “Part 3” addendum for the production-hardening pass that followed it — the two locale defects it originally flagged are fixed in code (see docs/limitations.md), though not yet verified against a real non-English-locale Windows Server host; real-host validation across locales remains the largest open item before GA.

Testing

make test        # pytest
make lint         # flake8 + black --check + mypy

See tests/ for the full suite: config parsing, validation, PowerShell invocation, DNS protocol probing, environment checks, every collector module, and full check-cycle scenarios — all against mocked subprocess calls, no Windows host required to run the tests.

Support

Maintainer contact and issue reporting: see author in manifest.json. For security issues, see docs/security.md#reporting-a-vulnerability.

Changelog

See CHANGELOG.md.

License

MIT — see LICENSE.