uWSGI stats server: enabling it and reading it without --stats-http

The uWSGI stats server is the primary data source for every monitoring signal in the uWSGI playbook: worker busy ratio, harakiri count, avg_rt, respawn rate, RSS, exception counts, and more. Without it, you are blind to internal state. With it, you have complete visibility into worker pool health, saturation, and failure modes.

The stats server must be explicitly enabled with the --stats option. It is not on by default. Once enabled, it serves a JSON document containing the full internal state of the master process and all workers, including PIDs, worker status, request counters, memory usage, and per-core request data.

The critical gotcha: by default, the stats server speaks a raw binary protocol over a socket, not HTTP. Running curl http://127.0.0.1:9191 against a default stats socket produces garbage output or a hung connection. HTTP access requires the additional --stats-http flag. This article covers enabling the stats server, choosing the right socket type, and reading the raw JSON output regardless of whether HTTP mode is enabled.

What this enables

The stats server exports a JSON document with the complete internal state of the uWSGI instance. The top-level fields include the master PID, listen queue depth, and signal queue. The workers[] array contains per-worker data including id, pid, status (idle, busy, cheap, pause, sig), accepting, requests, delta_requests, avg_rt (microseconds), running_time, harakiri_count, respawn_count, exceptions, rss, vsz, tx, signal_queue, and last_spawn. Each worker also contains a cores[] array with per-core in_request, write_errors, read_errors, and when a request is in flight, req_info.request_start (a UNIX timestamp).

The stats server is served by the master process, not by workers. This means it remains responsive even when every worker is stuck, hung, or in a crash loop. This is valuable for diagnosis during incidents: you can read the stats of a completely saturated instance. But it also means the stats server is not a valid user-facing health check. A responsive stats endpoint does not indicate that workers can serve requests.

Prerequisites

• uWSGI config access. You need write access to the uWSGI INI file or the ability to pass CLI flags, plus the ability to reload the instance.
• The uwsgi binary. Used for uwsgi --connect-and-read <addr>, the recommended way to read a default (non-HTTP) TCP stats socket.
• socat or nc. For reading default UNIX socket stats endpoints. The playbook uses socat - UNIX-CONNECT:<path>.
• jq (recommended). The JSON output is dense. All collection commands in the uWSGI playbook pipe through jq for filtering.
• uWSGI 2.0.5 or later. Required for --stats-no-cores. The stats server itself has been available since 1.x.

Procedure

1. Enable the stats server

Add the --stats option to your uWSGI configuration with a socket address. Choose TCP, UNIX socket, or abstract socket.

INI format:

[uwsgi]
stats = 127.0.0.1:9191

CLI equivalent:

uwsgi --ini app.ini --stats 127.0.0.1:9191

For a UNIX socket:

stats = /tmp/uwsgi-stats.sock

For an abstract socket (Linux only):

stats = @uwsgistats

Reload uWSGI for the change to take effect.

2. Choose the socket type

The stats server has no authentication. Anyone who can reach the socket can read PIDs, in-flight request URIs, and configuration details. Bind to localhost or a UNIX socket with restrictive permissions.

3. Read the raw JSON output

The default stats server speaks the raw uwsgi binary protocol, not HTTP. The reading method depends on the socket type and whether --stats-http is enabled.

flowchart TD
    A["Stats socket enabled"] --> B{"--stats-http set?"}
    B -->|No| C["Raw uwsgi protocol"]
    B -->|Yes| D["HTTP protocol"]
    D --> E["curl http://addr:port"]
    C --> F{"Socket type?"}
    F -->|TCP| G["uwsgi --connect-and-read addr:port"]
    F -->|UNIX| H["socat - UNIX-CONNECT:path"]

TCP socket (default protocol):

# Read full JSON output from a TCP stats socket
uwsgi --connect-and-read 127.0.0.1:9191 | jq .

UNIX socket (default protocol):

# Read full JSON output from a UNIX stats socket
socat - UNIX-CONNECT:/tmp/uwsgi-stats.sock | jq .

Any socket type with –stats-http enabled:

# Read stats over HTTP (requires --stats-http flag)
curl -s http://127.0.0.1:9191 | jq .

The JSON output is identical regardless of transport. The protocol only affects how you connect.

4. Optionally enable HTTP mode

If you want to use curl, wget, or any HTTP client to read the stats, add --stats-http alongside --stats:

[uwsgi]
stats = 127.0.0.1:9191
stats-http = true

This modifies the stats socket to serve HTTP instead of the raw uwsgi protocol. It does not create a separate listener. Both flags must reference the same socket address.

5. Optionally reduce payload size

The cores[] array adds significant size to the JSON output, especially with many workers and threads. If you do not need per-core data, suppress it:

stats = 127.0.0.1:9191
stats-no-cores = true

This drops all cores[] fields from every worker. Without it, write_errors, read_errors, in_request, and req_info.request_start are available. With it, those signals are lost.

6. Enable memory metrics

By default, the rss and vsz fields in the stats output show as 0. To populate them, add --memory-report:

[uwsgi]
stats = 127.0.0.1:9191
memory-report = true

Without --memory-report, you cannot track per-worker RSS growth, detect memory leaks, or correlate memory pressure with respawns.

Verifying it works

After reloading uWSGI with the stats server enabled, verify connectivity:

# Verify TCP stats socket responds
uwsgi --connect-and-read 127.0.0.1:9191 | jq '{pid, workers: (.workers | length)}'

Expected output includes the master PID and the count of workers in the workers[] array. If the command hangs or returns garbage, you may be connecting with the wrong protocol (see pitfalls below).

Check that memory metrics are populated:

# Verify RSS/VSZ are non-zero (requires --memory-report)
uwsgi --connect-and-read 127.0.0.1:9191 | jq '.workers[] | select(.pid > 0) | {id: .id, rss: .rss, vsz: .vsz}'

If RSS and VSZ are both 0, --memory-report is not enabled.

Verify the stats socket is bound to localhost only:

# Confirm stats socket is not exposed on a public interface
ss -ltnp | grep 9191

The ss output should show the socket bound to 127.0.0.1:9191, not 0.0.0.0:9191.

Common pitfalls

Adding --stats-http without --stats. The --stats-http flag modifies the behavior of the stats socket; it does not create one. If you only set stats-http = true without stats = <addr>, no stats server starts. You need both.

Using curl on a default (non-HTTP) stats socket. The default stats server speaks the raw uwsgi binary protocol. Running curl http://127.0.0.1:9191 against it returns binary garbage or hangs because curl expects HTTP. Use uwsgi --connect-and-read for TCP sockets or socat - UNIX-CONNECT:<path> for UNIX sockets instead.

RSS and VSZ showing 0. The stats server does not collect memory data unless --memory-report is explicitly enabled. This is the most common surprise when teams first set up monitoring. Add memory-report = true to the config.

Using the stats endpoint as a health check. The stats server is served by the master process and stays responsive during complete worker starvation. A Kubernetes livenessProbe or load balancer health check pointed at the stats endpoint will report healthy even when all workers are dead. Health checks must go through the worker pool, experiencing the same queuing as real requests.

Exposing the stats socket on a public interface. The stats server has no authentication and exposes PIDs, configuration details, and in-flight request URIs (including headers via cores[].vars). Bind to localhost or a UNIX socket with restrictive permissions only.

Suppressing cores when you need stuck-request detection. --stats-no-cores reduces payload size but also removes in_request, req_info.request_start, write_errors, and read_errors. If you plan to detect stuck requests by their age or track per-core socket errors, do not enable this flag.

Signals to monitor

Once the stats server is running, these are the highest-priority fields to collect and alert on:

Note: avg_rt is an exponential moving average computed as (old + new) / 2, not a cumulative average. A single slow request shifts it significantly. See uWSGI avg_rt is not a real average for details.

Also note: the listen_queue and load fields in the stats output are unreliable on standard Linux and almost always read 0 regardless of actual backlog. Measure the socket queue depth externally with ss -ltn or ss -lxn.

How Netdata helps

• Netdata polls the stats socket at per-second resolution, catching transient saturation events that coarser scraping intervals miss.
• Worker busy ratio and accepting worker count, read from the same stats payload, provide an immediate view of whether the instance is approaching capacity or already saturated.
• Harakiri rate and respawn rate from the same source let you distinguish crash loops from normal max-requests recycling without manual delta tracking.
• Per-worker RSS (when --memory-report is enabled), correlated with host-level swap usage and OOM-killer events, pinpoints whether memory pressure originates in uWSGI or elsewhere on the host.
• Correlating avg_rt with downstream dependency latency (database, cache, external API) shows whether rising response time is an application problem or a cascade from a slow dependency.
• The stats server remaining responsive while workers are stuck is itself a diagnostic signal: reachable stats with zero accepting workers means the master is alive but the application is not serving.

Related guides

• uWSGI all workers busy: reading the busy ratio before the queue fills
• uWSGI avg_rt is not a real average: why the latency number lies
• uWSGI cache subsystem: hit ratio drops and ‘full’ insert failures
• uWSGI capacity planning: the leading indicators before saturation
• uWSGI chain reload: cycling workers one at a time for zero-downtime deploys
• uWSGI cheaper subsystem: dynamic worker scaling and the false ‘missing workers’ alert
• uWSGI connection pool cascade: downstream latency that stalls every worker
• uWSGI connection refused: clients turned away when the backlog overflows
• uWSGI Emperor healthy but vassal dead: monitoring each instance independently
• uWSGI file descriptor limits: raising ulimit -n and systemd LimitNOFILE
• uWSGI in gevent/async mode: why worker busy ratio stops meaning anything
• uWSGI threaded mode and the GIL: why more threads don’t add CPU parallelism