WiredTiger cache sizing and memory fragmentation
Parent: WiredTiger cache eviction and dirty ratio · Published reference · snapshot 2026-10-31
↓ Facts as markdownall context files
Source-anchored research for WiredTiger cache sizing and memory fragmentation. Run status: COMPLETED.
These notes link each claim to its source. Some citations identify archived research reports that are no longer hosted on this site. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.
How it works
- Budget memory outside WiredTiger: MongoDB also uses filesystem cache and separate application allocations. A stable WiredTiger cache can coexist with increasing process memory, as demonstrated by the MyDBOps production investigation. (medium confidence) [source]
- MongoDB advises avoiding increases above the default WiredTiger cache size and allows reductions for other RAM consumers. For containers, check hostInfo.system.memLimitMB and size against the container allowance; shared hosts with multiple mongod processes require smaller per-process caches. (low confidence) (verified as of 2026-10-14) [source]
- Starting with MongoDB 8.0, the upgraded TCMalloc uses per-CPU caches on supported platforms with the stated aim of reducing fragmentation. Percona independently tested complete 7.0 and 8.0 server versions, but its test does not isolate the allocator as the sole cause of performance changes. (medium confidence) (verified as of 2025-12-22) [source]
- For diagnosis, compare serverStatus.tcmalloc.generic.current_allocated_bytes, heap_size, free-list statistics, WiredTiger occupancy, and OS RSS over time. This is a synthesis of MongoDB accounting and upstream allocator definitions; no single one of these measurements identifies the cause of growth. (medium confidence) [source]
Measurements and reference values
- MongoDB 8.0 documents a default WiredTiger cache of max(50% × (RAM − 1 GB), 0.256 GB); its 4 GB example yields 1.5 GB. Percona's 16 GB example yields 7.5 GB, confirming that the subtraction occurs before multiplication. (medium confidence) (verified as of 2026-10-27) [source]
- The documented default WiredTiger internal cache is max(0.5 × (RAM − 1 GB), 0.256 GB); a 4 GB system therefore defaults to 1.5 GB. This is a cache budget, not a total mongod memory ceiling. (low confidence) (verified as of 2026-10-14) [source]
- For the upgraded allocator, MongoDB documents supported Linux x86_64 and ARM64 deployments; Windows, PPC64LE, and s390x use the legacy allocator. Its guidance enables THP for the upgraded allocator and disables it for MongoDB 7.0 or earlier and the documented legacy Linux architectures. (low confidence) (verified as of 2026-10-14) [source]
Problems, failure modes and limitations
- Percona traced an allocator configuration failure in Docker to getMemorySizeLimitInBytes parsing the cgroup value 'max' with atoll and treating the resulting zero as available memory. This is evidence that allocator behavior can depend on container-specific parsing, not just the configured WiredTiger cache size. (low confidence) [source]
Comparisons and alternatives
- cacheSizeGB limits the WiredTiger internal cache, rather than total mongod memory. MongoDB also benefits from filesystem caching; increasing the internal cache consumes RAM otherwise available for compressed file pages and other consumers. (medium confidence) [source]
- Allocator statistics separate live application bytes, page-heap free memory, partially used spans, per-CPU/thread caches, and metadata. Allocator totals can differ from RSS; an RSS-minus-WiredTiger-cache gap alone does not measure fragmentation or prove a leak. (medium confidence) [source]
- MongoDB's repository describes application threads joining eviction when cache triggers are reached. Long-running transactions can make cache pressure stall progress. For secondary-read investigations, treat eviction work and latency as diagnostic signals rather than assuming that high cache occupancy alone proves fragmentation. (low confidence) (verified as of 2026-10-30) [source]
- TCMalloc central free lists contain partially used spans, while page-heap free lists contain unused memory that could be returned to the OS. Its reported actual memory usage can differ from RSS and excludes mappings outside its accounting. (low confidence) [source]
Facts and statements
- For containerized or colocated mongod instances, size the internal cache against the memory actually available to the instance and leave room for other consumers. The versioned MongoDB documentation warns that container limits may not always be accounted for automatically. (low confidence) (verified as of 2026-10-27) [source]
- WT-6175 describes small insert/update allocations increasing allocator overhead, including allocations retained on pages marked clean after checkpoint. Its original reproduction involved loading data and then a long index-building scan. This is historical evidence from the MongoDB 4.4 development period, not proof that a current secondary read has the same bug. (low confidence) [source]
- MongoDB 8.0 introduced an upgraded TCMalloc using per-CPU caches on supported platforms. MongoDB documents Linux x86_64 and ARM64 support and legacy allocators on other listed platforms; Percona describes the same allocator change. Platform and configuration checks must precede expectations of reduced fragmentation. (medium confidence) (verified as of 2026-10-14) [source]
- Percona compared PSMDB 7.0.26-14 with 8.0.16-5 using four workload threads and ten-minute tests on 4-CPU, 4-GB Ubuntu 24.04 servers. These are short, whole-version benchmarks and do not establish long-duration secondary-read memory safety or an allocator-only speedup. (low confidence) (verified as of 2025-12-22) [source]
- MyDBOps reports a MongoDB 7.0.14 incident in which WiredTiger cache remained stable while allocations outside it grew; investigation implicated SBE plan-cache growth. This is an example of another memory consumer, not evidence that all high RSS is allocator fragmentation. (low confidence) (verified as of 2025-12-08) [source]
- TCMalloc distinguishes live application bytes from allocator-held memory: heap allocation includes both used and unused memory, while free lists retain reusable blocks. Consequently, heap size minus live allocation is not by itself proof of a leak. (medium confidence) [source]
- Verify allocator activation with serverStatus.tcmalloc.usingPerCPUCaches=true and tcmalloc.tcmalloc.cpu_free>0. If per-CPU caches do not activate, MongoDB documents checking glibc rseq registration and Linux kernel 4.18 or later. Do not assume that installing 8.0 alone activates per-CPU caching. (medium confidence) (verified as of 2026-10-14) [source]
Children
- Allocator live bytes versus RSS and retained free memory (frontier)
- WiredTiger cache eviction diagnostics (frontier)
- Container memory limits and allocator cache configuration (frontier)
- Allocator free-list and RSS accounting (frontier)
- Container-aware WiredTiger memory budgets (frontier)
- Per-CPU TCMalloc activation diagnostics (frontier)
Frontier under this node: Allocator free-list and RSS accounting, Allocator live bytes versus RSS and retained free memory, Container memory limits and allocator cache configuration, Container-aware WiredTiger memory budgets, Per-CPU TCMalloc activation diagnostics, WiredTiger cache eviction diagnostics