Performance and resource usage¶

This page is the single source for the published performance and resource numbers. It records what was measured, how it was measured, and what the result does not prove. The performance and footprint section in operations owns the implementation cost model and go_memory_limit behavior.

These are scoped local measurements of the native proxy process, not deployment guarantees. They were taken on 2026-10-20 UTC. The footprint, fast-response, streaming concurrency, writer, storage and query tables used source revision facb699; the sustained-capacity table used revision 54d1276; the streaming throughput table used revision ca6ead9 on branch perf/e2e-streaming. Measurements used Go 1.27.2 on Linux/amd64 under WSL2. The host was a shared Intel Core Ultra 9 285H with 12 visible logical CPUs and 62 GiB of visible RAM. The earlier tables were measured with builds and tests finished; the streaming throughput ramp ran under variable background load. The public example configuration was used, with private listen and database paths supplied by scripts/dev.sh. Debug captures and body previews were off. No browser or live observer was attached during the load stages. CPU and RSS describe the native Go process, not Docker's container-wide accounting. Percentiles are nearest-rank; RSS was sampled every 100 ms unless stated otherwise.

Method¶

Artifact and idle footprint¶

The image was built from the current Dockerfile. The binary was built with CGO_ENABLED=0, -trimpath, -buildvcs=false, and -ldflags="-s -w".

The image size includes the distroless base, dependency notices, and the embedded UI. It is not a compressed download size, a registry digest, or a persistent-volume estimate. Idle RSS and CPU describe one process on this host. A short sample cannot prove that a longer idle period uses exactly the same resources.

Fast-response throughput¶

Each stage used a fresh disposable database and the same synthetic response: ten content frames, usage 100/10, and fixture cost 0.001. The upstream added no intentional delay. Each stage started requests for five seconds, then let active requests drain. The final row is a separate ten-second run used to reach about 90,000 durable rows without a storage drop.

All HTTP responses succeeded in these stages, including the 128-worker stage. That is not a promise that every configuration and history size stays exact under overload. The durable queue is bounded and best-effort; the deliberate overload fixture below shows what a drop result looks like.

At the ten-second 128-worker stage, the separate load generator and synthetic upstream process used 218.8% CPU and 31.8 MiB peak RSS. The proxy figure excludes that process.

Sustained capacity¶

The sustained capacity point is the highest tested closed-loop level that completed five minutes with zero durable drops and exact accounting. Each level started from a fresh disposable database. The upstream response and client shape were the same as the fast-response table: ten content frames, usage 100/10, and fixture cost 0.001. A level that dropped rows is an overload observation, not a capacity result.

The separate load generator and synthetic upstream used 249.0% CPU and 230.9 MiB peak RSS at the 48-worker exact point, and 206.5% CPU and 186.1 MiB at the 128-worker overload point. The proxy figures exclude that process.

The exact five-minute result is 14,166.2 requests/s at 48 workers, with p95 6.96 ms and p99 13.14 ms. The 64-worker point produced 50,208 drops (1.2% of successful requests) and the 128-worker point produced 433,859 drops (11.4%). Those rows show that the bounded durable queue is not a promise of lossless storage at every load. They are not evidence of a universal capacity ceiling; host, configuration, response size, history growth, and attached observers all change the result.

Streaming concurrency¶

The synthetic upstream emitted ten content frames across approximately one second, followed by usage and a terminator. Each stage started requests for five seconds and then drained. Latency includes the intentional upstream delay, so these numbers are not proxy-only overhead.

These stages measure concurrency and end-to-end latency for that fixed fixture. They do not measure SSE event rate, bytes per second, token throughput, TTFT, chunk-size or hold-duration effects, sustained streaming, or the point where streaming saturates. First-byte p95 is the first response byte, not the first generated token.

The 512-worker stage reached 512 upstream connections and remained exact. This is a configured concurrency result on one host, not a universal request-capacity ceiling. The 512 level also matches the example configuration's max_conns_per_host. No higher level, sustained streaming stage, or automatic saturation sweep was run; see Limitations. The generator and upstream used 69.9% CPU and 65.8 MiB peak RSS at that stage.

Streaming throughput¶

scripts/perf.sh streaming runs the longer end-to-end throughput ramp. Each level starts a fresh private scripts/dev.sh instance and sends requests through the real proxy to a local synthetic SSE upstream. The defaults are 1, 8, 32, 64, 128, 256, 512 and 1024 clients for 60 seconds per level, with 100 content frames over a roughly one-second stream.

Each result line reports requests/s, SSE events/s, response bytes/s, output tokens/s, end-to-end latency, first-byte p95, proxy CPU/RSS and durable rows. The event, byte and token counts come from responses the client compared byte-for-byte with the fixture, so they describe what the client received; a failed response does not contribute. The ramp stops at the first failed stage or durable drop. The per-level JSON carries sse_events_per_second, stream_bytes_per_second and output_tokens_per_second alongside the existing request and latency fields.

This fixture emits 100 content frames per one-second stream, ten times the ten-frame concurrency fixture above, so its CPU and byte rates are not directly comparable to that table. The 2026-10-20 run measured:

At 512 clients the proxy reached 479.3 requests/s, 48,884 SSE events/s, 2,435.1 KiB/s (about 2.4 MiB/s) and 47,925 output tokens/s with exact accounting and no drops. At 1024 clients the upstream peak stayed at 512, throughput stayed flat (473.0 requests/s, 48,243 events/s), and p50 latency doubled from about 1.06 s to 2.14 s; first-byte p95 rose from 9.17 ms to 1,097.42 ms. The extra clients queued behind the configured 512 upstream connections. The proxy used about 2.2 CPU cores at both levels, so this plateau is the configured connection cap, not a demonstrated proxy CPU ceiling. Every level completed with exact durable accounting and zero drops.

This run was taken under variable background load (1-minute load average 2.6 at the start and 13.1 at the end), so its absolute rates are lower and noisier than a quiet-host run. The plateau and the doubled 1024-client latency are the same-host comparison; do not compare the absolute numbers across hosts.

The 1024-client level is deliberately above the example configuration's max_conns_per_host of 512. It measures queueing and the throughput plateau, not 1024 simultaneous upstream connections. This is a fixed-level ramp, not an automatic saturation search; override the levels with PERF_STREAMING_LEVELS when a different range is needed.

Durable writer and overload¶

These are isolated Go benchmarks from the test overlay, not HTTP runs. Every row and drop count is verified against successful requests. The overload benchmark deliberately fills the bounded queue, so its drop count is a fixture result, not a recommended operating point.

The overload fixture confirms the accounting invariant durable + dropped = successful requests. Increasing queue capacity alone cannot make sustained overload lossless. A higher HTTP success rate is not a complete-accounting result unless the durable row count and drop delta agree.

Storage and retained projection¶

The storage fixture stores complete records, indexes, projection triggers, and marshaled response headers in SQLite. Disk bytes include the database, WAL, and shared-memory sidecar after a final flush.

The projection process benchmark is a relative measure inside the test binary, not the deployed proxy's RSS. At 100,000 records it measured 93.84 MiB process RSS and a 76.50 MiB projection delta; at 10,000 records it measured 37.61 MiB process RSS and a 20.27 MiB delta. The test binary and its linked packages are part of the absolute figure.

A loaded proxy run reached a 115.0 MiB peak with 90,620 durable rows while no dashboard projection was preloaded. A full dashboard preload over an authorized 100,000-row history was not remeasured for this page. Use the projection delta above for the retained analytical cost, not the loaded-process peak as a substitute.

Query and metadata paths¶

The query benchmarks seed a 100,000-row scratch database and decode a 200-row page. These are single-iteration measurements on a shared host, so small differences are not meaningful.

The request metadata path was measured separately. It performs one bounded metadata decode and allocates 16 bytes per call.

The 1 MiB case is about 108 microseconds on this host. It is a metadata decode measurement, not a promise that every 1 MiB request body is fully processed in that time.

Reproduce¶

scripts/perf.sh owns the repeatable local run: bench, stress, streaming, sustained, image, or all. It uses a fresh private scripts/dev.sh instance for each stress mode and stops it through the script's own lifecycle owner.

streaming runs the end-to-end SSE throughput ramp: levels 1, 8, 32, 64, 128, 256, 512 and 1024 for 60 seconds each, with 100 content frames over a one-second stream. PERF_STREAMING_LEVELS, PERF_STREAMING_DURATION, PERF_STREAMING_HOLD, PERF_STREAMING_CHUNKS and PERF_STREAMING_TIMEOUT override those defaults.

sustained runs the fast-response fixture for five minutes at each level in PERF_SUSTAINED_LEVELS (default 128), with PERF_SUSTAINED_DURATION defaulting to 300s. It does not run the held streaming fixture.

The individual commands below are the same evidence path. Use a fresh DEV_COPY_DB=0 instance for each workload. Never target the main instance on port 8080. The stress harness verifies that the target is the private scripts/dev.sh instance before sending traffic.

(
  set -e
  trap 'scripts/dev.sh stop' EXIT
  export MILLIVOLT_OPERATOR_TOKEN='dev-instance-credential'
  DEV_COPY_DB=0 scripts/dev.sh
  go run ./cmd/stress -target http://127.0.0.1:8081 \
    -concurrency 1,8,32,128 -duration 5s -stream-duration 0
)

Use a separate fresh instance for the streaming ramp:

(
  set -e
  trap 'scripts/dev.sh stop' EXIT
  export MILLIVOLT_OPERATOR_TOKEN='dev-instance-credential'
  DEV_COPY_DB=0 scripts/dev.sh
  go run ./cmd/stress -target http://127.0.0.1:8081 \
    -concurrency 1,8,32,128,512 -duration 5s -stream-duration 1s
)

The isolated benchmarks use the test overlay:

scripts/check.sh go test -run='^$' -bench='BenchmarkProjectionFootprint|BenchmarkStoreDiskBytes' \
  -benchtime=1x -count=1 ./internal/web
scripts/check.sh go test -run='^$' -bench='BenchmarkProjectionProcessRSS' \
  -benchtime=1x -count=1 ./internal/web
scripts/check.sh go test -run='^$' -bench='BenchmarkStorageWriter' \
  -benchtime=2s -benchmem -count=1 ./internal/storage
scripts/check.sh go test -run='^$' -bench='Benchmark(QueryBeforeEquality|QueryBeforeCount)' \
  -benchtime=1x -benchmem -count=1 ./internal/storage
scripts/check.sh go test -run='^$' -bench='Benchmark(RequestMetadata|ProxyDurableContention)' \
  -benchtime=2s -benchmem -count=1 ./internal/proxy

The image measurements use a disposable local image:

docker build --platform linux/amd64 -t millivolt-perf .
docker image inspect millivolt-perf --format '{{.Size}}'
docker save millivolt-perf | gzip -9 | wc -c

Idle RSS and CPU were sampled from /proc/<pid>/status and /proc/<pid>/stat after a 15-second settle. The process was started and stopped only through scripts/dev.sh.

Limitations¶

• The host was shared. Other workloads can change absolute rates and latency.
• The upstream was a local synthetic server. Provider latency, TLS, retries, payload shape, and real identity cardinality are not represented.
• These are short closed-loop bursts, not sustained production capacity. No result here is a capacity ceiling or a guarantee.
• The streaming concurrency table is a five-second ramp on a ten-frame, roughly one-second fixture at 1, 8, 32, 128 and 512 workers. The streaming throughput table is a 60-second-per-level ramp on a 100-frame, roughly one-second fixture at 1, 8, 32, 64, 128, 256, 512 and 1024 workers. Both are synthetic-fixture measurements, not universal maxima. The throughput table's 1024 level is above the example max_conns_per_host of 512 and measures queueing; it is a fixed level list, not an automatic saturation search. Its token rate is the fixture's usage count, not provider-token throughput, and the run was taken under variable background load.
• The five-minute sustained sweep uses the fast-response fixture with no intentional stream hold (-stream-duration 0) at 32, 48, 64 and 128 workers. Its 64-worker durable-drop boundary is a writer/accounting boundary, not a maximum streaming rate. The streaming throughput ramp is the only sustained held-stream run; it stops at its fixed levels and does not search beyond 1024.
• Performance checks are manual (scripts/perf.sh), not CI. Each level is one run per invocation on one host; there is no repetition or variance study.
• Durable accounting is best-effort. The fast stages happened to remain exact; the overload benchmark intentionally does not.
• Container-wide CPU/RSS, cold-start time, browser rendering, arm64 image size, disk throughput, and a full dashboard preload over a large authorized history were not measured for this page.
• The image archive is a local artifact, not a published registry digest.
• The source revision is the runtime tree before the later documentation, site, test, and login-page color commits in the same change set. Those commits do not change the request accounting or storage paths measured here.
• The current numbers supersede the older v0.1.0 example. Do not compare them directly across differing hosts, workloads, or revisions.