$ guides / uwsgi ▌

UWSGI · OPERATIONS PLAYBOOK

uWSGI's one hard limit: a fixed pool of workers, a kernel queue behind them, and a watchdog that kills what hangs

A pre-fork application server where a master process runs a pool of workers, each a full copy of your app. Requests wait in the kernel's listen backlog until a worker is free, a harakiri timer kills anything that runs too long, and a bad reload can leave zero workers alive. We trace how that behaves under load, where it turns from queuing into dropped connections, and what to do when it does.

> Start with the monitoring checklist → # Jump to the full guide list

uWSGI's defaults get you serving quickly, then hand you a set of cliff-edges that most teams only meet during an incident.

The defaults work. Until every worker is busy at once, new connections pile into the kernel listen backlog, and when that fills the kernel drops them silently — no uWSGI log, no error counter, just clients getting connection refused. Until a downstream dependency hangs, every request blows past the harakiri timeout, and the pool spends all its time being killed and respawned instead of serving. Until a worker leaks memory until the OOM killer takes it. Until a deploy ships broken code, the reload kills the old workers, the new ones fail to start, and the pool sits at zero. Until ulimit -n is hit and accept() starts failing with no signal at all.

These guides are written for engineers who already run uWSGI in production, not for people wiring up their first .ini file. The goal is the mental model of how the server actually behaves under load, the failure patterns that keep recurring, the signals that catch them before they page anyone — including the ones uWSGI reports badly, like the broken listen_queue field — and the runbooks you wish someone had handed you before your last incident.

How uWSGI actually runs in production

uWSGI is not just 'the thing behind nginx'. It is a master process supervising a pool of worker processes, each a full copy of your application, fed by a single kernel listen queue and policed by a per-request watchdog. Most production failures live between these layers — in the queue, the watchdog, or the reload — not inside your application code.

reverse proxy / clients

nginx or HAProxy usually sits in front, buffering requests and holding its own upstream connection pool and <code>uwsgi_read_timeout</code>. Direct exposure means the kernel listen queue is your only buffer. The proxy's timeout and uWSGI's harakiri must be reconciled, or you get 502s when a worker is killed mid-response and 504s when the proxy gives up first.

PROXY

socket + listen queue (backlog)

Requests arrive on a UNIX or TCP socket; the kernel holds them in a listen backlog until a worker accepts. This is the single most important saturation point — when it fills, connections are dropped silently. Its real size is <code>min(--listen, net.core.somaxconn)</code>, and uWSGI's own <code>listen_queue</code> stat is unreliable on Linux.

SOCKET

master process

Never serves requests. It forks and respawns workers, runs the <code>harakiri</code> per-request watchdog, drives reloads, and serves the stats endpoint. It stays alive and responsive even when every worker is stuck — which is exactly why a master or stats health check lies about user-facing availability.

MASTER

worker processes

The pool that does the work. Each is a full copy of the app cycling <code>idle → accepting → busy → idle</code>. Worker count is your hard concurrency limit in pre-fork; a worker stuck in <code>busy</code> is one slot gone until harakiri reaps it. The <code>cheaper</code> subsystem scales the count at runtime, so the number is not fixed.

WORKER

threads / async cores

Inside a worker, threads or gevent/asyncio cores add concurrency. Threads share the GIL, so CPU-bound Python is serialised no matter how many you add; async multiplexes many I/O-bound requests on one event loop. This layer changes what 'busy' means, and is where per-core <code>in_request</code> becomes the real concurrency signal.

CORE

application (WSGI callable)

Your code and its downstream calls — databases, caches, external APIs. Almost every latency and harakiri incident traces to something here — a slow query, an exhausted connection pool, a hanging DNS lookup — not to uWSGI itself. Unhandled exceptions that reach uWSGI increment the exception counter.

APP

subsystems (spooler, cache, mules)

Optional shared machinery: the spooler (on-disk deferred jobs), the in-process cache, mules (background workers), and in Emperor mode a vassal per config file. They compete with request workers for CPU and memory, and each fails independently of the request path.

SUBSYS

OS resources

Memory (per-worker RSS, inflated by copy-on-write sharing), file descriptors (<code>ulimit -n</code>), and CPU. Each is a cliff, not a slope — memory is fine until it swaps, descriptors are fine until <code>EMFILE</code>, and neither is fully visible from uWSGI's own stats.

Why this matters: 'uWSGI is slow' or 'the site is down' can come from a full listen backlog dropping connections, every worker stuck on a slow dependency, a harakiri death spiral, a reload that left zero workers, a worker leaking into the OOM killer, or file descriptor exhaustion. The symptom rhymes but each layer has a different signal — and a different fix.

The failures you'll actually see

Most uWSGI incidents fall into a small set of recurring patterns. Recognise the shape, and triage gets dramatically faster.

CRITICAL

The silent outage: worker pool starvation

Every worker is stuck busy on slow or hanging requests, new connections pile into the kernel backlog, and once it fills the kernel drops them. The master and stats server stay responsive, so PID and stats health checks keep passing while real traffic gets nothing. From the outside the app looks up; for users it is down.

Worker busy ratio at 100% of non-cheaped workers, sustained
Listen queue (via ss) growing; TcpExtListenOverflows incrementing
Throughput collapsing while incoming traffic is unchanged
Busy workers all on one URI (a bad endpoint) or many (systemic)

Investigate →

CRITICAL

The harakiri death spiral

A downstream dependency hangs, so every request runs past the harakiri timeout, the master SIGKILLs the worker, respawns it, and it immediately accepts another doomed request. Respawns track harakiri kills almost one-to-one, throughput falls to near zero, and CPU burns on fork and startup while nothing gets served.

harakiri_count delta rising across all workers (HARAKIRI ON WORKER in logs)
respawn_count delta tracking the harakiri delta ~1:1
Worker busy ratio at ~100%, throughput near zero
All workers timing out on the same downstream call

Investigate →

CRITICAL

The listen queue overflow

The kernel listen backlog fills and connections are dropped with zero visibility — no uWSGI log line, no working error counter. uWSGI's own listen_queue and load fields read 0 regardless, so unless you measure the backlog externally you are blind to an active outage.

TcpExtListenOverflows / TcpExtListenDrops rate of change non-zero
ss Recv-Q on the listen socket sustained above zero
Clients or nginx reporting connection refused / TCP RST
uWSGI listen_queue reported as 0 despite the drops

Investigate →

CRITICAL

The reload blackout

A graceful reload killed the old workers, but the newly deployed code has a fatal import, config, or migration error, so the master spawns workers that die on startup and respawns them in a tight loop. Zero accepting workers, throughput at zero, respawn_count climbing — the deploy is the outage.

Zero workers with pid>0, accepting==1, status not cheap, for >60s
respawn_count rising / last_spawn timestamps churning
Import or startup errors in the application log
Outage begins exactly at a deploy or config change

Investigate →

ACTIVE

The memory leak and OOM spiral

Per-worker RSS grows over hours or days — a real leak, or Python allocator fragmentation that is operationally identical — the host starts swapping, and the OOM killer takes the largest worker, which respawns and grows back. Performance degrades slowly, then cliff-edges into cascading timeouts once swap engages.

Per-worker RSS trending up across all workers
Swap activity (si/so) climbing; dmesg shows oom-killer entries
Workers respawning without harakiri (signal 9 kills)
Latency fine after a restart, degrading again on the same cycle

Investigate →

IMMINENT

File descriptor exhaustion

Connections, sockets, logs, and everything the app opens each cost a file descriptor. At ulimit -n, accept() and open() fail with EMFILE — new connections rejected, logging broken, exceptions cascading — with no uWSGI-level signal. It is invisible in uWSGI stats and often misread as a disk or network fault.

'Too many open files' / EMFILE in application or uWSGI logs
Per-worker fd count (ls /proc/<pid>/fd) approaching the soft limit
New connections failing while workers otherwise look healthy
fd count climbing steadily over time (a descriptor leak)

Investigate →

Choosing a tool

Best uWSGI Monitoring Tools: 10 Ranked (2026)

A ranked review of the tools teams actually shortlist here, what each one is genuinely good at, and how the pricing behaves as you scale.

Read the buyer's guide →

uWSGI monitoring maturity levels

uWSGI observability works in four practical levels. Each is a complete operation, not a stepping stone. Pick the level that matches how much your app server matters. Most production deployments should land at the second level.

Level 1: Survival

Know that something is wrong

Survival monitoring is the floor. With these signals you can answer one question: is uWSGI alive and serving? You will not learn what broke, but you will learn that something broke — ideally before users do. Enough for a dev box or a non-critical internal app.

Master process alive kill -0 on the pidfile PID, not just that the file exists.
At least one worker accepting A worker with pid>0 and accepting==1; zero means nothing is served.
Request throughput non-zero During expected traffic hours, is the requests counter moving at all?
Host memory and CPU The blunt backstop for leaks and saturation before uWSGI-level signals.

Level 2: Operational

Diagnose most incidents on your own

Operational monitoring is what most production deployments should target. Survival says something is wrong; this says what. It covers the failure modes that actually take uWSGI down: starvation, stuck workers, memory leaks, and silently dropped connections. A professional should be embarrassed to be missing any of these.

Worker busy ratio Your primary utilisation signal; 100% means the backlog is filling.
Harakiri rate (delta) Requests hanging past the timeout; track the delta, the counter never resets.
Respawn rate (delta) Churn; subtract harakiri to separate crashes from max-requests recycling.
Per-worker RSS Growth across all workers is the leak signature; one outlier is request-specific.
Average response time (avg_rt) Trend only — a short EMA, not an SLI; watch it approach harakiri.
Exception rate (delta) Unhandled errors reaching uWSGI; a ratio to requests is more stable.
Listen queue (external) + overflows ss Recv-Q and TcpExtListenOverflows — the uWSGI field is broken.

Level 3: Mature

Catch problems before they become incidents

Mature monitoring catches problems before they page anyone. A single stuck worker hiding in the average, RSS creeping worker by worker, a spooler falling behind, a vassal quietly dead. None of these page you on day one; they become the incident on day thirty.

Per-worker request distribution One worker frozen while others progress = stuck; uneven load = accept imbalance.
Per-worker RSS growth rate The slope, not the point value — runway to the OOM cliff.
Currently-serving URI on busy workers During starvation this names the bottleneck endpoint immediately.
Worker running_time running_time/requests is the true per-request time; utilisation per worker.
Spooler depth and oldest-task age Deferred work backing up or a stuck spooler (if configured).
Kernel TcpExtListenOverflows/Drops Proof connections are being dropped when uWSGI cannot tell you.
Per-worker file descriptor count OS-level; the only warning before EMFILE.
Emperor / vassal status Each vassal independently — emperor health is not vassal health.

Level 4: Expert

Reactive instrumentation after real incidents

Expert signals join your stack the day after a specific incident proved you needed them. Per-endpoint timeouts, worker age skew, connection-pool correlation, copy-on-write divergence. Most teams never need all of them — add the ones your incident history demands.

Per-endpoint harakiri rate Which routes time out, not just that timeouts happen.
Worker age distribution Asymmetric recycling — one slot doing all the churn.
Downstream connection-pool use Correlated with busy ratio; the usual real root cause.
PSS per worker over time Copy-on-write divergence and true per-worker memory vs inflated RSS.
Page fault / swap rate vs latency pgmajfault correlated with the response-time cliff.
CPU time vs wall time per worker Separates CPU-bound from I/O-bound stalls.
Per-core in_request (threads/async) True concurrency in threaded and gevent modes where busy ratio lies.
Stats exposure / config drift Not a runtime metric — an audit: localhost bind, socket perms, config integrity.

Operating mistakes worth avoiding

The traps uWSGI teams keep falling into. Each has a clear, well-known fix. Most teams only learn it after an incident.

Not monitoring the listen queue at all

The number-one gap. Teams watch busy count and response time but never the kernel backlog, so when it overflows and connections are dropped there is no log, no counter, no alert — just customers reporting <code>connection refused</code> with nothing in any log. Monitor <code>ss</code> Recv-Q and <code>TcpExtListenOverflows</code>, and alert on any non-zero overflow rate.

Using the master PID or stats endpoint as a health check

The master and stats server stay responsive during total worker starvation, so a check that pings either returns 200 while 100% of real requests are dropped, and the load balancer keeps sending traffic to a dead node. Health checks must go through the worker pool and feel the same queuing as real requests.

Not configuring harakiri

Default uWSGI has no request timeout, so a single stuck request holds a worker slot forever; stuck workers accumulate silently until the pool is exhausted and only a manual restart recovers. An always-zero <code>harakiri_count</code> is a blind spot, not health. Set <code>harakiri</code> to about 2-3x the longest legitimate request and add <code>harakiri-verbose</code>.

Trusting the listen_queue and load stats fields

Both are broken on standard Linux and almost always read 0 regardless of the real backlog; <code>load</code> is literally identical to <code>listen_queue</code> (a source TODO admits it is not latency), and <code>listen_queue_errors</code> is dead code that never increments. Alerting on any of them gives false safety — measure the backlog externally.

Ignoring memory growth because 'we have max-requests'

<code>max-requests</code> bounds a leak but does not fix it: at 1MB per request and <code>max-requests 1000</code>, each worker grows about 1GB before recycling, so peak RSS is leak x max_requests x workers. Teams pick a comfortable number without that arithmetic and still OOM. Watch per-worker RSS growth and set <code>reload-on-rss</code> below the danger zone.

Not accounting for reload impact on capacity

A standard graceful reload kills all workers and respawns them; if startup is slow, capacity sits near zero for that whole window and every deploy is a small outage teams wave off as a 'deployment blip'. Use <code>chain-reload</code> to cycle workers one at a time, and watch throughput during deploys to quantify the hit.

Reading avg_rt as a real average

<code>avg_rt</code> is <code>(old + new) / 2</code> — a short EMA weighted about 50% to the last request, negligible after seven — not a cumulative or windowed average. A single slow request swings it; a burst of fast ones erases history. Use it for trend detection only; for latency SLIs use per-endpoint percentiles from access logs.

Watching only aggregates, and forgetting Emperor vassals

Aggregate throughput and average latency hide a single stuck or leaking worker — it is only 1/N of the mean — and in Emperor mode a healthy emperor says nothing about a vassal that died on a broken config. Monitor per-worker (status, RSS, harakiri) and each vassal independently.

uWSGI runbooks in this section

Each guide is a focused runbook for one symptom or topic. Pick one when you have an incident, or use the categories to learn the area.

▸

Start here

▸

Availability and worker pool saturation

▸

Harakiri, stuck workers, and timeouts

▸

Listen queue, backlog, and dropped connections

▸

Worker memory: RSS, leaks, and recycling

▸

Reloads, respawns, and worker lifecycle

▸

Latency, response time, and throughput

▸

Concurrency: processes, threads, async, cheaper

▸

File descriptors, OS limits, and capacity

▸

Spooler, cache, and Emperor/vassals

▸

Downstream, reverse proxy, and errors

▸

Stats server, configuration, and security

WHERE TO GO NEXT

Setting up uWSGI monitoring, or putting out a fire?

If you're starting from scratch, the monitoring checklist is the path of least regret. If you're mid-incident, jump straight to the symptom that matches what you're seeing.

> Start with the checklist > Back to Operations Guides