skip to content

Cache Sizing & Eviction

WiredTiger's cache has a formula-based default and sits beside the filesystem cache, and eviction pressure can stall application threads. Interviewers ask how to size it and read the symptoms.

part ofMongoDBread it →
on this pageshow

explore

questions

6

In MongoDB, what does cacheSizeGB control, and how big is the WiredTiger cache if you leave it unset?

level: juniorimportance: must knowfreq 45%

answer

  1. a ceiling on one memory area
  2. whole instance, not per database
  3. subtract one gigabyte, then halve
  4. a 256 MB floor

basics

~10 s

cacheSizeGB sets the maximum size of WiredTiger's internal cache. Left unset, mongod uses the larger of 256 MB and half of (RAM minus 1 GB), so a 64 GB host gets about 31.5 GB.

solid answer

~40 s

`storage.wiredTiger.engineConfig.cacheSizeGB`, or `--wiredTigerCacheSizeGB` on the command line, caps the internal cache where WiredTiger keeps collection and index pages in memory. There is one such cache per `mongod`, not one per database. Unset, `mongod` computes the size at startup as the larger of 256 MB and `0.5 * (RAM - 1 GB)`: 1.5 GB on a 4 GB host, about 31.5 GB on a 64 GB host. People say "half of RAM", and the option's own help text does too, but the code subtracts the gigabyte first. The setting is not a limit on all of `mongod`'s memory: connections and index builds sit outside it, and the operating system uses free RAM as filesystem cache. You can confirm the effective value in `serverStatus` under `wiredTiger.cache`, field `maximum bytes configured`.

code

yaml · 4 lines
yaml
storage:
  wiredTiger:
    engineConfig:
      cacheSizeGB: 16

go deeper

for a junior

Recall the option's job and the shape of the default: subtract 1 GB, halve it, never below 256 MB. Work the 64 GB example aloud.

for a middle

Explain that the setting bounds one area of memory only, and name what sits outside it: index builds, connections and the operating system's filesystem cache.

for a senior

Show you verify rather than assume: read the configured maximum back from serverStatus, and treat a surprising number as a sign that the server sees different memory than you think.

for a principal

Frame the default as a sound assumption about one mongod per machine, and treat any departure from it as a decision somebody should own and write down.

## What the setting controls `storage.wiredTiger.engineConfig.cacheSizeGB` (on the command line, `--wiredTigerCacheSizeGB`) is a `mongod` option that sets the **maximum size of WiredTiger's internal cache**. WiredTiger is MongoDB's storage engine. Its internal cache is the memory where it keeps copies of recently used collection and index pages, so that it can serve them without going back to storage. Three properties of that cache come straight from the manual and surprise people who expect finer control: - **One cache per `mongod`.** WiredTiger allocates it to the entire instance, not per database or per collection. - **No split between reads and writes.** No portion is reserved for one or the other. - **No pinning.** You cannot pin documents into the cache. ## The default, as the code computes it When neither cache option is set, `WiredTigerUtil::getMainCacheSizeMB` (MongoDB 9.0.4) computes the size at startup: ```plaintext cacheSizeMB = max((memSizeMB - 1024) * 0.5, 256) ``` The result is rounded down to a whole number of megabytes. | RAM the server sees | Default cache | Why | |---|---|---| | 1 GB | 256 MB | the formula gives 0, so the floor applies | | 1.5 GB | 256 MB | the formula and the floor meet exactly here | | 2 GB | 512 MB | `(2048 - 1024) * 0.5` | | 4 GB | 1.5 GB | the manual's worked example | | 16 GB | 7.5 GB | `(16384 - 1024) * 0.5` | | 64 GB | 31.5 GB | `(65536 - 1024) * 0.5` = 32256 MB | Two details make this worth reading in the code rather than repeating from memory: - The option's help text says the cache "defaults to 1/2 of physical RAM". That is loose: on any host above the floor, the real value is 512 MB less than half. - `memSizeMB` is the RAM the server believes it has. The manual says the `hostInfo.system.memLimitMB` value, not the total system memory, is what the calculation uses, which matters inside a container. ## What the setting does not cover **`cacheSizeGB` is not a limit on `mongod`'s memory.** It bounds one area. Memory outside it includes: - connection and operation memory; - index builds, which the manual states are separate, with their own `maxIndexBuildMemoryUsageMegabytes` limit; - a separate **spill instance**, when one is present, which has its own small cache: `spillWiredTigerCacheSizePercentage` defaults to 2.5% of system memory, bounded by 100 MB and 1000 MB; - the **filesystem cache**, which belongs to the operating system rather than to `mongod` and uses whatever RAM is free. The RAM the default leaves over is therefore not wasted. The operating system uses it to keep data files in memory, and a read that misses the internal cache can often be served from there without touching the disk. It is also **a ceiling, not a reservation**. WiredTiger reads pages into the cache on demand, so a freshly started `mongod` holds little, and `bytes currently in the cache` grows towards the configured maximum as the workload touches data. A low figure right after a restart says nothing about whether the size is right. ## Setting it and checking it 1. **Leave the default unless you have a reason.** The manual's guidance is to avoid raising the cache above its default value. 2. **Lower it when something else needs the RAM**, such as a second process on the host. The default assumes one `mongod` per machine and knows nothing about your neighbours. 3. **Stay inside the valid range.** The option's validator accepts 0.25 to 10000. The manual prints the lower bound as 0.256 GB; the code's floor is 256 MB, which is 0.25 GB in 1024-based units. 4. **Restart and verify.** It is a startup option. Read the effective value back from `serverStatus`. A value above 80% of the RAM the server sees is not rejected: `mongod` starts and logs a startup warning saying the cache is more than 80% of available RAM. ```javascript db.serverStatus().wiredTiger.cache["maximum bytes configured"] ``` The field is in bytes. On a 64 GB host running the default it reads about 31.5 GB, and a value that surprises you is usually the first clue that the server is seeing a different amount of memory from the one you assumed.

  • Can the WiredTiger cache size be changed without restarting mongod?
    `cacheSizeGB` is read at startup, so the supported route is a restart, usually rolling through a replica set. WiredTiger itself can reconfigure `cache_size` on a live connection, and `mongod` exposes that through the `wiredTigerEngineRuntimeConfig` parameter, but the manual warns against changing it unless MongoDB engineers direct you to.
  • Why does the default subtract 1 GB before halving rather than simply taking half of RAM?
    The code comment states the rule, a minimum of 256 MB and otherwise 50% of available memory over 1 GB, without giving a reason. The practical effect is that small hosts keep proportionally more for everything else: a 2 GB host gives the cache a quarter of its RAM, not half. On big hosts the difference is only 512 MB.

  • The default WiredTiger cache is exactly half of physical RAM on every host.
  • cacheSizeGB caps all the memory a mongod process can use.
  • Each database on a mongod gets its own slice of the WiredTiger cache.
  • RAM left over beyond the default cache simply sits idle.
  • Setting cacheSizeGB above 80% of RAM makes mongod refuse to start.
open as a page

In WiredTiger, what are the default eviction targets and triggers, and what changes when the cache crosses each one?

level: middleimportance: must knowfreq 42%

basics

~20 s

By default, worker threads evict at 80% cache use or 5% dirty; application threads join at 95% use or 20% dirty. Updates carry their own pair, 2.5% and 10%. At 100% of the cache, operations stall.

open as a page

How should you size the WiredTiger cache for a mongod in a memory-limited container, and how do cacheSizeGB and cacheSizePct differ there?

level: middleimportance: should knowfreq 30%

basics

~20 s

Check hostInfo's memLimitMB, then set the cache explicitly below the container's limit. cacheSizeGB is a fixed size from 0.25 to 10000 GB. cacheSizePct, new in 8.2, is a fraction of memory up to 0.8 that follows a resize on restart.

open as a page

With WiredTiger, what do the internal cache and filesystem cache each hold, including index pages, and why does MongoDB's default leave room for the second?

level: middleimportance: should knowfreq 38%

basics

~20 s

WiredTiger's internal cache holds collection pages uncompressed and index pages in an in-memory form that keeps prefix compression. The OS filesystem cache holds the on-disk, compressed blocks. The default leaves RAM free so those blocks avoid disk reads.

open as a page

A mongod shares a 64 GB host with a second process, and p99 latency climbs during a bulk load while application threads do eviction: how do you diagnose it from WiredTiger's cache statistics?

level: seniorimportance: should knowfreq 35%

basics

~20 s

Compute dirty and used shares against maximum bytes configured: at 20% dirty or 95% used, application threads evict, and rising eviction counters confirm it. A write burst usually means slow storage or an over-fast load, rarely too small a cache.

open as a page

When a MongoDB deployment outgrows its WiredTiger cache, how do you choose between raising the cache, adding memory and sharding, and should two mongods ever share a host?

level: principalimportance: should knowfreq 26%

basics

~20 s

Raise the cache only when misses dominate and RAM is truly spare; add memory when the working set has outgrown the host; shard when one node's writes or data no longer fit. By default, run one mongod per host.

open as a page