Session catalog partitioning and contention diagnostics
Parent: MongoDB Performance Troubleshooting · Published reference · snapshot 2026-10-29
↓ Facts as markdownall context files
Source-anchored research for Session catalog partitioning and contention diagnostics. 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
- MongoDB documents sessionCatalogPartitions as new in 9.0.1 for mongod; partitioning targets session-catalog lock contention when many sessions are present. (medium confidence) (verified as of 2026-10-14) [source]
- Distinguish partition-mutex contention from session-checkout serialization. OperationContextSession may wait because only one user can check out a session at a time; increasing partitions does not remove that exclusivity. SERVER-37499 describes a historical same-session exchange deadlock and explicitly says the scenario had not been observed. (medium confidence) (verified as of 2026-10-27) [source]
- SERVER-66960 records a historical optimization that avoids re-locking the session catalog when refreshing the highest child txnNumber, by caching it on the participant session. Its listed fixes are 6.0.0-rc9 and 6.1.0-rc0; it is separate from the later partition-count parameter. (low confidence) [source]
Problems, failure modes and limitations
- SERVER-37499 is a potential-deadlock analysis, not an observed incident: the authors explicitly say they had not observed the scenario. It affects 4.1.3 and lists fix version 4.1.7, so it cannot establish a current 9.0 partitioning defect. (low confidence) [source]
Comparisons and alternatives
- MongoDB explicitly recommends retaining the default sessionCatalogPartitions value. The example mongod --setParameter sessionCatalogPartitions=16 illustrates syntax rather than a workload-specific tuning recommendation. (low confidence) (verified as of 2026-10-14) [source]
- Tallent, Mellor-Crummey and Porterfield show why attributing lock-wait idleness only to waiting call paths can be uninformative. Their proposed method uses lock-associated data to attribute spinning-thread idleness to the lock holder and its calling context. They evaluate MADNESS, UTS and SSCA#2 rather than MongoDB. (low confidence) [source]
Facts and statements
- The default value 0 selects twice the CPU cores available to mongod, capped at 64 partitions. A positive explicit value supplies the partition count directly; 64 is the automatic-selection cap, not a documented cap on explicit settings. (medium confidence) (verified as of 2026-10-14) [source]
- MongoDB recommends keeping the default. sessionCatalogPartitions is startup-only, so the documented example mongod --setParameter sessionCatalogPartitions=16 is a startup configuration example, not a runtime tuning instruction. (low confidence) (verified as of 2026-10-14) [source]
- The master-branch SessionCatalog implementation assigns sessions by the parent logical-session ID hash. Each partition owns a session map and mutex; parent and child sessions remain in one partition. (low confidence) (verified as of 2026-10-27) [source]
- sessionCatalogPartitions is startup-only. The inspected implementation constructs the partition vector once and never resizes it, so the parameter is not a runtime contention-control knob. (medium confidence) (verified as of 2026-10-14) [source]
- The inspected master constructor registers partition mutexes under sessionCatalogMutex with partition_N labels. Combined with the documented serverStatus lockContentionMetrics interface, this supports checking that tag on a build containing this instrumentation; it does not establish availability in every release. (medium confidence) (verified as of 2026-10-27) [source]
- serverStatus excludes lockContentionMetrics by default. Request db.runCommand({serverStatus:1,lockContentionMetrics:1}) for aggregate tags or {serverStatus:1,lockContentionMetrics:{listAll:1}} for individual mutexes. total counts acquisitions, contentions counts acquisitions that waited, and waitCycles measures waiting in CPU cycles, not microseconds. (low confidence) (verified as of 2026-10-14) [source]
- logicalSessionRecordCache.sessionCatalogSize reports catalog population, including cached transaction or retryable-write state on mongod. It is not a direct measure of mutex contention or of simultaneously executing requests; correlate population with contention counters and operation latency. (low confidence) (verified as of 2026-10-14) [source]
- For blocked-thread investigation, off-CPU stack analysis complements CPU profiling, which misses time asleep waiting for locks. Off-CPU duration can also include scheduler delay after wakeup, and tracing overhead can alter the workload. This is general diagnostic methodology, not proof of a MongoDB session-catalog bottleneck. (low confidence) [source]
Children
- No children recorded.