memory-benchmark

Memory Benchmarking & Analysis

The perf/memory crate benchmarks memory usage of SQL workloads under WAL and MVCC journal modes. It uses dhat as the global allocator to track every heap allocation, and memory-stats for process-level RSS snapshots.

It also contains a stack-report helper binary for stack-usage investigations. That binary runs a SQL payload with the stacker feature enabled and captures turso_stack tracing events in-process, aggregating structured tracing fields instead of parsing stderr log text.

Location

• Benchmark crate: perf/memory/
• CodSpeed bench crate: perf/memory/codspeed/ (CI allocation regression tracking)
• Analysis script: perf/memory/analyze-dhat.py
• dhat output: dhat-heap.json (written to CWD after each run)

The crate is split into a library and binaries. The workload engine lives in memory_benchmark::workload (run_workload, WorkloadConfig, WorkloadObserver, the JournalMode/WorkloadProfile enums and create_profile); the memory-benchmark bin is a thin CLI over it that adds dhat/RSS measurement. Randomized profiles (read-heavy, mixed) use a fixed RNG seed (profile::WORKLOAD_RNG_SEED) so workloads are identical across runs.

Running Stack Reports

Use this when investigating stack usage from SQL translation/execution probes. Run stack reports in release mode with --features stacker when comparing against server logs or CI stack-size output. Debug builds can materially overstate stack deltas and should only be used for quick local iteration.

cargo run --release -q -p memory-benchmark --features stacker --bin stack-report -- \
  --sql path/to/payload.sql \
  --top 40

Useful options:

--sql FILE|-             # SQL payload, or stdin with -
--format human|json|csv  # output format
--top N                  # aggregate/span rows per statement in human output
--statement N[,N...]     # only include reports for 1-based statement indexes
--sql-contains TEXT      # only include reports for statements containing TEXT, ASCII case-insensitive