dnsbench

Documentation

Overview

Package dnsbench contains functionality for executing various plain DNS, DoH and DoQ Benchmarks.

Index

• Constants
• type Benchmark
  • func (b *Benchmark) Run(ctx context.Context) ([]*ResultStats, error)
• type Counters
• type Datapoint
• type ErrorDatapoint
• type ResultStats

Constants

const (
	// UDPTransport represents plain DNS over UDP.
	UDPTransport = "udp"
	// TCPTransport represents plain DNS over TCP.
	TCPTransport = "tcp"
	// TLSTransport represents DNS over TLS.
	TLSTransport = "tcp-tls"
	// QUICTransport represents DNS over QUIC.
	QUICTransport = "quic"

	// GetHTTPMethod represents GET HTTP Method for DoH.
	GetHTTPMethod = "get"
	// PostHTTPMethod represents GET POST Method for DoH.
	PostHTTPMethod = "post"

	// HTTP1Proto represents HTTP/1.1 protocol for DoH.
	HTTP1Proto = "1.1"
	// HTTP2Proto represents HTTP/2 protocol for DoH.
	HTTP2Proto = "2"
	// HTTP3Proto represents HTTP/3 protocol for DoH.
	HTTP3Proto = "3"

	// DefaultEdns0BufferSize default EDNS0 buffer size according to the http://www.dnsflagday.net/2020/
	DefaultEdns0BufferSize = 1232

	// DefaultRequestLogPath is a default path to the file, where the requests will be logged.
	DefaultRequestLogPath = "requests.log"
)

Types

type Benchmark

type Benchmark struct {
	// Server represents (plain DNS, DoT, DoH or DoQ) server, which will be benchmarked.
	// Format depends on the DNS protocol, that should be used for DNS benchmark.
	// For plain DNS (either over UDP or TCP) the format is <IP/host>[:port], if port is not provided then port 53 is used.
	// For DoT the format is <IP/host>[:port], if port is not provided then port 853 is used.
	// For DoH the format is https://<IP/host>[:port][/path] or http://<IP/host>[:port][/path], if port is not provided then either 443 or 80 port is used. If no path is provided, then /dns-query is used.
	// For DoQ the format is quic://<IP/host>[:port], if port is not provided then port 853 is used.
	Server string

	// Types is an array of DNS query types, that should be used in benchmark. All domains retrieved from domain data source will be fired with each
	// type specified here.
	Types []string

	// Count specifies how many times each domain from data source is used by each worker. Either Benchmark.Count or Benchmark.Duration must be specified.
	// If Benchmark.Count and Benchmark.Duration is specified at once, it is considered invalid state of Benchmark.
	Count int64

	// Duration specifies for how long the benchmark should be executing, the benchmark will run for the specified time
	// while sending DNS requests in an infinite loop based on the data source. After running for the specified duration, the benchmark is canceled.
	// This option is exclusive with Benchmark.Count.
	Duration time.Duration

	// Concurrency controls how many concurrent queries will be issued at once. Benchmark will spawn Concurrency number of parallel worker goroutines.
	Concurrency uint32

	// Rate configures global rate limit for queries per second. This limit is shared between all the worker goroutines. This means that queries generated by this Benchmark
	// per second will not exceed this limit.
	Rate int
	// RateLimitWorker configures rate limit per worker for queries per second. This means that queries generated by each concurrent worker per second will not exceed this limit.
	RateLimitWorker int

	// QperConn configures how many queries are sent by each connection (socket) before closing it and creating a new one.
	// This is considered only for plain DNS over UDP or TCP and DoT.
	QperConn int64

	// Recurse configures whether the DNS queries generated by this Benchmark have Recursion Desired (RD) flag set.
	Recurse bool

	// Probability is used to bring randomization into Benchmark runs. When Probability is 1 or above, then all the domains passed in Queries field will be used during Benchmark run.
	// When Probability is less than 1 and more than 0, then each domain in Queries has Probability chance to be used during benchmark.
	// When Probability is less than 0, then no domain from Queries is used during benchmark.
	Probability float64

	// EdnsOpt specifies EDNS option with code point code and optionally payload of value as a hexadecimal string in format code[:value].
	// code must be an arbitrary numeric value.
	EdnsOpt string

	// DNSSEC Allow DNSSEC (sets DO bit for all DNS requests to 1)
	DNSSEC bool

	// Edns0 configures EDNS0 usage in DNS requests send by benchmark and configures EDNS0 buffer size to the specified value. When 0 is configured, then EDNS0 is not used.
	Edns0 uint16

	// TCP controls whether plain DNS benchmark uses TCP or UDP. When true, the TCP is used.
	TCP bool

	// DOT controls whether DoT is used for the benchmark.
	DOT bool

	// WriteTimeout configures write timeout for DNS requests generated by Benchmark.
	WriteTimeout time.Duration
	// ReadTimeout configures read timeout for DNS responses.
	ReadTimeout time.Duration
	// ConnectTimeout configures timeout for connection establishment.
	ConnectTimeout time.Duration
	// RequestTimeout configures overall timeout for a single DNS request.
	RequestTimeout time.Duration

	// Rcodes controls whether ResultStats.Codes is filled in Benchmark results.
	Rcodes bool

	// HistDisplay controls whether Benchmark.PrintReport will include histogram.
	HistDisplay bool
	// HistMin controls minimum value of histogram printed by Benchmark.PrintReport.
	HistMin time.Duration
	// HistMax controls maximum value of histogram printed by Benchmark.PrintReport.
	HistMax time.Duration
	// HistPre controls precision of histogram printed by Benchmark.PrintReport.
	HistPre int

	// Csv path to file, where the Benchmark result distribution is written.
	Csv string
	// JSON controls whether the Benchmark.PrintReport prints the Benchmark results in JSON format (option is true).
	JSON bool

	// Silent controls whether the Benchmark.Run and Benchmark.PrintReport writes anything to stdout.
	Silent bool
	// Color controls coloring of std output.
	Color bool

	// PlotDir controls where the generated graphs are exported. If set to empty (""), which is default value. Then no graphs are generated.
	PlotDir string
	// PlotFormat controls the format of generated graphs. Supported values are "svg", "png" and "jpg".
	PlotFormat string

	// DohMethod controls HTTP method used for sending DoH requests. Supported values are "post" and "get". Default is "post".
	DohMethod string
	// DohProtocol controls HTTP protocol version used fo sending DoH requests. Supported values are "1.1", "2" and "3". Default is "1.1".
	DohProtocol string

	// Insecure disables server TLS certificate validation. Applicable for DoT, DoH and DoQ.
	Insecure bool

	// ProgressBar controls whether the progress bar is printed.
	ProgressBar bool

	// Queries list of domains and data sources to be used in Benchmark. It can contain a local file data source referenced using @<file-path>, for example @data/2-domains.
	// It can also be data source file accessible using HTTP, like https://raw.githubusercontent.com/Tantalor93/dnspyre/master/data/1000-domains, in that case the file will be downloaded and saved in-memory.
	// These data sources can be combined, for example "google.com @data/2-domains https://raw.githubusercontent.com/Tantalor93/dnspyre/master/data/2-domains".
	Queries []string

	// RequestLogEnabled controls whether the Benchmark requests will be logged. Requests are logged into the file specified by Benchmark.RequestLogPath field.
	RequestLogEnabled bool

	// RequestLogPath specifies file where the request logs will be logged. If the file does not exist, it is created.
	// If it exists, the request logs are appended to the file.
	RequestLogPath string

	// SeparateWorkerConnections controls whether the concurrent workers will try to share connections to the server or not. When set true,
	// the workers will NOT share connections and each worker will have separate connection.
	SeparateWorkerConnections bool

	// Writer used for writing benchmark execution logs and results. Default is os.Stdout.
	Writer io.Writer
	// contains filtered or unexported fields
}

Benchmark is representation of runnable DNS benchmark scenario. based on domains provided in Benchmark.Queries, it will be firing DNS queries until the desired number of queries have been sent by each concurrent worker (see Benchmark.Count) or the desired benchmark duration have been reached (see Benchmark.Duration).

Benchmark will create Benchmark.Concurrency worker goroutines, where each goroutine will be generating DNS queries with domains defined using Benchmark.Queries and DNS query types defined in Benchmark.Types. Each worker will either generate Benchmark.Types*Benchmark.Count*len(Benchmark.Queries) number of queries if Benchmark.Count is specified, or the worker will be generating arbitrary number of queries until Benchmark.Duration is reached.

func (*Benchmark) Run

func (b *Benchmark) Run(ctx context.Context) ([]*ResultStats, error)

Run executes benchmark, if benchmark is unable to start the error is returned, otherwise array of results from parallel benchmark goroutines is returned.

type Counters

type Counters struct {
	// Total is counter of all requests.
	Total int64
	// IOError is counter of all requests for which there was no answer.
	IOError int64
	// Success is counter of all responses which were successful (NOERROR, but not NODATA!).
	Success int64
	// Negative is counter of all responses which were negative (NODATA/NXDOMAIN).
	Negative int64
	// Error is counter of all responses which were not negative (NODATA/NXDOMAIN) or success (NOERROR response).
	Error int64
	// IDmismatch is counter of all responses which ID mismatched the request ID.
	IDmismatch int64
	// Truncated is counter of all responses which had truncated flag.
	Truncated int64
}

Counters represents various counters of benchmark results.

type Datapoint

type Datapoint struct {
	Duration time.Duration
	Start    time.Time
}

Datapoint one datapoint of benchmark (single DNS request).

type ErrorDatapoint

type ErrorDatapoint struct {
	Start time.Time
	Err   error
}

ErrorDatapoint one datapoint representing single IO error of benchmark. Datapoint one datapoint of benchmark (single DNS request).

type ResultStats

type ResultStats struct {
	Codes                map[int]int64
	Qtypes               map[string]int64
	Hist                 *hdrhistogram.Histogram
	Timings              []Datapoint
	Counters             *Counters
	Errors               []ErrorDatapoint
	AuthenticatedDomains map[string]struct{}
	DoHStatusCodes       map[int]int64
}

ResultStats is a representation of benchmark results of single concurrent thread.