Developers

Size and performance budgets

WrenDNS runs on a Raspberry Pi next to other things, so footprint and speed are features with hard limits. This page lists the limits, where the bytes and the microseconds are, what we have already cut, what we measured and refused (so nobody has to measure it again), and how to measure your own change.

The rules

  • Performance ranks above footprint, and footprint above everything else but speed. If a size saving costs speed on the DNS path, the speed wins. We have refused savings of 0.3 MiB for that reason (below).
  • Never add allocation, locking, or I/O to the hot path without a benchmark that shows it is within budget. The steady-state cache-hit and blocked-answer paths allocate nothing (NFR-002, checked by an allocation-counting test).
  • A new runtime dependency needs a one-line justification and must not push the image past 15 MiB (AGENTS.md, rule 8).
  • Measure, don't assume. Every number in an ADR came from a real build. If you cannot say how you measured it, it is a guess.

The image: 15 MiB per architecture

  • The gate. The image workflow builds every platform, then deploy/image/size.py adds up the compressed layer sizes per platform and fails over 15 MiB. Compressed is what a Pi downloads, so how well something compresses matters: the same bytes stored twice cost twice.
  • Where the bytes are. About 97% of the image is the one static binary. Its largest parts are the DNS and TLS code, SQLite, and the embedded web UI.
  • Where we are. About 13.0 MiB on amd64, 12.3 on arm64, and 12.8 on armv7 after the cuts below (it was 14.84, 14.16, and 14.82 when the margin ran out). The size gate in the image run prints the real numbers for your commit.
  • Measure it like CI does. Build the image with BuildKit and OCI output as the image workflow does, then run python3 deploy/image/size.py --oci image.tar. A debug build says nothing: the release profile uses fat LTO, one codegen unit, and abort on panic.

What we cut

Each is an ADR with the numbers (Decisions). Sizes are amd64, compressed.

CutSavedHow, and the catch
The OpenAPI document compiled in0.60 MiBServed from the committed docs/api/openapi.json instead of being built from the annotations on every request. A test keeps the file equal to the code. (ADR-168)
The web UI stored gzip-only0.29 MiBThe embedded UI used to carry each file raw and as .gz; the layer's compression can only shrink the raw one, so every asset cost twice its gzip size. Clients without gzip get an inflated copy. (ADR-168)
No CA bundle in the image0.12 MiBNothing reads the system trust store: every TLS client uses the Mozilla roots compiled in. A private CA is set with tls_ca. (ADR-168)
A compact zoneinfoabout 0.2 MiBBuilt once with zic -b fat instead of copying Debian's three copies. The build fails if a zone name goes missing, and a test checks every file against the host's. (ADR-169)
SQLite without full-text search, R-tree, and dbstatabout 0.2 MiBLIBSQLITE3_FLAGS in .cargo/config.toml (so the tests run against the SQLite we ship), with a test that the four modules are gone and the ones we use are not. (ADR-169)
25 crates off the DNS path built for size0.36 MiBopt-level = "s" in [profile.release.package.*]. A guard test keeps hot-path crates off the list. (ADR-170)
Icon glyphs minifiedabout 15 KiB, with eleven more glyphsPath data to two decimals. See Extend the domain icons.

What we measured and refused

Do not spend time on these again unless the situation has changed. The reason is the part to read.

IdeaWhat it would saveWhy not
opt-level = "s" for wrendns-config0.6 MiBIts per-query client lookup grew and cache-hot throughput fell about 10%. Speed wins.
SQLite's C code at -Os0.31 MiBOn the rollup store's real queries the dashboard's week-wide top list was 10.5% slower, minute reads 11%, point reads 22%, bulk inserts 38%.
opt-level = "s" for rusqlitetinyOn the same query path, with no measurable gain to pay for it.
zstd image layersabout 2.1 MiBDocker before 23.0 and containerd before 1.5 cannot pull them, and Debian 12's docker.io is 20.10.
Stripping .eh_framepart of the binaryThe watchdog's stack capture unwinds with it (ADR-163).
Linker identical-code-foldinga littleThe cross compiler rejects the flag.
A slim zoneinfo (zic -b slim)0.06 MiB morejiff refuses one of its files (America/Ojinaga), so a schedule in that zone would be rejected as unknown. The zoneinfo test is the check if a later jiff accepts it.
Re-compressing the layer with zopfliabout 0.95 MiBA new build step and a provenance question for a one-time gain.

A guard test keeps the profile honest. crates/wrendns-config/tests/profile.rs fails if a crate known to be on the DNS path is added to the size-optimized list, if an entry is not exactly "s", or if an entry no longer matches Cargo.lock. The last one matters: a name@version entry that a dependency update makes stale is only a cargo warning, and the saving would vanish unseen. A crate present in two versions must be written name@version.

The web UI: 400 KiB

  • The budget is 400 KiB gzipped for the whole of ui/dist, lazy chunks included. npm run build prints the total and fails over the limit (ui/scripts/postbuild.mjs). It is about 296 KiB now.
  • Big data goes in a lazy chunk that loads when something needs it (the icon glyphs are one), so a page that never shows it never pays for it.
  • The UI is embedded in the binary as gzip only, so every KiB of UI is close to a KiB in the image.
  • A chart or a font library is a dependency. Justify it against the budget before you add it.

The DNS path's speed

  • The path. Receive, parse, policy, cache or forward, answer. Everything else (telemetry, storage, the API, the cluster) runs off it and may fail without a query going unanswered. The crates on the path: wrendns-proto, -net, -cache, -filter, -policy, -telemetry, -upstream, and the per-query lookups in wrendns-config. Run make bench-smoke after a change to any of them.
  • CI cannot judge speed. Hosted runners are too noisy for a regression gate, so the bench-smoke job fails only on lost queries or errors. You compare before and after yourself.
  • Benchmark with a control. On a shared build machine two runs of the same binary differed by up to about 15% for the DNS benchmark (about 0.5 to 4% for a single-thread SQLite workload). So build the baseline, the change, and a second copy of the baseline (the control), run them in rotation five or more times, and compare medians: a difference inside the control's spread is noise.
  • Benchmark the build you ship. make bench-smoke uses the bench-fast profile (thin LTO, 16 codegen units). The release build is fat LTO with one codegen unit and per-crate overrides, so a change to the release profile needs a release build of each variant (cargo build --release --config 'profile.release.package.X.opt-level="s"' sets an override without editing the manifest).
  • Look at the code, not only the number. For a compiler-setting change, list the sizes of the DNS-path functions in each binary with nm. Of 1,737 functions, 1,724 were identical for the size-optimized list: that is the evidence the hot path was not touched. A per-query function that changed size is the one to benchmark.
  • The latency budget (spec 00 §5): a cache hit or a blocked answer adds at most 250 µs at p99, at half the maximum load. A change that wakes an idle runtime worker before the answer is sent shows up only at low load, so measure at low and at high rates.

When you need more

  1. Find the offset first. Look for a cut of the same size that costs nothing (the table above shows several). A feature that adds 0.1 MiB and a cut that removes 0.3 is a good week.
  2. Write it down. An ADR with the before and after numbers from real builds, and what you measured and did not take.
  3. Let CI confirm. The size gate on your commit is the number that counts, not your estimate.
  4. Add a guard if the cut can be undone by accident, like the profile test.