README.md

A Top-like Interface for Austin

 

Synopsis • Installation • Usage • Compatibility • Contribute

Synopsis

The Python TUI is a top-like text-based user interface for Austin, the frame stack sampler for CPython. Originally planned as a sample application to showcase Austin uses, it's been promoted to a full-fledged project thanks to great popularity.

The header shows you the information of the application that is being profiled, like its PID, the command line used to invoke it, as well as a plot of the amount of CPU and memory that is being used by it, in a system-monitor style.

To know more about how the TUI itself was made, have a read through The Austin TUI Way to Resourceful Text-based User Interfaces.

Installation

Austin TUI can be installed directly from PyPI with

pipx install austin-tui

NOTE In order for the TUI to work, the Austin 3 binary needs to be discoverable in the ways documented by the austin-python library. Have a look at Austin installation instructions to see how you can easily install Austin on your platform.

On macOS and Linux, Austin TUI and its dependencies (including Austin itself) can be installed via conda with

conda install -c conda-forge austin-tui

Usage

Once Austin 3 and Austin TUI are installed, you can start using them straight-away. If you want to launch and profile a Python script, say myscript.py, you can do

austin-tui python3 myscript.py

or, if myscript.py is an executable script,

austin-tui ./myscript.py

Like Austin, the TUI can also attach to a running Python application. To analyse the frame stacks of all the processes of a running WSGI server, for example, get hold of the PID of the parent process and do

sudo austin-tui -Cp <pid>

The -C option will instruct Austin to look for child Python processes, and you will be able to navigate through them with the arrow keys.

The TUI is based on python-curses. The version included with the standard Windows installations of Python is broken so it won't work out of the box. A solution is to install the the wheel of the port to Windows from this page. Wheel files can be installed directly with pip, as described in the linked page.

Thread navigation

Profiling data is processed on a per-thread basis. The total number of threads (across all processes, if sampling child processes) is displayed in the top-right corner of the TUI. To navigate to a different thread, use the ← and → arrows. The PID and TID of the currently selected thread will appear in the middle of the top bar in the TUI.

Full mode

By default, Austin TUI shows you statistics of the last seen stack for each process and thread when the UI is refreshed (about every second). This is similar to what top does with all the running processes on your system.

If you want to see all the collected statistics, with the frame stacks represented as a rooted tree, you can press F to enter the Full mode. The last seen stack will be highlighted so that you also have that information available while in this mode.

The information that gets displayed is very dynamic and could become tricky to inspect. The current view can be paused by pressing P. To resume refreshing the view, press P again. While the view is paused, profiling data is still being captured and processed in the background, so that when the view is resumed, the latest figures are shown.

Graph mode

A live flame graph visualisation of the current thread statistics can be displayed by pressing G. This might help with identifying the largest frames at a glance.

To toggle back to the top view, simply press G again.

Save statistics

Peeking at a running Python application is nice but in many cases you would want to save the collected data for further offline analysis (for example, you might want to represent it as a flame graph). At any point, whenever you want to dump the collected data to a file, you can press S and a file with all the samples will be generated for you in the working directory, prefixed with austin_ and followed by a timestamp. The TUI will notify of the successful operation on the bottom-right corner.

If you run the Austin TUI inside VS Code, you can benefit from the editor's terminal features, like using Ctrl/Cmd+Left-Click to hop straight into a source file at a given line. You can also leverage the TUI's save feature to export the collected samples and import them into the Austin VS Code extension to also get a flame graph representation.

Threshold

The statistics reported by the TUI might be overwhelming, especially in full mode. To reduce the amout of data that gets displayed, the keys + and - can be used to increase or lower the %TOTAL threshold

Compatibility

Austin TUI has been tested with Python 3.7-3.10 and is known to work on Linux, macOS and Windows.

Since Austin TUI uses Austin to collect samples, the same note applies here:

Due to the System Integrity Protection introduced in macOS with El Capitan, Austin cannot profile Python processes that use an executable located in the /bin folder, even with sudo. Hence, either run the interpreter from a virtual environment or use a Python interpreter that is installed in, e.g., /Applications or via brew with the default prefix (/usr/local). Even in these cases, though, the use of sudo is required.

As for Linux users, the use of sudo can be avoided by granting Austin the cap_sys_ptrace capability with, e.g.

sudo setcap cap_sys_ptrace+ep `which austin`

Contribute

If you like Austin TUI and you find it useful, there are ways for you to contribute.

If you want to help with the development, then have a look at the open issues and have a look at the contributing guidelines before you open a pull request.

You can also contribute to the development of the Austin TUI by becoming a sponsor and/or by buying me a coffee on BMC or by chipping in a few pennies on PayPal.Me.