skip to content

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%

answer

  1. check what the server believes first
  2. a limit in hostInfo
  3. fixed size against a share
  4. only one of the two
  5. a fraction, whatever the name says

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.

solid answer

~40 s

The default is computed from the memory the server believes it has. The manual says that is `hostInfo.system.memLimitMB`, but it also warns that WiredTiger may not account for a container's limit in certain cases and says you must set a value below the RAM available to the container. So compare `db.hostInfo().system.memLimitMB` with the limit you configured, then set exactly one option. `cacheSizeGB` is a fixed size, accepted from 0.25 to 10000. `cacheSizePct` arrived in 8.2, so 8.0 does not have it, and it follows a vertical resize at the next restart. In 9.0.4 its validator takes 0 to 0.8 and the code multiplies by it, so half is `0.5`, even though the manual words it as a percentage. Leave room for whatever else runs in the container.

code

javascript · 3 lines
javascript
const s = db.hostInfo().system;
print("memSizeMB:", s.memSizeMB, "memLimitMB:", s.memLimitMB);
print("cache bytes:", db.serverStatus().wiredTiger.cache["maximum bytes configured"]);

go deeper

for a junior

Recall that the default is based on the memory the server sees, and that a container limit may be lower than the host's RAM.

for a middle

Compare the two options precisely: their ranges, what a resize does to each, the 8.2 start of the percentage option, and that only one may be set.

for a senior

Verify instead of trusting: read memLimitMB and the configured maximum bytes, and explain why a process sized from host RAM can be killed before eviction ever helps.

for a principal

Decide a fleet rule: fixed sizes where versions are mixed, a fraction where hosts resize often, and an explicit allowance for whatever else shares the container.

## Why containers need attention The default size of WiredTiger's internal cache, the larger of 256 MB and half of (RAM minus 1 GB), is only as good as the RAM figure behind it. On a dedicated host that figure is simple. In a container, the memory the process may actually use can be far lower than what the host has. The manual makes two statements that have to be read together: - `hostInfo.system.memLimitMB` is "the memory usage limit", and it is what the WiredTiger cache calculation uses instead of the total system memory. - WiredTiger "may not account for the memory limits of the specific container in certain cases", so for a `mongod` in a container without access to all of the system's RAM, you must set the cache to a value less than the RAM available to the container. So the server tries to see the limit, but the guidance is not to depend on that. If it sizes itself from the host's RAM, the process can exceed its limit and be killed long before eviction has a reason to act. ## Check before you set 1. Read what the server believes with `db.hostInfo().system`, comparing `memSizeMB` and `memLimitMB` with the limit you gave the container. 2. Read what it did with it: `db.serverStatus().wiredTiger.cache["maximum bytes configured"]`. 3. Decide how much memory the rest of the process and any other processes in the container need. 4. Set one cache option, restart, and read the value back. ## The two options | | `cacheSizeGB` | `cacheSizePct` | |---|---|---| | Available | long-standing | since MongoDB 8.2, so not in 8.0 | | Meaning | a fixed size in gigabytes | a share of the memory the server sees | | Accepted values (validator, 9.0.4) | 0.25 to 10000 | 0 to 0.8 | | Base | none | the full figure, without subtracting 1 GB | | Lower floor in the code | 256 MB, by its validator | raised to 256 MB when the result is lower | | After a vertical resize | stays the same until you edit it | follows at the next restart | | Too large a value | starts, with a warning above 80% | refused above 0.8 | - **Only one may be set.** The option help says so, and `getMainCacheSizeMB` opens with an invariant that both are not set. - **The 80% warning is strict.** The startup warning fires when the computed cache is greater than 80% of the memory seen, so exactly 80% does not trigger it. - **`cacheSizePct` is not the default formula with a different knob.** At `0.5` on a 64 GB host it gives 32 GB, while the default gives 31.5 GB. ## A trap in the percentage option The name, the help text and the manual all say "percentage", and the manual's example says the option "cannot be set to 10" on a 2 GB host because 10% of 2 GB is under the minimum. The code at 9.0.4 disagrees on both counts: - The option's validator accepts only values from 0 to 0.8, and the code multiplies the value directly by the memory figure. So half is `0.5`, and `10` is out of range on any host. - A small result is not an error in the code. `0.1` on a 2 GB host computes 204.8 MB, which is then raised to the 256 MB floor. The source wins here, so write `0.5`, and read the effective size back from `serverStatus`. ## Choosing a value - **A container with only `mongod` in it:** once `memLimitMB` is confirmed, the default's shape, half of (limit minus 1 GB), is a good number to write down explicitly, since it leaves room for the filesystem cache and for connections. - **A shared container or tight limit:** subtract what the other processes need first, then size from what is left, and accept a smaller cache rather than risk the limit. - **A fleet that resizes often:** `cacheSizePct` saves editing a number on each resize, provided every member runs 8.2 or later. Remember the manual's advice to avoid going above the default without a reason. - **A fleet mixing 8.0 and 9.0:** use `cacheSizeGB`, because 8.0 has no `cacheSizePct`.

  • On a 64 GB host, how does cacheSizePct 0.5 compare with the default WiredTiger cache?
    It gives 32 GB against the default's 31.5 GB. The percentage path multiplies the fraction by the whole memory figure, while the default path subtracts 1 GB before halving. On a large host that difference hardly matters, but it shows they are separate code paths rather than one formula with a different setting.
  • What happens if a mongod is given both cacheSizeGB and cacheSizePct?
    The manual and the option help say only one may be provided. At 9.0.4 the option definitions declare no conflict, but `getMainCacheSizeMB` starts with an invariant that they are not both non-zero, so the server does not choose a winner. Treat it as a configuration error and set one.

  • A mongod in a container always sizes its cache correctly, so no check is needed.
  • cacheSizePct: 50 gives half of memory on MongoDB 9.0.4.
  • cacheSizePct has been available since long before MongoDB 8.0.
  • cacheSizePct: 0.5 and the default formula give identical sizes.
  • If both cache options are set, mongod simply uses the larger.

Assumes MongoDB 9.0.4; cacheSizePct arrived in 8.2, so 8.0 has only cacheSizeGB, and the fraction range is read from the 9.0.4 validator.