Skip to content

Capacity

How many queries per second a pygslb node answers, where that time goes, and when to add another node. Every figure here is measured; the protocol is in bench/protocol.md and the raw runs in bench/RESULTS.md.

One node, one core

A DNS process answers about 10 000 queries per second on one core, and 4 000 queries per second with a median latency under a millisecond and no loss. The answer costs ~100 µs of CPU; one full core is the ceiling, because the answer path is Python bytecode under the global interpreter lock.

Measured on 2026-11-15 (version 0.5.0, CPU i5-8259U), saturating runs of 30 s. Lot 7 changed nothing on this path — the TCP backlog and the journal are elsewhere — so these figures still describe 0.7.0:

Workers Queries/s p50 p95 p99 µs CPU per answer Cores used
1 9 872 18.9 ms 32.3 ms 61.4 ms 102 1.01
2 12 245 15.9 ms 41.0 ms 77.8 ms 159 1.95
4 17 835 5.4 ms 44.0 ms 84.0 ms 207 3.69

Latency at saturation is queueing, not service time: it says "the node is full", not "the node is slow". With a rate held below saturation, one worker gives:

Offered rate Answered p50 p95 p99 lost
1 000 q/s 1 000 1.02 ms 1.63 ms 6.8 ms 0
2 000 q/s 2 000 0.66 ms 1.25 ms 15 ms 0
4 000 q/s 3 995 0.31 ms 6.0 ms 28 ms 0
6 000 q/s 5 893 0.29 ms 32 ms 51 ms 0

Between 4 000 and 6 000 the node reaches 98 % of its capacity and the tail collapses: the useful planning figure is half the saturation point, here 4 000–5 000 q/s per core.

What the version before it did

Same machine, same protocol, version 0.4.1:

0.4.1 0.5.0
Queries/s, one worker 3 182 9 872 ×3.1
µs of CPU per answer 351 102 ÷3.4
p50 at 1 000 q/s 2.1 ms 1.02 ms ÷2

Three changes, each measured on its own (bench/RESULTS.md has the tables):

  1. No thread per packet. dnslib inherited socketserver.ThreadingMixIn and created a thread for every datagram — 13 342 queries, 13 342 threads. That was 229 µs of the 351 µs. TCP keeps the threaded server.
  2. No ipaddress object per query. Bucketing the client address for the statistics, and matching a CIDR rule, built Python objects on every answer. Integer comparison now: 21 µs saved.
  3. Packed answers from a cache. The reply is built once per (request, address) and re-sent with the caller's identifier patched in. _whoami is never cached (it names the client); a reload builds a new resolver and therefore a new cache.

Using more cores

One process uses one core: adding cores to the container does nothing by itself. Set GSLB_WORKERS and one container runs one worker per core, all bound to the same address and port, and the console adds their counters up.

docker run -d --name gslb --network host \
  -e GSLB_ADDR=192.0.2.10 -e GSLB_WORKERS=auto -e GSLB_INSTANCE=dns-a \
  gslb:0.7.0

GSLB_WORKERS=auto follows the CPUs the process may use (its affinity mask); GSLB_WORKERS=4 pins the number. One worker is the default and behaves exactly like 5.0: no fork, no supervisor, no extra process.

Measured on 2026-11-15, same machine, one container, saturating runs of 20 s:

Workers Queries/s p50 p95 p99 µs CPU per answer
1 10 127 17.4 ms 28.2 ms 56.3 ms 94
2 13 906 13.6 ms 32.8 ms 60.4 ms 132
4 19 283 3.8 ms 34.8 ms 69.6 ms 161
8 29 061 5.0 ms 38.9 ms 79.9 ms 167

The per-answer cost grows with the worker count (94 → 167 µs): the client of the benchmark runs on the same four physical cores, and eight workers already fill the eight hardware threads, so they compete for cache and execution units. A dedicated machine would show a cleaner curve.

What it means in practice:

  • the supervisor forks before any thread starts, so each worker inherits the parsed configuration and nothing else;
  • every worker has its own pools, counters and probe thread; the probes are spread over the interval (worker N starts N/count of an interval later) so the backends do not see N simultaneous probes;
  • a worker that dies is restarted within a second; three deaths in thirty seconds stop the node, and the container's restart policy takes over;
  • SIGTERM, SIGINT and SIGHUP reach every worker; a reload applies to all;
  • memory is ~45 MiB per worker.

If you would rather run one container per core, set GSLB_REUSEPORT=1 on each and give them distinct GSLB_INSTANCE names: the kernel spreads the datagrams the same way, and the console treats them as separate nodes.

When to add a node rather than a worker

Workers share a kernel, a NIC and a machine. Past one saturated NIC, or when the answer must survive the loss of a host, use the HA mode: N hosts, one management console, an external VIP (ha.md). The counters aggregate the same way, and the DNS keeps answering while the console is down.

The console is the other half

The DNS scales to tens of thousands of queries per second; the journal behind the console does not scale the same way. One answer is one row of ~162 bytes and every dashboard query is linear in the rows of its window, so a node answering thousands of queries per second fills /data in hours and makes /api/stats take seconds. The tables and the mitigations are in Operations: keep the short windows, lower GSLB_RETENTION_DAYS, and remember that a slow console never slows an answer.

Reading the numbers honestly

  • The client shares the physical CPU of the server in this rig (the benchmark client runs in a VM hosted on the same NUC). Every throughput figure is a lower bound; the per-query CPU figure is not affected.
  • The machine throttles under a long saturation run: successive passes lose a few percent. Each figure is the median of three passes of 30 s.
  • p99 is the client's tail as much as the server's at high rates, because both compete for the same four cores.
  • The query mix is fixed (50 % A, 20 % AAAA, 10 % _whoami, 10 % NXDOMAIN, 10 % REFUSED). A zone with more names caches less well: the reply cache is most effective on a small zone, which is the normal shape of a GSLB zone.

Reproducing it

bench/protocol.md has the exact commands; bench/capacity.sh runs the load and prints a row per measurement, and bench/cost.py measures the same answer path without a socket or a client.