Skip to content

Memory budget excludes hydrate/squeeze transients: tier reports at limit while the process holds 3x that #43

Open

Description

@zfarrell

Summary

The memory budget accounts for an entry only once it has landed in the index. Every
intermediate that the hydrate → insert → squeeze cycle creates on the way there is
invisible to it — and that cycle runs per batch for any scan whose working set exceeds
the memory tier.

Measured on a 16 GiB container with a 5.15 GB memory tier and a 30 GB disk tier, scanning
a synthetic table of ~960k rows at ~7.5 KB/row (~7.3 GB): the cache's own
used_memory_bytes sat at 5.14 GB against its 5.15 GB limit — perfect by its own
bookkeeping — while process anonymous memory reached 16.35 GB and the container was
OOM-killed. At rest, with no queries running, the same process holds 8.64 GB against a
tally of 5.04 GB.

Because the host query engine's memory pool only tracks its own operators, nothing in the
system can see or refuse these bytes.

Where the accounting stops

All line references are at rev 3aec144.

  • BudgetAccounting::try_reserve_memory (src/core/src/cache/budget.rs:38) has exactly
    one non-test reserving caller: CacheStorage::try_insert
    (src/core/src/cache/core.rs:404-425), which reserves at the moment the entry is
    inserted into self.index. (The release path,
    drop_memory_entry → try_update_memory_usage(…, 0) at core.rs:451, is the other
    budget touchpoint.)
  • read_disk_liquid_array (src/core/src/cache/core.rs:840-861) fetches the object and
    runs ipc::read_from_bytes into a LiquidArrayRef with no budget interaction at
    all
    .
  • maybe_hydrate (defined src/core/src/cache/core.rs:569; read-path call sites at 160,
    651, 673, 766, 894, 916) then promotes that decoded entry toward the memory tier.
  • insert_inner (src/core/src/cache/core.rs:339-369) loops: try_insert → on failure
    find_memory_victim(8) → squeeze_victims → retry, holding the pending entry across
    every iteration.

So each iteration can have all of the following live and uncounted simultaneously:

  1. the decoded disk-tier entry,
  2. the hydrated copy being inserted,
  3. up to 8 victims' transcode outputs (TranscodeSqueezeEvict compresses to FSST in
    memory before the result is indexed),
  4. the Arrow array materialized for the caller.

Reading from the cache triggers this, not just filling it

This is what makes it a continuous cost rather than a warm-up cost, and it was active
during the OOM itself
.

squeeze is reached from both read_parquet_batch_and_fill_cache and
CachedColumn::get_arrow_array_with_filter. In the heap profile of the window that ended
in the kill, the read-side path is:

CachedColumn::get_arrow_array_with_filter        21.4%
  ├─ LiquidCache::read_disk_liquid_array         20.7%
  └─ futures_util::stream::collect::Collect::poll
       └─ TranscodeSqueezeEvict::squeeze         43.5%

That intermediate Collect node is the buffer_unordered(…).collect() inside
squeeze_victims, so the graph shows the read path entering the concurrent squeeze
directly. A disk-tier read re-inserts into the memory tier, the tier is full, and the
insert loop squeezes 8 victims.

It follows from AlwaysHydrate being the default hydration policy
(src/datafusion-local/src/lib.rs:91): a query whose working set is larger than the memory
tier churns indefinitely, warm or cold. A warm profile makes it unambiguous only because
there are no parquet-decode frames left to confuse it with — 49.2% of live heap is FSST
transcode with zero decode frames present.

Two aggravating details

Squeeze concurrency is unbounded, for victims that write to disk. squeeze_victims
(src/core/src/cache/core.rs:493-510) uses buffer_unordered(usize::MAX) with no byte
bound, so nothing limits how many victims' outputs are resident together.

The scope needs stating precisely, because an earlier revision of this issue overstated
it. These are futures on the calling task, so they only overlap across an await. A
MemoryArrow victim whose transcode succeeds returns bytes_to_write: None
(src/core/src/cache/policies/squeeze.rs:116-119) — no disk write, hence no await, hence
each such future runs to completion in a single poll and no two are ever mid-squeeze
together. The pile-up requires a victim already in liquid form, whose squeeze writes
its backing to disk and therefore awaits. Measured on that case: peak in-flight reaches
about 9x one entry's size (all eight victims plus the pending entry) unbounded, against
~3x when byte-bounded.

Production takes the concurrent path; the tests only take the sequential one.
src/core/src/cache/builders.rs:64 sets squeeze_victims_concurrently: !cfg!(test). So
the memory shape that ships is the one no test exercises.

Transcode buffers grow by doubling. 69.6% of sampled bytes in that window arrive via
do_rallocx (realloc growth) rather than fresh allocation, which both leaves doubling
slack in finished buffers and frees a long tail of half-grown ones.

Measurements

container limit 17.18 GB
memory tier limit / reported use at peak 5.15 GB / 5.14 GB
disk tier in use ~30 GB
process anon, idle, nothing running 8.64 GB (tally 5.04 GB)
process anon, peak during scan 16.35 GB → OOM-killed
live heap at a single profile upload near peak ~12.4 GB of 16.35 GB
TranscodeSqueezeEvict::squeeze share of live heap 43.5% (cold window), 49.2% (warm)
SpillReaderStream share, for contrast 13.5%

Profile shares are from inuse_space with lg_prof_sample:20; attribution is by
allocation site, not by holder. Note that a shallow node cut hides this mechanism: at a
top-28 cut the squeeze frame falls below the threshold and its incoming read-path edge
collapses into the truncation node, which is what made an earlier revision of this issue
claim the read-triggered squeeze was absent when cold. It is not.

Suggested directions

  1. Count in-flight bytes against the budget, not just indexed ones — reserve before
    decoding/hydrating/transcoding and release on failure, so the tier's limit bounds the
    cycle's true footprint rather than its end state.
  2. Make hydration conditional. Skip re-inserting a disk-tier hit when the caller's
    working set clearly exceeds the memory tier. A policy that always hydrates converts
    every read of an oversized working set into an eviction storm.
  3. Bound squeeze concurrency — buffer_unordered with a small constant instead of
    usize::MAX.
  4. Expose an in-flight gauge alongside used_memory_bytes. The current gauge reading
    exactly at limit while the process holds three times that is the reason this went
    unnoticed.
  5. Cover the concurrent squeeze path in tests, given it is the only one that ships.

Not established

  • The idle excess is unexplained. 8.64 GB resident against a 5.04 GB tally with nothing
    running. CachedBatch::memory_usage_bytes
    (src/core/src/cache/cached_batch.rs:68-75) delegates to get_array_memory_size, and
    LiquidByteViewArray::get_detailed_memory_usage
    (src/core/src/liquid_array/byte_view_array/mod.rs:225-239) sums its components
    including the FSST buffer's capacity — so simple slack does not obviously explain it.
    One candidate: reference_count (cached_batch.rs:78) is reported in stats but does not
    gate eviction, so an entry can be evicted — dropping its contribution to the tally to
    zero for a disk-tier entry — while an outstanding Arc keeps the array alive.
  • The split between live intermediates and allocator-retained pages at peak. Only
    ~12.4 GB of the 16.35 GB peak is live heap. The remainder is plausibly freed-but-unpurged
    pages given the realloc churn, but a heap profile cannot attribute those. jemalloc's
    stats.allocated vs stats.resident would settle it; in our build nothing enables
    tikv-jemalloc-sys/stats, so jemalloc compiles --disable-stats and those counters do
    not exist. Comparing a single profile upload's total against process anon is the
    available substitute.

Activity

  1. zfarrell commented on Sep 3, 2026

    @zfarrell
    Author

    Reproduced locally without the fixture: a counting global allocator around a 32 MiB tier and a ~190 MiB working set (src/core/tests/memory_footprint.rs in #45) shows idle live heap at 6.14x the tally and the read-pass peak at 6.09x the limit, in two seconds.

    The dominant cause is not in-flight transcode transients. CongeeArc::remove/insert drop the replaced Arc through crossbeam-epoch deferred destruction, so every evicted or replaced array stays alive until a later collection, invisible to the budget. Emptying the index freed nothing; forcing 20k pins afterwards dropped live heap from 73.9 to 8.7 MiB. The heap profile's "43-49% under squeeze" is allocation-site attribution of that resident and deferred-garbage cache content, which is also what the idle 8.64 GB vs 5.04 GB was. A second defect rode along: a hydrated DiskLiquid entry re-serialised and rewrote its own bytes on eviction and reserved the disk budget twice (190 writes in a pure read pass; disk tally 2.7x the real objects), which explains the disk tier reading ~30 GB. Both are fixed in #45 with regression assertions; after the fix the same test reads 1.01x idle and 1.71x peak.

  2. zfarrell commented on Nov 17, 2026

    @zfarrell
    Author

    Found by a memory-accounting audit of 8b3c813. The tests are on branch audit/memory-tests and fail on main today; check out that branch to run them. File and line links point at that commit.

    #43 already covers uncounted transients, unbounded buffer_unordered(usize::MAX) (now core.rs:832), and the production-only concurrent path (builders.rs:64). Add:

    • Insert peaks: 8.2–9.2x a 512 KiB budget for strings. Int64 passes narrowly at 1.95x.
    • Read peaks: 5x the budget for strings; Int64 also fails.
    • Transcode scratch: one string transcode has a floor of about 3.4–3.7 MB regardless of input. A 64-row dictionary array used 3.37 MB.
    • Concurrent spill: with 8 victims parked before store.put, the cache held 1,616,472 uncharged bytes, about 25x one victim.
      • Each victim holds its serialized Bytes at 2x its length (from arrow_to_bytes) plus the object Vec at core.rs:1090-1092.
      • That is about 3 copies per victim, not 3 in total as first estimated from reading the code.
    • Reads (measurement only): a read of an in-memory liquid entry returns an Arrow array 3.2–43.9x the charged size, counted nowhere. Whether the cache should account for it is a design question.
    • to_bytes() slack: it returns a Vec with spare capacity (len 21,727, capacity 41,990) that Bytes::from keeps alive. Measured on the Arrow path only.
    Test File Command Flags
    audit_insert_peak_within_twice_the_budget_utf8 src/core/tests/audit_cache_heap.rs:385 cargo +1.96.0 test -p liquid-cache --test audit_cache_heap audit_insert_peak_within_twice_the_budget_utf8 -- --nocapture --test-threads=1
    audit_insert_peak_within_twice_the_budget_string_view src/core/tests/audit_cache_heap.rs:390 cargo +1.96.0 test -p liquid-cache --test audit_cache_heap audit_insert_peak_within_twice_the_budget_string_view -- --nocapture --test-threads=1
    audit_insert_peak_within_twice_the_budget_int64 src/core/tests/audit_cache_heap.rs:395 cargo +1.96.0 test -p liquid-cache --test audit_cache_heap audit_insert_peak_within_twice_the_budget_int64 -- --nocapture --test-threads=1 C (passes at 1.95x)
    audit_read_peak_within_twice_the_budget_utf8 src/core/tests/audit_cache_heap.rs:400 cargo +1.96.0 test -p liquid-cache --test audit_cache_heap audit_read_peak_within_twice_the_budget_utf8 -- --nocapture --test-threads=1
    audit_read_peak_within_twice_the_budget_int64 src/core/tests/audit_cache_heap.rs:405 cargo +1.96.0 test -p liquid-cache --test audit_cache_heap audit_read_peak_within_twice_the_budget_int64 -- --nocapture --test-threads=1
    audit_report_read_of_liquid_entry_returns_uncharged_arrow src/core/tests/audit_cache_heap.rs:415 cargo +1.96.0 test -p liquid-cache --test audit_cache_heap audit_report_read_of_liquid_entry_returns_uncharged_arrow -- --nocapture --test-threads=1 M
    audit_transcode_scratch_is_bounded_by_its_input src/core/src/liquid_array/size_audit.rs:669 cargo +1.96.0 test -p liquid-cache --lib audit_transcode_scratch_is_bounded_by_its_input -- --nocapture
    audit_concurrent_spill_scratch_is_bounded_by_one_victim src/core/src/cache/audit_spill.rs:42 cargo +1.96.0 test -p liquid-cache --lib audit_concurrent_spill_scratch_is_bounded_by_one_victim -- --nocapture holds all 256 disk_key_locks
    alloc_vs_budget src/core/tests/alloc_vs_budget.rs:464 AVB_CYCLES=20 AVB_OVERWRITE_ITERS=100 cargo +1.96.0 test -p liquid-cache --test alloc_vs_budget -- --nocapture --test-threads=1 M, about 2 min (full run about 7 min)

    Caveat: the numbers are requested bytes, from a debug build at small scale. RSS will be higher.

    Flags: P probabilistic (a pass after a fix only means the race wasn't hit), F interleaving forced by a test hook, L Linux only, D needs Docker, M measurement only, C control (passes by design).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions