uWSGI monitoring checklist: the signals every production app server needs

The stats server (enabled with --stats <socket>) exports a JSON document with worker state, request counters, memory usage, and error rates. This checklist organizes those signals by maturity level, from survival to expert. Each level assumes the previous one is in place.

uWSGI is in maintenance mode (bugfixes only, no new features), so the stats schema and signal semantics are stable. Three fields are not: listen_queue, load, and listen_queue_errors are broken or dead code on standard Linux. This checklist flags every unreliable field and points to the external measurement that works instead.

Three prerequisites must be satisfied before any stats-based signal works. First, enable the stats server with --stats <socket>; by default it serves raw JSON on a socket, and HTTP access requires --stats-http. Second, enable --memory-report (shortcut -m) so RSS and VSZ fields report real values instead of zero. Third, configure --harakiri <seconds> so stuck workers have a timeout; without it, harakiri_count is permanently zero and gives false confidence.

flowchart TD
    L1["Level 1 - Survival
master alive, accepting workers,
throughput nonzero"]
    L2["Level 2 - Operational
busy ratio, harakiri rate, avg_rt,
per-worker RSS, exception rate"]
    L3["Level 3 - Mature
respawn rate, signal queue,
spooler/cache, Emperor/Vassal"]
    L4["Level 4 - Expert
stuck request age, per-core concurrency,
external listen queue, RSS divergence"]
    L1 --> L2 --> L3 --> L4

Level 1: survival

These three signals answer one question: is uWSGI alive and serving requests? Missing any of them means you cannot distinguish “completely down” from “healthy under load.”

Signal	What it tells you	Collection	Alert condition
Master process alive	If the master is dead, no workers exist and no requests are served. The master never handles requests itself.	`kill -0 $(cat /path/to/uwsgi.pid)` or top-level `pid` in stats JSON	PAGE on absence. Verify with `kill -0`, not PID file existence, since the file can be stale.
At least one accepting worker	Workers with `pid > 0`, `status != "cheap"`, and `accepting == 1` can serve requests now. Zero accepting workers with a running master means the service is down.	`uwsgi --connect-and-read <addr> \| jq '[.workers[] \| select(.pid > 0 and .status != "cheap" and .accepting == 1)] \| length'`	PAGE when zero accepting workers persist for more than 60 seconds with the master alive.
Request throughput nonzero	Sum of `workers[].requests` across all workers, computed as a delta between polls. Zero throughput with alive workers means requests are stuck or not arriving.	`uwsgi --connect-and-read <addr> \| jq '[.workers[].requests] \| add'`	TICKET when throughput drops to zero during expected traffic hours with master alive.

Cheaper-aware note: If the cheaper subsystem is active, worker count fluctuates by design. Cheaped workers appear in stats with status: "cheap" and pid: 0. Do not alert on absolute worker count. Alert on accepting worker count and utilization ratios instead.

Level 2: operational

Five signals cover the failure modes that cause most production incidents: worker exhaustion, stuck workers, memory leaks, and application errors.

Signal	What it tells you	Collection	Alert condition
Worker busy ratio	Proportion of alive workers in `busy` status. At 100%, every additional request queues in the kernel backlog with no uWSGI-level visibility.	Count `status == "busy"` divided by workers where `pid > 0 AND status != "cheap"`	TICKET on sustained above 80%. Brief spikes during bursts are normal if they self-resolve.
Harakiri rate (delta)	Each harakiri kill means a request exceeded the timeout, the master sent SIGKILL to the worker, and the client got a 502. Track the delta, not the absolute count.	Sum `workers[].harakiri_count`, compute delta between polling intervals	TICKET on any sustained non-zero rate over a 5-minute window. The counter is per-worker and monotonic; it never resets, even on respawn.
Average response time (avg_rt)	Per-worker exponential moving average, reported in microseconds, updated as `(old + new) / 2`. Roughly 50% weight on the most recent request, making it responsive but volatile.	Average `avg_rt` across alive non-cheaped workers	TICKET on sustained increase above 2x recent baseline. Compare against configured harakiri timeout.
Per-worker RSS	Physical memory per worker. Consistent growth across all workers indicates a leak. One outlier indicates a request-specific memory issue. Requires `--memory-report` for non-zero values.	`jq '.workers[] \| select(.pid > 0) \| {id, rss_mb: (.rss / 1048576)}'`	TICKET on sustained positive slope over hours. Alert if any worker exceeds 2x the RSS of the youngest worker.
Exception rate (delta)	Application exceptions caught at the WSGI/protocol layer. Application-level try/except blocks that handle errors internally do not increment this counter.	Sum `workers[].exceptions`, compute delta	TICKET on sustained increase above baseline. A ratio of exceptions per requests is more stable than absolute counts.

avg_rt caveat: The (old + new) / 2 formula gives approximately 50% weight to the most recent request, 25% to the second-most-recent, and 12.5% to the third. After roughly 7 requests, older contributions fall below 1%. A single slow request can shift avg_rt significantly. Do not use avg_rt as a latency SLI. Use access log percentiles (p50, p95, p99) per endpoint instead.

Harakiri not configured is a monitoring gap: If --harakiri is absent, harakiri_count is always zero. This is not health. It means stuck workers have no timeout and permanently consume a worker slot. The absence of harakiri configuration is itself a risk that should be flagged during setup and review.

Level 3: mature

Seven signals add lifecycle tracking and subsystem health. The respawn rate signal is the most important addition at this level because it distinguishes healthy max-requests recycling from crash-induced churn.

Signal	What it tells you	Collection	Alert condition
Respawn rate (delta)	Worker lifecycle churn. Normal causes include `max-requests` recycling and `reload-on-rss` memory management. Abnormal causes include crashes and harakiri kills. To isolate crash respawns, subtract the harakiri rate from the respawn rate.	Sum `workers[].respawn_count`, compute delta	TICKET when respawn rate significantly exceeds the expected rate from `max-requests` configuration and traffic volume. A sudden spike across multiple workers indicates a mass-kill event.
Signal queue depth	Pending uWSGI internal signals (timers, file monitors, custom signals). Not related to UNIX signals. Should be zero in steady state.	Top-level `signal_queue` and per-worker `workers[].signal_queue`	TICKET on any sustained non-zero value.
Write errors (per core)	Socket write errors during response delivery. Typically means the client disconnected before the response completed (broken pipe). Sustained high rates indicate slow responses or proxy timeouts.	Sum `workers[].cores[].write_errors`, compute delta. Suppressed by `--stats-no-cores`.	TICKET on significant sustained increase above baseline.
Read errors (per core)	Socket read errors during request reception. Client connections lost mid-request. Can indicate network instability or proxy misconfiguration.	Sum `workers[].cores[].read_errors`, compute delta. Suppressed by `--stats-no-cores`.	TICKET on significant sustained increase above baseline.
Spooler health	Pending tasks, running state, and respawns for uWSGI spooler processes. Growing task count means the spooler cannot keep up. High respawns means the spooler process is crashing.	`.spoolers[]` array (only present when spoolers are configured)	TICKET on sustained task growth or any non-zero respawn rate.
Cache performance	Hit/miss ratios and fullness of uWSGI built-in cache. Non-zero `full` count means cache capacity is exhausted.	`.caches[]` array (only present when cache is configured)	TICKET on declining hit ratio or non-zero `full` rate.
Emperor/Vassal health	In Emperor mode, each Vassal is an independent uWSGI instance. The Emperor can be healthy while a Vassal is dead (broken config, resource limits). Each Vassal needs independent monitoring via its own stats server.	Per-Vassal stats server or process monitoring	TICKET when a Vassal fails to start or dies and does not restart.

Level 4: expert

Eight signals provide per-request and per-worker granularity. These are the signals you add after incidents that aggregate metrics failed to catch: a single stuck worker, a slow endpoint hidden in averages, or a listen queue overflow invisible to uWSGI’s own counters.

Signal	What it tells you	Collection	Alert condition
External listen queue depth	Kernel socket backlog, the buffer between incoming connections and available workers. Measured externally because uWSGI’s `listen_queue` field is broken on standard Linux.	`ss -ltn 'sport = :PORT'` (check Recv-Q for depth, Send-Q for backlog limit). For UNIX sockets: `ss -lxn` and filter the output by path with grep (`ss` has no path filter argument for UNIX sockets).	TICKET on sustained non-zero Recv-Q.
Listen overflows (kernel)	Connections dropped because the backlog was full. System-wide counter, not per-socket. On multi-service hosts, correlate with per-socket queue depth to attribute drops to uWSGI.	`nstat -az TcpExtListenOverflows TcpExtListenDrops`	PAGE on any non-zero rate of change. Users are experiencing connection failures right now.
Stuck request age	Elapsed time of in-flight requests. Detectable via per-core `in_request` flag and `req_info.request_start` (epoch seconds) inside each core’s `req_info` object. Critical when harakiri is not configured, since stuck requests have no timeout.	`jq` on `workers[].cores[]` where `in_request == 1`, compute current time minus request start timestamp	TICKET when request age approaches harakiri timeout, or exceeds a reasonable maximum if harakiri is absent.
Per-core in_request	Thread-level concurrency visibility. In threaded mode, “busy” means at least one thread is active, not that all threads are occupied. Per-core `in_request` is the true concurrency indicator.	`jq` on `workers[].cores[].in_request`. Suppressed by `--stats-no-cores`.	Context-dependent. Use for diagnosis, not standalone alerting.
Per-worker RSS divergence	One worker with RSS much higher than others indicates a request-specific memory issue: regex backtracking (ReDoS), unbounded query results loaded into memory, or a blocking call.	Compare per-worker RSS values. Flag when any worker exceeds 2x the youngest (most recently respawned) worker.	TICKET on significant divergence.
Running time / request count	True average processing time per request (`running_time / requests`), more accurate than avg_rt for long-running workers.	Derived from `workers[].running_time` and `workers[].requests`	Baseline-relative.
TX bytes per worker	Data volume served per worker. A sudden spike may indicate large responses. A drop with stable request count may indicate truncated responses.	Sum `workers[].tx`, compute delta	Baseline-relative. Alert on significant deviation from historical tx-per-request ratio.
File descriptor headroom	Not visible in uWSGI stats. Must be measured at the OS level. Exhaustion causes silent connection failures (EMFILE) with no uWSGI-level signal.	`ls /proc/<master_pid>/fd \| wc -l` and per-worker. Compare against `ulimit -n`.	TICKET when usage exceeds 80% of the soft limit.

Counter reset behavior: On a worker respawn, source code inspection shows delta_requests, rss, vsz, uss, and pss are reset to 0, while requests, running_time, avg_response_time, tx, exceptions, harakiri_count, and respawn_count are not reset and keep their values on the worker slot. Do not build monitoring logic that depends on respawn resets for counters other than the memory fields and delta_requests. If workers respawn frequently, use the monotonic requests counter and compute deltas externally for consistency.

Signals you cannot trust

Several stats fields appear useful but produce false confidence. Do not build alerts or dashboards on them.

Field	Problem	What to do instead
`listen_queue`	Broken on standard Linux. TCP measurement relies on kernel-version-dependent `TCP_INFO` behavior. UNIX socket measurement requires a non-standard kernel ioctl. Almost always reads 0 regardless of actual backlog.	Measure externally with `ss -ltn` (TCP) or `ss -lxn` (UNIX).
`load`	Identical to `listen_queue` in the source code, not average latency as the name implies. The source contains a `TODO` comment acknowledging this.	Do not use. Track avg_rt for application latency, or use access log percentiles.
`listen_queue_errors`	Dead code. The field exists in the JSON output but is never incremented anywhere in the uWSGI source. Always 0.	Use kernel `TcpExtListenOverflows` via `nstat` or `/proc/net/netstat`.
`rss` / `vsz` without `--memory-report`	Report 0 when the flag is not enabled. Many monitoring setups silently report zero memory usage because of this.	Enable `--memory-report` (shortcut `-m`) in the uWSGI configuration.

Common collection mistakes

Alerting on absolute worker count with cheaper enabled: When the cheaper subsystem is active, worker count fluctuates by design. Alerting on “expected workers vs actual workers” generates false positives when workers are intentionally scaled down. Alert on accepting worker count and busy ratio instead.

Treating all respawns as crashes: max-requests recycling produces routine, healthy respawns. With max-requests = 1000 and steady traffic, respawns are expected at a predictable cadence. Correlate respawn rate with harakiri count: if respawns track harakiri 1:1, workers are crashing or being killed. If respawns are steady with zero harakiri, it is recycling.

Using curl without –stats-http: The stats server exports raw JSON on a socket by default. curl http://... only works if --stats-http is explicitly enabled. Use uwsgi --connect-and-read <addr> for TCP stats sockets or socat - UNIX-CONNECT:<path> for UNIX stats sockets.

Using avg_rt as a latency SLI: avg_rt is an exponential moving average with 50% weight on the most recent request. It is volatile and not suitable for service-level indicators. Use access log percentiles per endpoint instead.

Monitoring only the reverse proxy: Nginx 502 and 504 rates are lagging indicators. By the time the proxy reports upstream errors, uWSGI has been saturated for seconds or minutes. Worker busy ratio and avg_rt provide earlier warning.

Treating the stats endpoint as a health check: The stats server runs in the master process, which stays responsive during complete worker starvation. A health check that pings the stats endpoint returns success while 100% of real requests are being dropped. Health checks must go through the worker pool so they experience the same queuing as real requests.

How Netdata helps

Per-second granularity: Worker busy ratio and the kernel listen queue can spike and recover between coarse polling intervals. Per-second collection catches saturation bursts that 10- or 15-second scrapes miss.
Delta computation built in: Counters like harakiri_count, respawn_count, and exceptions are per-worker monotonic values that never reset. Netdata handles rate computation automatically, including across worker respawns.
External listen queue monitoring: Netdata’s system collectors surface TcpExtListenOverflows and socket queue depths at the kernel level, compensating for uWSGI’s broken listen_queue field without custom scripts.
Cross-layer correlation: When worker busy ratio rises, Netdata displays it alongside system memory pressure, CPU saturation, swap usage, and downstream dependency metrics on the same timeline. This correlation is where the root cause becomes obvious within seconds instead of minutes.
Anomaly detection on trends: ML-based anomaly detection on avg_rt, busy ratio, and per-worker RSS trends surfaces slow degradation (memory leaks, capacity creep) before static threshold alerts would fire.