{"id":9385,"library":"uwsgitop","title":"uWSGI top-like interface","description":"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.","status":"active","version":"0.12","language":"en","source_language":"en","source_url":"https://github.com/xrmx/uwsgitop","tags":["monitoring","uwsgi","cli","performance","server"],"install":[{"cmd":"pip install uwsgitop","lang":"bash","label":"Install uwsgitop"}],"dependencies":[{"reason":"uwsgitop monitors uWSGI instances; requires a running uWSGI Stats Server.","package":"uwsgi","optional":false}],"imports":[],"quickstart":{"code":"# 1. Start uWSGI with the stats server enabled (e.g., using a UNIX socket)\nuwsgi --module myapp --socket :3030 --stats /tmp/stats.socket --master --processes 4\n\n# 2. In a new terminal, run uwsgitop pointing to the stats socket\nuwsgitop /tmp/stats.socket\n\n# Alternatively, if uWSGI stats are served over HTTP:\nuwsgi --module myapp --http :3030 --stats :3031 --stats-http --master --processes 4\nuwsgitop http://127.0.0.1:3031","lang":"bash","description":"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."},"warnings":[{"fix":"Add `stats = /path/to/stats.socket` or `stats = 0.0.0.0:1717 --stats-http` to your uWSGI configuration.","message":"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.","severity":"gotcha","affected_versions":"All"},{"fix":"Add `memory-report = true` to your uWSGI configuration.","message":"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'.","severity":"gotcha","affected_versions":"All"},{"fix":"For historical data, consider integrating uWSGI Stats Server with tools like Telegraf, InfluxDB, and Grafana.","message":"uwsgitop displays real-time data only, similar to the `top` command. It does not provide historical metrics or logging capabilities.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"The uWSGI Stats Server is either not running, or `uwsgitop` is trying to connect to the wrong address/port.","error":"ConnectionRefusedError: [Errno 111] Connection refused"},{"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.","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.","error":"uwsgitop doesn't show all processes / only the master process"},{"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.","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.","error":"JSONDecodeError: Expecting value: line X column Y (char Z)"}]}