Memcached memory utilization: bytes vs limit_maxbytes and why the global number lies

The bytes and limit_maxbytes fields from stats look like a clean fill gauge. Divide one by the other and you know how full the cache is. Many dashboards and alerts are built on exactly that ratio.

This article covers why the global ratio lies, what it actually measures, and which per-slab signals confirm real pressure. bytes includes per-item overhead and never quite reaches the ceiling, allocation happens in 1MB page jumps rather than smoothly, and the pool is partitioned into fixed-size slab classes that saturate independently. A cache at 50% global utilization can be evicting live, actively-requested data.

Treat bytes / limit_maxbytes as a coarse leading indicator, then confirm with stats slabs and stats items before acting.

What it is and why it matters

bytes reports memory used for item storage. limit_maxbytes is the configured ceiling, set by the -m flag in megabytes and reflected verbatim in stats.

Conventional thresholds:

These are reasonable as a coarse indicator. The problem is that the ratio has three structural properties that make it unreliable as a saturation signal alone, and the most important one, slab partitioning, can hide an eviction storm behind a healthy-looking 50%.

How it works

Three mechanisms make the global ratio behave differently from a naive “tank filling up” model.

Per-item overhead inflates bytes. bytes is not the sum of value payloads. It includes the key, flags, exptime, internal pointers, and slab chunk padding. The per-item overhead is the item header struct, plus the key, flags, CAS value, protocol suffix, and padding to the next chunk boundary. On a default 64-bit build, sizeof(item) is 48 bytes; verify your build with stats slabs when the exact boundary matters. A 100-byte value in a 152-byte chunk contributes 152 bytes to bytes, not 100. The effective payload capacity is lower than limit_maxbytes suggests, and bytes plateaus below the ceiling even under heavy pressure.

Allocation is page-wise, not smooth. Memory is handed out in 1MB pages. When a slab class needs more storage, memcached assigns it a full page. The counter moves in steps, not continuously. Small caches show visible stair-stepping; on large caches the granularity is invisible but the mechanism is the same. The moment-to-moment bytes value is a snapshot of a step function, not a smooth fill level.

The pool is partitioned by item size. This is the big one. At startup memcached divides the -m pool into slab classes, each handling a range of item sizes. With defaults, class 1 handles items up to 96 bytes, class 2 up to 120, and class 3 up to 152; chunk sizes are rounded to 8-byte alignment and grow by the -f factor (default 1.25). Confirm the active boundaries with stats slabs. Pages are assigned to slab classes, and each class fills independently. The global bytes is the sum across all classes. If your workload concentrates in one size class, that class fills and evicts while the others sit idle, and the global ratio reports a number that has nothing to do with the pressure the hot class is under.

This is the slab imbalance trap, and it is the single most underdiagnosed memcached problem. You can be evicting actively-used items at 50% global utilization.

flowchart TD
    L["limit_maxbytes
set via -m"] --> P["divided into 1MB pages"]
    P --> S1["slab class A
small chunks"]
    P --> S2["slab class B
medium chunks"]
    P --> S3["slab class C
large chunks"]
    S1 --> U1["100% used
evicting live items"]
    S2 --> U2["100% used
evicting live items"]
    S3 --> U3["25% used
idle pages"]
    U1 --> B["bytes = sum of all classes"]
    U2 --> B
    U3 --> B
    B --> R["global ratio ~55%
reads as healthy"]
    R --> X["reality: A and B are saturated"]

The diagram shows the lie in one frame: three slab classes, two saturated and evicting, one idle. The global ratio sums them into a number that looks comfortable, and the operator never opens stats slabs to see the per-class breakdown.

What limit_maxbytes actually is

limit_maxbytes is the -m value converted to bytes. It is a ceiling on item storage memory, not on total process memory. Memcached uses additional memory for the hash table, connection buffers, thread stacks, and internal structures. Process RSS will exceed limit_maxbytes in steady state. The -m flag documentation is explicit that it is not a hard global limit on the process.

limit_maxbytes can be changed at runtime with the cache_memlimit command. It takes megabytes, not bytes. Passing a byte value corrupts the limit_maxbytes figure. If limit_maxbytes moves unexpectedly between samples, someone issued cache_memlimit, or the process restarted with a different -m. Lowering limit_maxbytes below current bytes is disruptive: it does not guarantee memory is returned to the OS, the allocator and kernel decide that, and active eviction may spike in the slab classes that hold the freed pages. Do not run it against a production cache without a drain plan.

Where it shows up in production

Three recurring scenarios.

Slab calcification after a deploy. An application changes its serialization format or adds fields, shifting the item size distribution. Items that used to be 180 bytes are now 280 bytes, landing in a different slab class. The old class still holds its pages, assigned at warmup, serving a workload that no longer exists. The new class is undersized and evicting. Global memory reads 60%. Operators add memory and watch it flow to the wrong classes. The fix is per-slab inspection and slab_automove, not more RAM.

Warmup slab allocation mismatch. If warmup traffic has a different item-size distribution than steady-state, pages get assigned to the wrong classes during the initial fill. The cache enters steady-state already calcified. This is why a freshly restarted cache can show evictions at 40% global utilization within minutes of coming up.

The “we have plenty of memory” false comfort. A team sizes their cache to 70% global utilization and sets an alert at 90%. They never get paged. Meanwhile one slab class has been evicting active items for weeks, hit ratio for that size range is degraded, and nobody looks because the global gauge never crossed the line.

The common thread: the global ratio answers “how full is the pool?” when the question you actually need is “is any slab class under pressure?”

Tradeoffs and common misuses

Alerting on global ratio alone. A threshold on bytes / limit_maxbytes at 0.9 will catch genuine global undersizing, where the whole pool is full. It will not catch slab imbalance, which is the more common and more damaging failure mode at moderate utilization. Pair the global alert with per-slab eviction monitoring or you will miss the case that matters.

Assuming bytes can reach limit_maxbytes. It cannot, because of per-item overhead and chunk padding. An alert that fires only when bytes gets within a hair of limit_maxbytes will never fire. The practical ceiling is meaningfully below the configured one.

Reading a sudden bytes drop as memory pressure. A sudden drop means items disappeared: a flush_all, a mass TTL expiration, or a restart. It is not pressure, it is evacuation. Check cmd_flush, uptime, and curr_items to classify the event. After a flush, bytes can lag because flushed item memory is reclaimed gradually, mainly as it is reused or reclaimed by the crawler.

Treating cache_memlimit as a pressure-relief knob. Raising limit_maxbytes at runtime adds headroom globally, but the new memory still has to be claimed by slab classes as pages. If the pressure is in one saturated class and slab_automove is off, raising the limit may not help that class at all. Confirm where the pressure is before adjusting the ceiling.

Trusting stats sizes blindly. stats sizes gives an item-size histogram that is exactly what you need for slab analysis, but on versions before 1.4.27 it locks the entire cache while scanning. From 1.4.27 onward it is disabled by default and requires -o track_sizes at startup, returning sizes_status disabled otherwise. Know your version before running it in production.

Signals to watch in production

The global ratio is the first row. Every other row is what you need to confirm or refute what the global ratio is telling you.

How Netdata helps

Netdata surfaces the global ratio and the per-slab breakdown in the same view, which is the correlation that matters for this problem.

• The memcached collector pulls bytes and limit_maxbytes into a per-second utilization chart, so the coarse fill gauge updates frequently enough to catch step-changes from page allocation and sudden drops from flushes.
• Per-slab charts for used_chunks, free_chunks, and eviction counts let you see which class is saturated without dropping to a shell and running stats slabs manually.
• Eviction rate and evicted_time are tracked alongside utilization, so you can distinguish “full and evicting cold items” from “full and evicting live data” without correlating across tools.
• ML anomaly detection flags sudden drops in bytes from flushes, restarts, or mass expiry, and unexpected shifts in the bytes / limit_maxbytes ratio including changes introduced by cache_memlimit.
• The cmd_flush counter is tracked as a discrete event, so a sudden bytes drop is immediately attributable to a flush rather than guessed at.
• Alerting can be layered: a global ratio alert catches whole-pool saturation, while per-slab eviction alerts catch the imbalance case the global ratio hides.

Related guides

• Memcached evicted_unfetched and expired_unfetched: caching data nobody ever reads
• Memcached cas_badval climbing: check-and-set contention and lost updates
• Memcached connection refused: telling a dead process from a hung or full one
• Memcached evicted_time low: distinguishing healthy turnover from cache thrash
• Memcached eviction cascade: when a full cache overloads the backend
• Memcached evictions climbing: the cache is full and discarding live data
• Memcached high miss rate: separating cold start, new key patterns, and memory pressure
• How Memcached actually works in production: a mental model for operators
• Memcached incr/decr misses: evicted counters that silently break rate limiters and locks
• Memcached hit ratio dropping: reading get_hits, get_misses, and cache effectiveness
• Memcached monitoring checklist: the signals every production cache needs
• Memcached monitoring maturity model: from survival to expert