DnsStream is a lightweight software agent developed by Telemity that captures DNS telemetry from Windows DNS servers and forwards structured events to a SIEM or log management platform. It is installed as a Windows service on the DNS server itself and operates as a passive observer - receiving DNS events directly from the Windows DNS Server service with no impact on DNS service operation.
DnsStream is the collection layer in the telemetry stack. It does not perform detection, analysis, or enforcement. Its job is to deliver complete, high-fidelity DNS event data to the platforms where those functions already operate.
Three principles govern every aspect of DnsStream’s design.
Telemetry collection is a distinct concern. Detection, correlation, and analytics belong in the SIEM. Bundling detection logic into a telemetry agent creates fragility, opacity, and lock-in. DnsStream collects and forwards - nothing else.
Production systems come first. DnsStream is deployed on DNS servers. DNS is critical infrastructure. Every design decision is evaluated against a single question: what is the cost to production? The answers to that question produced the ETW-based architecture, the in-memory pipeline, the fixed memory footprint, and the passive observer model.
The data that leaves should be complete. Partial telemetry is worse than its absence in some respects - it creates the illusion of coverage while leaving real gaps. DnsStream fully decodes DNS messages meaning that every response event includes the complete answer section, all resource records, and all TTL values.
DnsStream captures DNS events using Windows Event Tracing for Windows (ETW), subscribing to the Microsoft-Windows-DNSServer provider. ETW is the high-performance tracing subsystem built into Windows and used by the operating system itself. The DNS Server service fires a structured ETW event for every DNS query and response it processes.
DnsStream registers as a real-time ETW consumer. Events are delivered to DnsStream’s callback in kernel-buffered memory - there is no disk I/O, no polling, and no shared log files in the capture path.
The Windows DNS Server ETW provider is the only mechanism that gives access to DNS events as the DNS service generates them - after DNS parsing is complete, before any network activity. This gives ETW-based capture several structural advantages over the alternatives:
Versus DNS debug logging. The debug log writes to disk synchronously at high volume, produces unstructured text requiring fragile parsing, and was designed as a troubleshooting tool rather than a production telemetry pipeline. ETW has none of these characteristics.
Versus packet capture. Network-layer capture typically requires a kernel-level capture driver (Npcap, WinPcap, or equivalent) - or at the very least a network interface permanently in promiscuous mode which also requires permanently elevated permissions - on the production DNS server which introduces kernel attack surface. This requires IPv4, IPv6, UDP and TCP reassembly and decoding work that the network stack and DNS service has already done internally.
Versus other ETW consumers. Other agents that consume the DNS Server ETW provider don’t parse the DNS packet data provided with each event, only capturing data like query name, type, and client address while omitting the response payload - answer records, TTL values, authority and additional sections. DnsStream fully decodes DNS packets and includes this data.
Detailed comparison of DnsStream against alternatives:
| Capability | DnsStream | ETW (raw) | Filebeat / Eventbeat | Packetbeat | DNS Debug Logs |
|---|---|---|---|---|---|
| Real-time processing | Yes (streaming) | Yes (but raw) | Near real-time | Near real-time | No (file-based) |
| Full DNS packet parsing (answers, TTLs, flags) | Yes | No (raw hex only) | No | Yes | Partial |
| Ease of use | Turnkey | Complex | Moderate | Moderate | Poor |
| Performance overhead on DNS server | Low (bounded, in-memory) | High (verbose ETW) | High (ETW + shipping) | Low (off-host) | High (disk I/O) |
| Disk I/O required | None | None | Depends | None | High |
| Works without network tap/SPAN | Yes | Yes | Yes | No | Yes |
| Structured output (JSON/syslog) | Yes | No | Yes | Yes | No |
| Answer visibility (RR sets) | Full | None | None | Full | Limited |
| TTL / response detail visibility | Yes | No | No | Yes | Limited |
| DNS tunnelling detection capability | Strong | Weak | Weak | Strong | Limited |
| Operational complexity | Low | High | Medium | Medium | High |
| Runs directly on Windows DNS server | Yes | Yes | Yes | No | Yes |
| Impact on DNS resolution path | None (passive) | None | None | None | Indirect (I/O pressure) |
All processing between ETW capture and network transmission occurs in memory. DnsStream does not write event data to disk. The pipeline has four stages:
Receive. The ETW callback fires synchronously for each DNS event. DnsStream reads the structured event fields from the ETW buffer and hands off immediately to avoid blocking the ETW delivery thread.
Queue. The normalised event is placed into a configurable in-memory ring buffer. This decouples capture from forwarding and absorbs bursts in DNS query volume. If the forwarding target is temporarily unavailable, events accumulate in the buffer rather than being dropped. Buffer size is configurable.
Parse. Dedicated forwarding threads drain events from the queue. Common DNS record types are decoded into structured fields. Uncommon types are preserved as hex-encoded RDATA.
Forward. The dedicated forwarding threads serialise events into the configured output format, and transmit them over a persistent TCP connection to the configured forwarding target, optionally using TLS.
DnsStream generates the following event types:
Client query. Fired when the DNS Server receives an inbound query from a client. Contains: client IP and port, server IP, query name (QNAME), query type (QTYPE), query class (QCLASS), transaction ID, DNS header flags, and transport protocol.
Client response. Fired when the DNS Server sends a response. Extends the query request fields with: response code (RCODE), full answer section (all resource records with names, TTLs, classes, types, and RDATA), authority section, and additional section.
Parse error. Fired when DnsStream receives an ETW event from the DNS Server which contains a DNS packet it cannot parse. Contains: client IP and port, server IP, raw packet bytes (hex-encoded), and an error description.
Metrics. Operational metrics generated periodically by DnsStream. Includes ETW session, network client and forwarding queue metrics.
The Events & output formats documention identifies all supported event types.
DnsStream serialises events into the configured output format on the forwarding thread before transmission. The output format is set in dnsstream.conf and requires a service restart to change.
| Format | Description |
|---|---|
json |
Newline-delimited JSON (NDJSON). One JSON object per event per line. |
querylog |
DNS payload in BIND querylog style. |
For querylog, events are carried as a syslog message body using one of the following:
<priority>MMM DD HH:MM:SS hostname appname[pid]: <event><priority>1 ISO8601timestamp hostname appname pid - - <event>For json, events use a two-level structure: a top-level envelope (timestamp, host, schema version, event type) and a data object carrying the DNS message fields. The schema version field (schema) is incremented on breaking changes; breaking changes are published in the DnsStream changelog.
Detailed output format information is provided in the Events & output formats documention.
The forwarding target is configured as an IP address or DNS name. If a DNS name is used, DnsStream resolves it when it attempts to connect - DnsStream cycles through all resolved addresses until one connects successfully. This allows Core users to implement network recovery using multiple A or AAAA records and allowing DnsStream to move on to the next on failure or by manually invoking failover by modifying the address in the DNS record - since only one forwarder target is supported in Core.
All formats use a persistent TCP connection. DnsStream maintains a single long-lived connection per configured forwarding target and reconnects automatically on failure. For both Core and Assured, all configured forwarder targets will connect, however, for Core users only the first configured forwarder target which does not have client certicate TLS options on will process events in the forwarding queue.
Both DnsStream Core and Assured support TLS-encrypted forwarding for all TCP-based formats with Assured also supporting mutual TLS (mTLS), enabling certificate-based authentication of both the DnsStream agent and the receiving collector. TLS 1.2 and 1.3 are supported. Certificate paths, CA certificate, and peer verification are configured in dnsstream.conf. Since native Windows Schannel is used for TLS support, configuration like TLS version, enabled ciphers etc. are managed at the system level using local or Active Directory based policies.
If all forwarding hosts become unreachable, DnsStream continues capturing into the ring buffer while attempting to establish a connection. Events accumulated in the buffer during an outage are forwarded in order once connectivity is restored. Events are only lost if the ring buffer fills completely before the connection is re-established, in this case older events are overwritten. Buffer sizing guidance is in the Ring buffer behaviour section in the Network recovery documentation.
The Network recovery document details DnsStream’s connection model and recovery behaviour.
DnsStream is designed so that telemetry failure does not become DNS infrastructure failure.
All DnsStream settings are defined in a single plain text configuration file, dnsstream.conf, located in the %ProgramData%\Telemity\DnsStream directory. The file is read at startup; changes require a service restart.
A minimal working configuration to send events to a forwarder target requires only one forwarder directive. Additional will be required to change the event format.
All configuration paramters are detailed in the Configuration reference documentation.
CPU - DnsStream’s CPU usage is approximately 25% of the CPU used by the Windows DNS Server process at any given time. This is a stable proportional ratio, not a fixed ceiling - it scales naturally with query volume. On a server under full DNS load, both processes together leave substantial headroom on modern server hardware.
Throughput - DnsStream can comfortably sustain an ingestion well in excess of 150,000 continuous DNS queries per second from the ETW provider. Each query generates two events (a request and a response), giving a forwarding throughput of 300,000 events per second for 150,000 DNS queries a second. This far exceeds the query rate of nearly all production Windows DNS deployments.
Memory - Memory usage is fixed and determined entirely by the ring buffer configuration. At default settings (100 MB buffer) total DnsStream process memory is approximately 115 MB. This figure does not grow with query volume. On busy servers where longer forwarding outages need to be accommodated, the buffer size can be increased.
Disk I/O - There is no disk I/O in the DnsStream data path. All pipeline stages - ETW callback, ring buffer, parsing, serialisation, and TCP transmission - operate entirely in memory. The only disk writes DnsStream makes are periodic application-level entries to the Windows Event Log, written at the configured metrics interval (default: every 60 seconds). These are low-frequency, low-volume writes consistent with normal Windows service behaviour. Additionally, if queue recovery is active, queued events are serialised to a disk file when DnsStream is stopped, the file is then loaded on start so that the events are not lost during a restart.
DNS service impact - DnsStream is a passive ETW consumer. It does not modify DNS Server configuration, does not intercept DNS responses, and introduces no execution path into the DNS service. In production deployments, DNS query latency and resolution performance are not affected. If DnsStream stops or crashes for any reason, the DNS Server service continues operating without interruption.
DnsStream has the following system requirements:
DnsStream is distributed as a signed ZIP archive containing:
dnsstream.exe - the signed DnsStream binary (~1 MB)dnsstream.conf.default - default configuration file for new installationseula.txt - end user license agreementinstall.ps1 - Windows service installation scriptuninstall.ps1 - Windows service removal scriptversion.txt - DnsStream versionInstallation involves extracting the archive, running install.ps1 with administrator privileges, editing the installed dnsstream.conf and starting the DnsStream Windows service. The install.ps1 script registers DnsStream as a Windows service with automatic startup. No EXE installer, no package manager, and no reboot are required. Administrators can read the installer script to see exactly what it does.
DnsStream can be run in console mode to verify the configuration and confirm events are flowing:
& $Env:ProgramFiles\Telemity\DnsStream\dnsstream.exe run-stdout $Env:ProgramData\Telemity\DnsStream\dnsstream.conf
Console mode prints events to stdout in the configured format and exits cleanly on CTRL+C.
DnsStream has no interactive installer and no GUI configuration. Every aspect of installation and configuration is scriptable, making it compatible with Group Policy, Ansible, Puppet, Chef, DSC, and any tooling that can execute a PowerShell script and write a configuration file.
DnsStream is available in two editions.
DnsStream Core is free to download with no licence key and no account required. It includes the complete ETW-based capture engine, in-memory ring buffer, JSON output, BSD syslog, RFC 5424 syslog, DNS domain enrichment, graceful network recovery, metrics logging, console mode, TLS transport using native Windows Schannel, and schema stability guarantees with versioning and advance notice of changes.
DnsStream Assured is the enterprise tier, available on a per-server subscription basis. It includes everything in Core and adds:
Data residency. DNS events go where dnsstream.conf directs them. No data is sent to Telemity. There are no vendor cloud services in the data path for Core or Assured deployments unless they have been configured as a forwarder target.
Binary integrity. The DnsStream binary is Authenticode-signed by Telemity Ltd. Verify the signature with Get-AuthenticodeSignature .\dnsstream.exe before installation.
Attack surface. DnsStream has no network listening port, no web interface, no management API, and no inbound network connectivity. Its only network activity is outbound TCP to the configured forwarding target.
Privilege. DnsStream requires administrator rights for installation. The running service can be configured to run under a dedicated low-privilege service account with access only to the ETW provider and the Windows Event Log.
mTLS (Assured). Mutual TLS ensures that only an authorised DnsStream instance can connect to an authorised collector, and vice versa. This prevents injection of forged DNS telemetry events and protects the telemetry stream in transit.