$ guides / uwsgi / uwsgi-rss-vs-vsz ▌

Operations Guides

uWSGI RSS vs VSZ: reading worker memory without being fooled by shared pages

You look at your uWSGI stats and see 8 workers each reporting 500 MB of RSS. The host has 4 GB of RAM. By the math, you should be deep into swap, but vmstat shows zero swap activity and response times are fine.

The gap is copy-on-write (COW) sharing. uWSGI’s default model loads the application once in the master process, then forks workers that inherit the master’s memory. Linux marks those inherited pages as shared and read-only. As long as workers do not write to them, the pages stay shared across all workers. But Linux RSS counts every shared page fully for every process that maps it. Sum worker RSS across 8 workers and you may overstate real memory consumption by 2-5x.

What RSS and VSZ actually measure

RSS (Resident Set Size) is the number of physical pages a process has mapped into RAM. It includes private anonymous pages (heap, stack), private file-backed pages (executable text written via COW), and shared pages (shared libraries, COW pages inherited from fork). On Linux, uWSGI reads this from /proc/<pid>/stat and reports it in the stats server as workers[].rss (integer, bytes).

VSZ (Virtual Set Size) is the total virtual address space the process has allocated. It includes everything in RSS plus mapped-but-not-touched memory, mmap’d files, pre-allocated arenas, and reserved-but-unused address ranges. uWSGI reports it as workers[].vsz (integer, bytes).

Both fields appear in the stats server JSON. Both require --memory-report to be enabled; without it, they report zero. Verified in the uWSGI source: the rss/vsz values are only populated when --memory-report (or force_get_memusage) is enabled, so the fields stay at 0 otherwise.

You can also access these values outside the stats server:

# Per-worker RSS and VSZ from uWSGI stats server
uwsgi --connect-and-read 127.0.0.1:9191 | \
  jq '.workers[] | select(.pid > 0) | {id: .id, rss_mb: (.rss / 1048576), vsz_mb: (.vsz / 1048576)}'

# Cross-check against the kernel for the same PID
grep -E '^(VmRSS|VmSize):' /proc/<pid>/status

# Log format variables available since uWSGI 1.4.6: %(rss), %(vsz), %(rssM), %(vszM)

In uWSGI’s default pre-fork model, the master loads and initializes the application, then calls fork() to create each worker. The kernel does not copy the master’s memory pages into each child. It maps the same physical pages into both parent and child with copy-on-write protection. When a worker writes to a page, the kernel duplicates it. Pages that are only read (most application code, loaded libraries, initialized data structures) stay shared indefinitely.

The problem is how Linux accounts for these shared pages in RSS:

flowchart TD
    A["Master loads app
into memory"] -->|"fork + COW"| B["Worker 1"]
    A -->|"fork + COW"| C["Worker 2"]
    A -->|"fork + COW"| D["Worker 3"]
    B --> E["RSS counts shared
pages fully per worker"]
    C --> E
    D --> E
    E --> F["sum(RSS) overstates
real memory by 2-5x"]
    E --> G["PSS divides shared pages
by number of sharers"]

Each worker’s RSS includes the full size of every shared page. If the master loaded 200 MB of application code and libraries, and each worker added 50 MB of private state, each worker reports approximately 250 MB of RSS. With 8 workers, sum(RSS) = 2000 MB. Actual physical memory consumed: 200 MB (shared, counted once) plus 8 x 50 MB (private per worker) = 600 MB. The RSS sum overstates real usage by more than 3x.

This is not a uWSGI bug. It is how the Linux kernel reports RSS for any forked process. Every tool that reads RSS (ps, top, /proc/<pid>/status) has the same limitation.

Known discrepancy: stats server RSS vs kernel RSS

There is a documented divergence (uWSGI issue #1989: “htop/top/ps memory not equal to uwsgitop stats”) where the stats server RSS differed sharply from ps / /proc/<pid>/status for the same PID; the root cause was never definitively resolved, and the stats server only samples RSS at request completion (and only with --memory-report). If you see large divergences between the stats server value and the kernel value, trust /proc/<pid>/status (VmRSS) over the stats server number.

VSZ is not memory used

VSZ measures virtual address space, not physical memory consumption. It includes:

Mapped shared libraries that may only have a few pages resident
Pre-allocated heap arenas (Python’s pymalloc requests large arenas upfront)
Memory-mapped files that may never be read into RAM
Thread stacks (each thread maps a fixed-size stack region)

A Python uWSGI worker reporting 4 GB VSZ with 200 MB RSS is normal. The 3.8 GB gap is address space that has been mapped or reserved but never touched. It consumes no physical RAM.

VSZ becomes worth watching only when it approaches per-process virtual memory limits (ulimit -v), or when it grows without bound alongside file descriptor count increases (a sign of mmap’d file leaks). In those cases, VSZ growth is a symptom of a resource leak, not a memory pressure indicator.

The uWSGI option --reload-on-as triggers worker recycling based on address space size. This is rarely the right tool for memory management. Use --reload-on-rss instead, which at least measures physical pages, even though it overstates due to COW.

How lazy-apps changes the picture

The lazy-apps directive changes the fork model. Instead of loading the application once in the master and sharing pages via COW, each worker loads the application independently after being forked.

What this means in practice:

No COW sharing: Each worker’s memory pages are private from the start.
Higher baseline RSS: Workers start with the full memory footprint of loading the application. With 8 workers and a 200 MB application, baseline memory is closer to 8 x 200 MB instead of 200 MB plus shared overhead.
RSS is closer to reality: Because pages are not shared, per-worker RSS approximates actual unique memory consumption. sum(RSS) is a more reliable capacity metric under lazy-apps.
Slower startup: Each worker goes through application initialization independently. Startup time multiplies by worker count if they initialize sequentially.

The tradeoff is memory cost for safety. Some libraries (database drivers, ML frameworks, C extensions with global state) are not fork-safe and corrupt shared state when multiple processes write to the same COW page simultaneously. lazy-apps avoids this by giving each worker its own clean copy.

If you are running lazy-apps, RSS-based thresholds like --reload-on-rss are more meaningful because each worker’s RSS reflects its actual footprint. If you are running default pre-fork, RSS overstates per-worker cost due to sharing.

Getting accurate per-worker memory with PSS

Proportional Set Size (PSS) is the correct metric for understanding actual memory consumption in a forked process group. PSS divides the size of each shared page by the number of processes that share it. A 4 KB page shared by 4 workers contributes 1 KB to each worker’s PSS. Summing PSS across all workers gives you the actual unique physical memory consumed.

Reading PSS from the kernel

# Read PSS for a single worker PID
# smaps_rollup is available since Linux 4.14 (2017)
grep -E '^(Pss|Rss|Size):' /proc/<pid>/smaps_rollup

# Sum PSS across all workers of a uWSGI master
MASTER_PID=$(cat /tmp/uwsgi.pid)
for pid in $(pgrep -P "$MASTER_PID"); do
  grep '^Pss:' "/proc/$pid/smaps_rollup"
done | awk '{s+=$2} END {printf "Total worker PSS: %.0f MB\n", s/1024}'

Reading smaps_rollup is more expensive than reading /proc/<pid>/stat (the kernel must walk the page tables to compute proportional accounting). Do not poll it every second. A 10-60 second interval is sufficient for capacity monitoring.

PSS in uWSGI itself

uWSGI 2.1-dev adds a pss field to the stats server, providing per-worker PSS without external tools. The --reload-on-pss option triggers worker recycling based on PSS instead of RSS. Verified: both the --reload-on-pss option and the pss/uss stats fields exist only in the 2.1-dev (master) line; stable 2.0.x up to 2.0.31 does not ship them.

PSS/USS support was merged into the uWSGI master branch in 2017 but may not be present in all distributed builds. Pip-installed uWSGI has been reported to be missing --reload-on-pss (issue #2237, verified: a source build exposed the flag while the pip-installed binary did not). If you need PSS-based recycling and the option is unavailable in your build, use kernel-level PSS from /proc/<pid>/smaps_rollup combined with external monitoring that triggers uWSGI reloads.

Where this matters in production

Capacity planning: Do not size hosts based on sum(worker_rss). Use PSS-based totals or subtract the estimated shared footprint. Keep total worker RSS (adjusted for shared pages) below 70% of available system memory.

Setting reload-on-rss thresholds: This threshold operates on the RSS value, which includes shared pages. If you set --reload-on-rss 512 and your shared footprint is 200 MB, workers start recycling when their private memory reaches approximately 312 MB. This may trigger earlier than you intend. Understand the baseline before setting the number.

OOM-killer behavior: The Linux OOM-killer selects victims based on a scoring that includes RSS. In a pre-fork uWSGI setup, all workers have inflated RSS due to shared pages. The OOM-killer may target workers somewhat arbitrarily among the high-RSS candidates. After killing one worker, the respawned worker quickly shares the same pages and the cycle repeats. Monitor dmesg for OOM events correlated with worker respawns.

Memory leak detection: Track RSS growth rate per worker over time, not just absolute values. A consistent positive slope across all workers indicates a leak. Python and Ruby memory allocators rarely return freed memory to the OS, so RSS may plateau at a high-water mark even after the leak source is fixed. This fragmentation plateau is operationally indistinguishable from a slow leak. Workers recycled by max-requests show a sawtooth RSS pattern, which is healthy.

Single-worker poisoning: If one worker’s RSS is much larger than the others (more than 2x the youngest, most recently respawned worker), the issue is request-specific, not systemic. A pathological request path (unbounded query results, ReDoS, large payload held in memory) is the likely cause. The outlier RSS pinpoints which worker to investigate.

Signals to watch in production

Signal	Why it matters	Warning sign
Per-worker RSS (stats server or /proc)	Tracks memory growth per worker; catches leaks and cache bloat	Sustained positive slope over hours across all workers
PSS sum across workers (smaps_rollup)	Accurate total physical memory consumed by the worker pool	Approaching 70% of system RAM
RSS divergence between workers	One worker much larger than others indicates request-specific memory issue	Any worker RSS greater than 2x the youngest respawned worker
RSS vs VSZ ratio	Large gap is normal; shrinking gap with growing RSS means real allocation growth	VSZ stable but RSS climbing toward VSZ
Respawn rate correlated with RSS	Distinguishes memory-triggered recycling from crashes	Respawns tracking harakiri count 1:1 means crashes, not memory
Swap usage (host-level)	Indicates real memory pressure regardless of RSS accounting	Any nonzero si/so in vmstat

How Netdata helps

Netdata’s per-process monitoring and host-level metrics help you reason about uWSGI memory without falling into the RSS sum trap:

Per-process RSS from the kernel: Netdata reads RSS directly from /proc, giving you per-worker RSS at per-second resolution. You see the sawtooth pattern of max-requests recycling immediately, without polling the stats server.
System-level memory pressure: Netdata tracks available RAM, swap usage, and page fault rates at the host level. These signals tell you whether inflated RSS numbers actually translate into memory pressure, cutting through the COW accounting noise.
OOM-killer correlation: When Netdata’s process monitoring shows a worker disappearing and respawning, you can correlate that exact moment with system-level memory events to determine whether the OOM-killer was involved.
Anomaly detection on RSS trends: Netdata’s anomaly detection flags unusual RSS growth patterns, helping you distinguish a slow leak from normal allocator fragmentation without static thresholds.
Correlation with worker busy ratio and response time: Memory pressure often manifests as GC pauses or swapping before it shows up as an OOM kill. Correlating RSS trends with response time degradation gives earlier warning than RSS alone.