uWSGI top-like interface

0.12 · active · verified Thu Apr 16

uwsgitop is a command-line tool that provides a 'top-like' interface for real-time monitoring of uWSGI applications. It connects to the uWSGI Stats Server to display worker statistics, memory usage, request rates, and other vital metrics in a curses-based terminal view. The current version is 0.12, and while functional, the project exhibits a slow release cadence, primarily for maintenance rather than active feature development.

Common errors

```
ConnectionRefusedError: [Errno 111] Connection refused
```
cause The uWSGI Stats Server is either not running, or `uwsgitop` is trying to connect to the wrong address/port.

fix Verify your uWSGI configuration includes `stats` (e.g., `stats = /tmp/stats.socket` or `stats = 127.0.0.1:1717 --stats-http`). Ensure uWSGI is running and the specified stats address is correct and accessible from where `uwsgitop` is executed.
```
uwsgitop doesn't show all processes / only the master process
```
cause This can happen in uWSGI's Emperor mode without proper vassal configuration, or if the uWSGI instance is not configured to spawn workers, or if the stats server isn't correctly reporting worker information.

fix Ensure your uWSGI configuration has `processes = X` (where X > 1) and that the Stats Server is properly configured. For Emperor mode, individual vassals might need their own stats sockets, or you might need to use a custom solution to aggregate stats.
```
JSONDecodeError: Expecting value: line X column Y (char Z)
```
cause uwsgitop received data from the stats server that it could not parse as valid JSON. This often happens if the `stats-http` option is missing when connecting to an HTTP address, or if another service is listening on the specified port/socket.

fix If connecting to an HTTP address, ensure `stats-http` is enabled in uWSGI config. Double-check the address/port to ensure it's exclusively used by the uWSGI Stats Server and that the uWSGI instance is healthy.

Warnings

gotcha uwsgitop requires the uWSGI Stats Server to be explicitly enabled in your uWSGI configuration. Without it, uwsgitop will not be able to connect or display any data. You'll likely see connection errors.
Fix: Add `stats = /path/to/stats.socket` or `stats = 0.0.0.0:1717 --stats-http` to your uWSGI configuration.
gotcha For detailed memory statistics (RSS and VSZ), you must enable the `memory-report` option in your uWSGI configuration. Otherwise, these fields in uwsgitop will show '0'.
Fix: Add `memory-report = true` to your uWSGI configuration.
gotcha uwsgitop displays real-time data only, similar to the `top` command. It does not provide historical metrics or logging capabilities.
Fix: For historical data, consider integrating uWSGI Stats Server with tools like Telegraf, InfluxDB, and Grafana.
gotcha When using UNIX sockets for the uWSGI Stats Server, ensure that the user running `uwsgitop` has appropriate read permissions on the socket file. Incorrect permissions will lead to 'Permission denied' errors.
Fix: Set appropriate permissions in your uWSGI config using `chmod-socket = 666` (or more restrictive `660` if the user is in the correct group) or ensure `uwsgitop` is run by the same user/group as uWSGI.

Install

pip install uwsgitop Install uwsgitop

Quickstart

To use uwsgitop, you must first enable the Stats Server in your uWSGI configuration. This can be done via a UNIX socket or an HTTP address. Then, execute the `uwsgitop` command, providing the address of the uWSGI Stats Server.

# 1. Start uWSGI with the stats server enabled (e.g., using a UNIX socket)
uwsgi --module myapp --socket :3030 --stats /tmp/stats.socket --master --processes 4

# 2. In a new terminal, run uwsgitop pointing to the stats socket
uwsgitop /tmp/stats.socket

# Alternatively, if uWSGI stats are served over HTTP:
uwsgi --module myapp --http :3030 --stats :3031 --stats-http --master --processes 4
uwsgitop http://127.0.0.1:3031

view raw JSON →