Dynamic bucket size cap under cache pressure
Parent: Bucket catalog memory and closure reasons · Published reference · snapshot 2026-10-24 · skill mongodb-cohort-bd6489c69c3d
↓ Facts as markdownall context files
Source-anchored research for Dynamic bucket size cap under cache pressure. 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.
Structure and components
- The minimum-size floor is version-sensitive historically: SERVER-82798 records a fix for respecting the time-series bucket minimum size and lists 7.0.4 and 7.2.0-rc0 as fix versions. The pinned implementation contains that floor. (high confidence) (verified as of 2023-11-07) [source]
How it works
- SERVER-69899 describes lowering bucket limits to target roughly half the WiredTiger cache for active buckets and avoid repeated write-through at high cardinality. This is a policy objective, not a guaranteed memory ceiling, especially when the minimum-size floor binds. (high confidence) [source]
- During insertion, after time-range and count checks, MongoDB compares the bucket’s current size plus the incoming size estimate against the effective cap. For a bucket with at least timeseriesBucketMinCount measurements, exceeding that cap returns kSize only when the effective cap equals gTimeseriesBucketMaxSize; if the cap is lower, it returns kCachePressure, even when the proposed size also exceeds the configured maximum. The rollover enum explicitly distinguishes these reasons. (high confidence) [source]
- MongoDB introduced dynamic time-series bucket sizing in 6.2 (SERVER-69899 lists fix version 6.2.0-rc0). Its purpose is to reduce write-through behavior when many active buckets would otherwise outgrow the WiredTiger cache; smaller buckets trade cache residency against disk usage and query performance. (high confidence) [source]
- SERVER-105187 describes raising timeseriesBucketMinSize as high as timeseriesBucketMaxSize to suppress ordinary dynamic bucketing and proposes making the factor of two configurable. The inspected code still hardcodes that factor. Treat this as an engineering tuning mechanism whose effects require workload validation, not a demonstrated universally beneficial setting. (high confidence) [source]
Problems, failure modes and limitations
- numBucketsClosedDueToCachePressure counts dynamic-size-limit closures. numBucketsClosedDueToSize tracks the ordinary size reason, while numBucketsClosedDueToMemoryThreshold and numBucketsArchivedDueToMemoryThreshold describe bucket-catalog memory reclamation. A cache-pressure counter alone does not prove WiredTiger cache occupancy reached a measured threshold. (high confidence) [source]
Comparisons and alternatives
- The sizing policy uses storage-cache capacity and global active-bucket cardinality. It is a workload heuristic rather than a direct measurement of current cache occupancy or eviction pressure; another collection's active buckets can affect the calculation. (high confidence) [source]
- The design explicitly trades better avoidance of repeated writes for potentially poorer disk utilization and query performance from smaller buckets. A 2023 user experiment reported severe bucket fragmentation during interleaved multi-collection loading; that report illustrates a failure case rather than a universal performance multiplier. (medium confidence) [source]
- SERVER-105187 describes increasing timeseriesBucketMinSize up to timeseriesBucketMaxSize as a way to suppress ordinary dynamic bucketing. This changes the intended cache-versus-packing tradeoff; the pinned code still applies its separate large-measurement absolute ceiling. (high confidence) [source]
Facts and statements
- At pinned MongoDB revision 35647d07, for active-bucket count N > 0 and storage-cache capacity C bytes, getCacheDerivedBucketMaxSize computes D = max(timeseriesBucketMinSize, min(floor(C / (2*N)), INT32_MAX)) and returns effective ordinary cap min(timeseriesBucketMaxSize, D) plus D. For N = 0 it returns the configured maximum and INT_MAX. The inputs are cache capacity and cardinality, not measured cache occupancy or eviction rate. (high confidence) [source]
- The minimum-count optimization can keep a bucket open beyond the ordinary effective cap to accommodate large measurements. It remains bounded by min(Bucket::kLargeMeasurementsMaxBucketSize, D); exceeding a cache-derived absolute ceiling produces kCachePressure. Thus the minimum count does not guarantee ten measurements per bucket. (high confidence) [source]
- SERVER-89233 reports pathological one-document buckets with numBucketsClosedDueToCachePressure on affected versions 7.0.4 and 7.0.5; its issue record lists fixes in 8.0.5 and 8.1.0-rc0. These are the issue’s listed versions, not an exhaustive affected-version or backport matrix. (medium confidence) (verified as of 2024-10-03) [source]
- High metadata cardinality tends to create more concurrent buckets and can therefore lower the cache-derived cap. OneUptime describes the cardinality-to-bucket-count relationship, while MongoDB's implementation and design issue establish its connection to dynamic sizing. (medium confidence) [source]
- Percona's mongodb_exporter reference documents the collstats collector and --mongodb.collstats-colls for selecting collections. These are collection-statistics collection controls, not parameters that tune MongoDB's dynamic bucket cap; the reference does not guarantee export of a particular cache-pressure metric. (low confidence) (verified as of 2026-10-20) [source]
- The active-bucket cardinality includes open and archived buckets. The sizing policy uses the global count across collections, so another collection can affect a collection’s dynamic cap. The half-cache target is a sizing heuristic, not a guarantee that all bucket-related memory stays within half the cache. (high confidence) [source]
- At revision 35647d07, timeseriesBucketMaxSize defaults to 128000 bytes, timeseriesBucketMinSize defaults to 5120 bytes, and timeseriesBucketMinCount defaults to 10. The minimum-size parameter is available at startup and runtime; the maximum-size and minimum-count parameters are startup parameters. The size floor prevents the dynamic calculation from shrinking without bound. (high confidence) [source]
- Percona mongodb_exporter provides a collstats collector and a mongodb.collstats-colls selection option. These provide an external monitoring integration for collection statistics, but its reference does not document or independently validate MongoDB’s dynamic-cap formula. (low confidence) (verified as of 2026-10-24) [source]
Children
- No children recorded.