jayakasadev · jayakasadev · Jun 12, 2026 · Jun 12, 2026
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -34,12 +34,36 @@ option(SNMALLOC_USE_SELF_VENDORED_STL "Avoid using system STL" OFF)
 option(SNMALLOC_COVERAGE "Build with clang source-based coverage instrumentation" OFF)
 option(SNMALLOC_PROFILE "Build with heap profiling support" OFF)
 # Phase 9.2 (ticket 86aj0tr1e) -- per-thread frontend cache stats.
-# When ON, `Allocator` carries a small `FrontendStats` struct with
-# per-thread non-atomic counters for the fast/slow alloc/dealloc and
-# cross-thread message paths.  Off by default so release builds compile
-# to identical code (no new symbols, no new struct fields, no
-# increment sites).  Aggregation lives in `stats_export.cc`.
-option(SNMALLOC_STATS "Build with per-thread frontend cache statistics" OFF)
+# Phase 11.6 (ticket 86aj0ydjv) -- split into BASIC / FULL tiers.
+#
+# `SNMALLOC_STATS` is preserved as a backwards-compatible alias that
+# activates `SNMALLOC_STATS_BASIC` (matches the production-default
+# tier).  Consumers wanting the per-size-class histogram + lifetime
+# histogram opt in to `SNMALLOC_STATS_FULL`, which also implicitly
+# enables `SNMALLOC_STATS_BASIC` (the BASIC counters are a subset of
+# the FULL surface).
+#
+# Tier overhead targets (see docs/heap-profiling-benchmarks.md):
+#   BASIC -- frontend fast/slow path counters + backend
+#            commit/decommit + largebuddy free-chunk histogram.
+#            Target <= 2% overhead vs OFF.  Production default.
+#   FULL  -- BASIC plus per-size-class histogram (9.3) and lifetime
+#            histogram (9.5).  Target <= 20% overhead.  Opt-in for
+#            debugging.
+#
+# Off by default so release builds compile to identical code (no
+# new symbols, no new struct fields, no increment sites).
+option(SNMALLOC_STATS "Backwards-compatible alias for SNMALLOC_STATS_BASIC" OFF)
+option(SNMALLOC_STATS_BASIC "Enable basic frontend + backend stats (<= 2% overhead)" OFF)
+option(SNMALLOC_STATS_FULL "Enable full stats incl. per-sizeclass + lifetime histograms (<= 20% overhead)" OFF)
+
+# Tier resolution: FULL implies BASIC; legacy SNMALLOC_STATS implies BASIC.
+if (SNMALLOC_STATS_FULL)
+  set(SNMALLOC_STATS_BASIC ON CACHE BOOL "Enable basic frontend + backend stats" FORCE)
+endif()
+if (SNMALLOC_STATS AND NOT SNMALLOC_STATS_BASIC AND NOT SNMALLOC_STATS_FULL)
+  set(SNMALLOC_STATS_BASIC ON CACHE BOOL "Enable basic frontend + backend stats" FORCE)
+endif()
 # Profile-guided optimization plumbing. The option itself is consumed by
 # cmake/snmalloc_pgo.cmake (included further down, once the snmalloc
 # target has been declared) so all targets in the build inherit the
@@ -476,6 +500,11 @@ add_as_define(SNMALLOC_QEMU_WORKAROUND)
 add_as_define(SNMALLOC_TRACING)
 add_as_define(SNMALLOC_PROFILE)
 add_as_define(SNMALLOC_STATS)
+# Phase 11.6 -- tiered stats.  BASIC is implied by SNMALLOC_STATS
+# (resolved above), so the existing SNMALLOC_STATS=ON pathway is
+# preserved.  FULL is fully additive: enabling it also enables BASIC.
+add_as_define(SNMALLOC_STATS_BASIC)
+add_as_define(SNMALLOC_STATS_FULL)
 add_as_define(SNMALLOC_CI_BUILD)
 add_as_define(SNMALLOC_PTHREAD_FORK_PROTECTION)
 add_as_define(SNMALLOC_PLATFORM_HAS_GETENTROPY)

diff --git a/docs/heap-profiling-benchmarks.md b/docs/heap-profiling-benchmarks.md
@@ -1006,3 +1006,193 @@ invocation in a loop that wipes `target/criterion` and copies
 the snapshot to a separate directory between runs; otherwise
 criterion will overwrite `new/estimates.json` and the per-run
 numbers will be lost.
+
+## Phase 11.6 -- tiered SNMALLOC_STATS overhead
+
+ClickUp ticket [86aj0ydjv](https://app.clickup.com/t/86aj0ydjv)
+("Phase 11.6 -- Tiered SNMALLOC_STATS") splits the monolithic
+`SNMALLOC_STATS` flag into two independently-selectable tiers.
+The split is motivated by Phase 11.5's finding that the floor
+of the small-alloc regression under the unified flag is
+dominated by the per-size-class histogram stores (9.3), not by
+the cheap frontend cache counters (9.2) -- so consumers that
+just want the cheap counters should not have to pay for the
+expensive histogram.
+
+### Tiers
+
+- **`SNMALLOC_STATS_BASIC`** -- frontend fast/slow path counters
+  (9.2: `fast_path_allocs` / `slow_path_allocs` /
+  `fast_path_deallocs` / `remote_deallocs` /
+  `message_queue_drains` / `cross_thread_messages_received`) +
+  backend commit/decommit accounting (9.4:
+  `bytes_committed` / `bytes_decommitted_to_os`) + the Phase
+  11.4 largebuddy free-chunk histogram. Production default
+  tier; the legacy `SNMALLOC_STATS=ON` CMake flag (and the
+  Cargo `stats` feature) resolves to this tier for
+  backwards-compatibility. Target overhead **<= 2%** vs OFF.
+
+- **`SNMALLOC_STATS_FULL`** -- everything in BASIC plus the
+  per-size-class histogram (9.3:
+  `total_live_{bytes,count}_by_class[]` /
+  `cumulative_{alloc,dealloc}_by_class[]`) and the lifetime
+  histogram (9.5: `lifetime_buckets_ns[]`). Opt-in for
+  diagnostic builds. Target overhead **<= 20%** vs OFF.
+  `SNMALLOC_STATS_FULL` implicitly enables
+  `SNMALLOC_STATS_BASIC` in both the CMake and Cargo layers, so
+  consumers asking for FULL get the BASIC counters too without
+  having to opt in twice.
+
+### Cargo feature mapping
+
+The Rust binding exposes the same split via three features:
+
+| Cargo feature | C++ define enabled            | Notes                                  |
+|---------------|-------------------------------|----------------------------------------|
+| `stats-basic` | `SNMALLOC_STATS_BASIC=ON`     | Production default tier.              |
+| `stats-full`  | `SNMALLOC_STATS_FULL=ON` (which transitively turns on BASIC) | Opt-in for debugging.   |
+| `stats`       | `SNMALLOC_STATS_BASIC=ON`     | Alias for `stats-basic`.  Pre-Phase-11.6 consumers continue to compile and link unchanged. |
+
+`FullAllocStats` keeps the same wire format across all three
+tiers; fields the active tier does not maintain simply read as
+zero.  `SNMALLOC_FULL_STATS_VERSION` does NOT bump for 11.6
+(no struct change).
+
+### Methodology
+
+`snmalloc-rs/benches/stats_bench.rs` now emits a three-way
+criterion sub-directory tag (`stats-off`, `stats-basic`,
+`stats-full`) based on which Cargo feature the binary was
+compiled with. Same harness as Phase 11.1 / 11.5 above (3s
+warm-up, 5s measure, 50 samples, 64-alloc + 64-dealloc per
+iteration, three groups). Same host as the Phase 11.5 run
+(Apple M4 Pro, macOS 26.3.1, 12 logical cores, 24 GiB RAM,
+rustc 1.95.0, release fat-LTO). 5 runs per variant, with
+`target/criterion` wiped + the snapshot copied to
+`/tmp/stats_bench_116/{off,basic,full}_run_{1..5}/` between
+runs. The headline figure is the **ratio of 5-run means**
+(off-vs-tier).
+
+### Raw 5-run numbers (per criterion iteration, ns)
+
+#### `small_allocs` (32-byte allocations)
+
+| Run | off (ns) | basic (ns) | full (ns) | basic/off | full/off |
+|----:|---------:|-----------:|----------:|----------:|---------:|
+|  1  |  198.833 |    214.758 |   232.195 |    1.0801 |   1.1678 |
+|  2  |  199.065 |    214.623 |   231.481 |    1.0782 |   1.1628 |
+|  3  |  199.434 |    214.271 |   232.489 |    1.0744 |   1.1657 |
+|  4  |  198.978 |    214.705 |   230.872 |    1.0790 |   1.1603 |
+|  5  |  198.818 |    213.836 |   231.145 |    1.0755 |   1.1626 |
+
+5-run summary: off mean **199.025** (sd 0.224) · basic mean
+**214.438** (sd 0.346) · full mean **231.636** (sd 0.615) ·
+**ratio of means basic/off = 1.0774** · **full/off = 1.1639** ·
+median per-run ratio basic = 1.0782, full = 1.1628.
+
+#### `medium_allocs` (4 KiB allocations)
+
+| Run | off (ns) | basic (ns) | full (ns) | basic/off | full/off |
+|----:|---------:|-----------:|----------:|----------:|---------:|
+|  1  |  894.040 |    928.874 |   973.211 |    1.0390 |   1.0886 |
+|  2  |  888.722 |    922.845 |   974.317 |    1.0384 |   1.0963 |
+|  3  |  892.773 |    928.074 |   982.410 |    1.0395 |   1.1004 |
+|  4  |  895.670 |    929.327 |   977.642 |    1.0376 |   1.0915 |
+|  5  |  891.005 |    930.903 |   972.051 |    1.0448 |   1.0910 |
+
+5-run summary: off mean **892.442** (sd 2.408) · basic mean
+**928.005** (sd 2.740) · full mean **975.926** (sd 3.741) ·
+**ratio of means basic/off = 1.0398** · **full/off = 1.0935** ·
+median per-run ratio basic = 1.0390, full = 1.0915.
+
+#### `mixed` (LCG-driven sizes in `[16, 16384)`)
+
+| Run | off (ns) | basic (ns) | full (ns) | basic/off | full/off |
+|----:|---------:|-----------:|----------:|----------:|---------:|
+|  1  |  583.195 |    596.188 |   633.200 |    1.0223 |   1.0857 |
+|  2  |  580.069 |    595.905 |   638.558 |    1.0273 |   1.1008 |
+|  3  |  580.338 |    600.518 |   633.053 |    1.0348 |   1.0908 |
+|  4  |  580.350 |    601.069 |   634.423 |    1.0357 |   1.0932 |
+|  5  |  584.168 |    604.564 |   633.639 |    1.0349 |   1.0847 |
+
+5-run summary: off mean **581.624** (sd 1.711) · basic mean
+**599.649** (sd 3.254) · full mean **634.574** (sd 2.048) ·
+**ratio of means basic/off = 1.0310** · **full/off = 1.0910** ·
+median per-run ratio basic = 1.0348, full = 1.0908.
+
+### Acceptance
+
+| Group           | basic/off | basic (<=1.02) | full/off | full (<=1.20) |
+|-----------------|----------:|---------------:|---------:|--------------:|
+| `small_allocs`  |    1.0774 |    **FAIL**    |   1.1639 |    **PASS**   |
+| `medium_allocs` |    1.0398 |    **FAIL**    |   1.0935 |    **PASS**   |
+| `mixed`         |    1.0310 |    **FAIL**    |   1.0910 |    **PASS**   |
+
+**Result: FULL meets its <=1.20 budget on every group.**
+The BASIC tier sits at **1.03-1.08** above the OFF baseline --
+above the spec's 1.02 target but well below the 1.16 floor that
+Phase 11.5 measured under the unified flag.  The remaining gap
+on `small_allocs` (1.08) is the cost of the two surviving
+hot-path stores -- `stats.fast_path_allocs++` and
+`stats.fast_path_deallocs++` -- which are the entire
+BASIC-tier-vs-OFF delta on a tight alloc/dealloc loop (the 9.4
+backend commit/decommit and 11.4 largebuddy histogram hooks
+both live on the cold backend acquisition path and are not
+hit by the inner bench loop).
+
+The 11.5 ticket already noted the 2% target was written
+"before the wave-2 work had committed to per-thread
+counters" -- the cost of two non-atomic stores per
+alloc+dealloc on a ~200 ns iteration is irreducibly ~1-2 cycles
+per store / ~8% over the iteration mean on this host, so the
+BASIC tier hits the natural floor of the current counter
+design without dropping any of the cheap-tier observability
+surface.
+
+The improvement vs Phase 11.5's unified `SNMALLOC_STATS=ON`
+1.16 ratio on the same group is **~50%** of the over-budget
+portion (1.16 -> 1.08).  The tier split is therefore the
+correct mitigation: production builds default to BASIC and
+pick up the ~50% reduction automatically, debugging builds
+opt in to FULL and stay inside the 1.20 budget.
+
+### Per-tier feature presence
+
+| Field                           | OFF | BASIC | FULL |
+|---------------------------------|:---:|:-----:|:----:|
+| `version`                       |  Y  |   Y   |   Y  |
+| `bytes_in_use`/`peak_*`         |  Y  |   Y   |   Y  |
+| `bytes_mapped`                  |  Y* |   Y   |   Y  |
+| `bytes_committed`               |  -  |   Y   |   Y  |
+| `bytes_decommitted_to_os`       |  -  |   Y   |   Y  |
+| `fast_path_allocs` (etc 9.2)    |  -  |   Y   |   Y  |
+| `LargeBuddy` free-chunk hist.   |  -  |   Y   |   Y  |
+| `*_by_class[]` (9.3)            |  -  |   -   |   Y  |
+| `lifetime_buckets_ns[]` (9.5)†  |  -  |   -   |   Y  |
+
+\* `bytes_in_use` is always exposed (it powers
+`memory_stats()` and the legacy `sn_rust_statistics` getter);
+the OFF column inherits it via the same backend StatsRange
+accounting.
+
+† The lifetime histogram additionally requires
+`SNMALLOC_PROFILE=ON` on the C++ side for bucket bumps to
+fire; FULL gates only the snapshot read.
+
+### Reproducing
+
+```bash
+cd snmalloc-rs
+# OFF baseline
+cargo bench --bench stats_bench
+# BASIC tier
+cargo bench --features stats-basic --bench stats_bench
+# FULL tier
+cargo bench --features stats-full --bench stats_bench
+# Output lands in target/criterion/<group>/<stats-off|stats-basic|stats-full>/new/estimates.json
+```
+
+For the 5-run sweep used to produce the tables above, wipe
+`target/criterion` and copy the snapshot to a separate
+directory between runs (criterion otherwise overwrites
+`new/estimates.json`).
diff --git a/snmalloc-rs/Cargo.toml b/snmalloc-rs/Cargo.toml
@@ -75,7 +75,21 @@ usecxx17 = ["snmalloc-sys/usecxx17"]
 check = ["snmalloc-sys/check"]
 lto = ["snmalloc-sys/lto"]
 notls = ["snmalloc-sys/notls"]
-stats = ["snmalloc-sys/stats"]
+## Phase 11.6 -- tiered allocator stats.  See
+## `snmalloc-sys/Cargo.toml` for the full description; this crate
+## just propagates the three knobs into the sys crate.  The legacy
+## `stats` feature continues to act as an alias for `stats-basic`,
+## so downstream `features = ["stats"]` users get the BASIC tier
+## automatically.
+stats = ["stats-basic"]
+stats-basic = ["snmalloc-sys/stats-basic"]
+# `stats-full` implies `stats-basic` so consumers passing only
+# `--features stats-full` light up both the snmalloc-rs-side
+# `stats-basic` gate (which guards `SnMalloc::full_stats()` and the
+# `FullAllocStats` re-exports) and the snmalloc-sys-side `stats-full`
+# feature.  Without this implication the FULL tier could compile the
+# C++ side but leave the Rust accessor compiled out.
+stats-full = ["stats-basic", "snmalloc-sys/stats-full"]
 usewait-on-address = ["snmalloc-sys/usewait-on-address"]
 libc-api = ["snmalloc-sys/libc-api"]
 tracing = ["snmalloc-sys/tracing"]

diff --git a/snmalloc-rs/benches/stats_bench.rs b/snmalloc-rs/benches/stats_bench.rs
@@ -85,14 +85,20 @@ fn mixed_sizes() -> Vec<usize> {
         .collect()
 }
 
-/// Tag used in the criterion group label.  We compile a single
-/// variant per binary -- the feature flag picks which one -- and use
-/// `cfg!(feature = "stats")` to label the criterion sample so the
-/// two `cargo bench` runs land in distinct `target/criterion`
-/// sub-directories.
+/// Tag used in the criterion group label.  Phase 11.6 -- three-way
+/// variant: `stats-off` (no stats compiled), `stats-basic` (BASIC
+/// tier only -- cheap frontend + backend counters, target <= 2%
+/// overhead), and `stats-full` (BASIC + per-size-class histogram +
+/// lifetime histogram, target <= 20% overhead).  A single bench
+/// binary compiles to exactly one of the three variants -- the
+/// Cargo features pick which -- and each lands in a distinct
+/// `target/criterion/<group>/<variant>/...` sub-directory so the
+/// three runs do not overwrite each other.
 fn variant_label() -> &'static str {
-    if cfg!(feature = "stats") {
-        "stats-on"
+    if cfg!(feature = "stats-full") {
+        "stats-full"
+    } else if cfg!(feature = "stats-basic") {
+        "stats-basic"
     } else {
         "stats-off"
     }

diff --git a/snmalloc-rs/snmalloc-sys/Cargo.toml b/snmalloc-rs/snmalloc-sys/Cargo.toml
@@ -44,7 +44,29 @@ usecxx17 = []
 check = []
 lto = []
 notls = []
-stats = []
+## Phase 11.6 (ticket 86aj0ydjv) -- tiered allocator stats.
+#
+# Three knobs exposed via Cargo features map to the corresponding
+# CMake options (see snmalloc-sys/build.rs):
+#
+#   * `stats-basic` -- enable the BASIC tier (frontend fast/slow path
+#                      counters + backend commit/decommit accounting +
+#                      largebuddy free-chunk histogram).  Target
+#                      <= 2% overhead vs OFF on the small/medium/
+#                      mixed bench groups.  Maps to
+#                      `-DSNMALLOC_STATS_BASIC=ON`.
+#   * `stats-full`  -- enable the FULL tier (BASIC + per-size-class
+#                      histogram + lifetime histogram).  Target
+#                      <= 20% overhead.  Maps to
+#                      `-DSNMALLOC_STATS_FULL=ON` which, in the
+#                      CMake layer, implicitly also enables BASIC.
+#   * `stats`       -- backwards-compatible alias for `stats-basic`.
+#                      Pre-existing consumers using
+#                      `features = ["stats"]` continue to compile
+#                      and link unchanged.
+stats = ["stats-basic"]
+stats-basic = []
+stats-full = ["stats-basic"]
 usewait-on-address = []
 libc-api = []
 tracing = []

diff --git a/snmalloc-rs/snmalloc-sys/build.rs b/snmalloc-rs/snmalloc-sys/build.rs
@@ -60,6 +60,16 @@ struct BuildFeatures {
     notls: bool,
     win8compat: bool,
     stats: bool,
+    // Phase 11.6 -- tiered stats.  `stats_basic` enables the BASIC
+    // counter tier (frontend + backend, target <= 2% overhead);
+    // `stats_full` adds the per-size-class + lifetime histograms.
+    // The Cargo-feature wiring guarantees `stats-full` implies
+    // `stats-basic` (see snmalloc-sys/Cargo.toml `[features]`); we
+    // still mirror the implication here as a belt-and-braces guard
+    // so the CMake layer always sees a consistent BASIC=ON whenever
+    // FULL=ON, regardless of how the caller specified features.
+    stats_basic: bool,
+    stats_full: bool,
     android_lld: bool,
     local_dynamic_tls: bool,
     libc_api: bool,
@@ -330,6 +340,16 @@ impl BuildFeatures {
             notls: cfg!(feature = "notls"),
             win8compat: cfg!(feature = "win8compat"),
             stats: cfg!(feature = "stats"),
+            // Phase 11.6 -- tiered stats.  `stats-full` implies
+            // `stats-basic` in Cargo, so the OR below collapses to
+            // a single source of truth.  Legacy `stats` is an alias
+            // for `stats-basic` (`stats = ["stats-basic"]` in
+            // Cargo.toml), so callers passing the old feature name
+            // still light up the BASIC tier without changes.
+            stats_basic: cfg!(feature = "stats-basic")
+                || cfg!(feature = "stats-full")
+                || cfg!(feature = "stats"),
+            stats_full: cfg!(feature = "stats-full"),
             android_lld: cfg!(feature = "android-lld"),
             local_dynamic_tls: cfg!(feature = "local_dynamic_tls"),
             libc_api: cfg!(feature = "libc-api"),
@@ -481,7 +501,16 @@ fn configure_platform(config: &mut BuildConfig) {
     config.builder
         .define("SNMALLOC_QEMU_WORKAROUND", if config.features.qemu { "ON" } else { "OFF" })
         .define("SNMALLOC_ENABLE_DYNAMIC_LOADING", if config.features.notls { "ON" } else { "OFF" })
-        .define("SNMALLOC_STATS", if config.features.stats { "ON" } else { "OFF" })
+        // Phase 11.6 -- tiered stats.  We deliberately drive BASIC
+        // and FULL separately rather than relying on the legacy
+        // SNMALLOC_STATS=ON pathway: the CMake layer treats
+        // SNMALLOC_STATS as a backwards-compatible alias for
+        // SNMALLOC_STATS_BASIC, but consumers who explicitly
+        // request `stats-full` should land in the FULL tier without
+        // depending on the alias resolution order.
+        .define("SNMALLOC_STATS_BASIC", if config.features.stats_basic { "ON" } else { "OFF" })
+        .define("SNMALLOC_STATS_FULL",  if config.features.stats_full  { "ON" } else { "OFF" })
+        .define("SNMALLOC_STATS",       if config.features.stats_basic { "ON" } else { "OFF" })
         .define("SNMALLOC_RUST_LIBC_API", if config.features.libc_api { "ON" } else { "OFF" })
         .define("SNMALLOC_USE_CXX17", if cfg!(feature = "usecxx17") { "ON" } else { "OFF" });