Performance limits #

Measured headline numbers for the v0.2.0 data layer. Use them to size projects, to spot regressions, and to know when you're approaching a cliff.

All numbers below were measured on a developer-class WSL2 host in 2026‑06 using pytest tests/test_data/test_perf.py -m benchmark (pytest-benchmark, warmup on, min_rounds=30 for query suites, GC disabled for query suites). Mean reported unless noted. Reproduce locally with:

pytest tests/test_data/test_perf.py -m benchmark --benchmark-only \
    --benchmark-columns=min,mean,stddev,median,iqr,ops

The means below are a "what to expect" baseline, not a regression gate — a gate wants minimum-over-rounds sampling, which is more stable than the means here.

To measure these numbers on your own machine — and get a result file you can send in when you hit a performance problem — run litmus benchmark. It runs the same store workloads against a throwaway directory and reports durable throughput per store, parallel-writer scaling, and the run's RAM/CPU footprint.

EventStore #

Cliff: linear scan past ~10k matched events trends into 100 ms+ territory. Above that, repeated re-scans within a single render add perceptible lag. Use the typed-column filters when you can — they're the difference between "instant" and "perceptible lag."

ChannelStore #

Cliff: ChannelStore writes scale linearly through 10k samples. At ~130k samples/s the bottleneck is the per-write append + flush batching. If you need higher sustained rates — > 50 kHz acquisition, many concurrent channels — the data path holds up but the subscribe side starts to lag the producer. Stay under ~50 kHz per channel on this release.

FileStore #

One-shot writes (files.write) #

Reads #

Cliff: the cold-disk case is not measured (every benchmark hits page cache). Production retention design should assume reads from cold storage are 100×–1000× slower for large artifacts. The resolve_uri walk is fast today because every test session lands in the current date partition; the worst case (cross-month historical reads) scales with the number of days spanned. Per-store indexing to flatten that is on the roadmap.

Streaming sinks (files.stream(format=...)) #

The "mean per call" column below is per burst — each benchmark invocation opens a sink, writes n chunks, then closes. Divide bytes by the mean to get sustained throughput.

Cliff: raw streaming hits a sustained ~400 MB/s on this hardware, limited by the per-chunk fsync-rename atomic. The cliff is latency variance, not bandwidth — single chunks routinely take 10× the median under contention. If you need predictable per-chunk latency, keep chunks ≤ 64 KB; if you need throughput, batch up to 1 MB per chunk and accept the variance.

jsonl is the cheapest format for event-style accumulation but scales linearly with row count per chunk because every row gets its own json.dumps. For dense numeric data, use tdms or h5.

When to worry about a regression #

Roughly, a 1.5× slowdown on any of the above numbers is regression- worth-investigating territory. The release-prep gates in tests/test_data/test_perf_daemon.py are the formal contract; they use min-over-rounds rather than means so transient spikes don't fail the build. The means in this doc are not gates — they're the "what users should expect" baseline.

Three benchmarks are known noisy:

Cold-storage read benchmarks and a "many concurrent producers" sustained-rate test for ChannelStore are not measured in this release.

Concurrency — multi-process scaling #

All four stores hold up under N concurrent writers. Numbers below measured at N = 1, 2, 4 spawned subprocesses (the multiprocessing spawn start method, see the fork-deadlock pitfall below). Each worker writes its own session / channel / artifact bucket so the benchmarks model the multi-UUT pytest case where N workers run concurrently against the canonical data dir.

(Efficiency = ideal-parallel-wall / observed-wall × 100. 100 % = perfect linear scaling; 50 % at N=4 = pretending 4 workers run as 2.)

Reading these:

• No singleton catastrophe. The EventStore daemon serves N writers without going serial; total throughput climbs ~3.9× from N=1 to N=4.
• Constant per-process cost on EventStore (~89 % efficiency at all N ≥ 2) is fixed per-process overhead. Adding more workers gives you more total work done; it doesn't speed up any one worker.
• ChannelStore + FileStore lose ~20 % efficiency at N=4 — filesystem contention on the atomic rename pair dominates. Stddev climbs sharply at N=4 on both. Below N=4 it's free.
• RunStore barely parallelizes (~1.3× from N=1 to N=4): finalizing a run writes a parquet file and materializes it, which is heavy per-op and serializes more than the other stores' writes. Concurrent run finalization is the weakest scaling of the four stores — size accordingly if many stations finalize runs at once.

To reproduce all of this on your own machine, run litmus benchmark --full: it runs the same 1/2/4 writer sweep per store and reports the speedup, plus the single-writer throughput and the run's RAM/CPU footprint.

⚠ Fork-deadlock pitfall — must use spawn, not fork #

The EventStore runs background threads. Python's default multiprocessing.Pool() uses fork() on Linux, which doesn't carry those threads into the child, so the children deadlock on the first store write.

Symptom: workers spawn, then hang indefinitely; the parent never sees output from the children.

Fix: use multiprocessing.get_context("spawn").Pool(...) instead of Pool(...). Slower spawn (each child re-imports Python + libs) but no shared mutex state. The concurrency benchmarks above use spawn for this reason.

Production implication: any code that calls os.fork() or multiprocessing.Process() after the EventStore singleton is alive in the parent will deadlock the children. The slot-runner mode is safe because each pytest worker is spawned by pytest itself before the parent imports Litmus heavily; ad-hoc helpers in test code that fork their own subprocesses after emitting any events must opt in to spawn explicitly.

This is the single most important concurrency caveat in v0.2.0. It is not a Litmus bug — it is the standard Python fork + threads hazard — but the v0.2.0 docs surface it here because Litmus's singleton stores make it easy to hit.

Hardware envelope used to produce these numbers #

WSL2 on Windows, ext4 on the WSL VHDX. Single producer per benchmark. No real network — Flight runs on loopback. Numbers will vary by ±2× across SSDs, ±3× across CPU generations, and dramatically under sustained multi-process load. Treat them as a sanity check, not a contract.