Package: austin-tui
A Top-like Interface for AustinSynopsis•Installation•Usage•Compatibility•ContributeSynopsisThe Python TUI is a top-like text-based user interface forAustin, the frame
stack sampler for CPython. Originally planned as a sample application to
showcaseAustinuses, 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 throughThe Austin
TUI Way to Resourceful Text-based User Interfaces.InstallationAustin TUI can be installed directly from PyPI withpipx install austin-tuiNOTEIn order for the TUI to work, the Austin 3 binary needs to be
discoverable in the ways documented by theaustin-pythonlibrary. Have a
look atAustin installationinstructions 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 withconda install -c conda-forge austin-tuiUsageOnceAustin3 and Austin TUI are installed, you can start using them
straight-away. If you want to launch and profile a Python script, saymyscript.py, you can doaustin-tui python3 myscript.pyor, ifmyscript.pyis an executable script,austin-tui ./myscript.pyLikeAustin, 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 dosudo austin-tui -Cp <pid>The-Coption will instructAustinto look for child Python processes, and you
will be able to navigate through them with the arrow keys.The TUI is based onpython-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 fromthispage. Wheel files
can be installed directly withpip, as described in thelinkedpage.Thread navigationProfiling 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 modeBy 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 pressFto enter theFullmode. 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 pressingP. To resume
refreshing the view, pressPagain. 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 modeA live flame graph visualisation of the current thread statistics can be
displayed by pressingG. This might help with identifying the largest
frames at a glance.To toggle back to the top view, simply pressGagain.Save statisticsPeeking 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 pressSand a file with all the
samples will be generated for you in the working directory, prefixed withaustin_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 usingCtrl/Cmd+Left-Clickto 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 theAustin VS Codeextension to also get a flame graph representation.ThresholdThe 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%TOTALthresholdCompatibilityAustin TUI has been tested with Python 3.7-3.10 and is known to work onLinux,macOSandWindows.Since Austin TUI usesAustinto collect samples, the same note applies here:Due to theSystem Integrity Protectionintroduced inmacOSwith El
Capitan, Austin cannot profile Python processes that use an executable located
in the/binfolder, even withsudo. Hence, either run the interpreter from
a virtual environment or use a Python interpreter that is installed in, e.g.,/Applicationsor viabrewwith the default prefix (/usr/local). Even in
these cases, though, the use ofsudois required.As for Linux users, the use ofsudocan be avoided by granting Austin thecap_sys_ptracecapability with, e.g.sudo setcap cap_sys_ptrace+ep `which austin`ContributeIf 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 thecontributing guidelinesbefore you
open a pull request.You can also contribute to the development of the Austin TUI by becoming a
sponsor and/or bybuying me a coffeeon BMC or by chipping in a few pennies onPayPal.Me.