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):
- No thread per packet.
dnslibinheritedsocketserver.ThreadingMixInand 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. - No
ipaddressobject 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. - Packed answers from a cache. The reply is built once per (request,
address) and re-sent with the caller's identifier patched in.
_whoamiis 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,SIGINTandSIGHUPreach 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.