Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/P403n1x87/austin-tui

The top-like text-based user interface for Austin
https://github.com/P403n1x87/austin-tui

hacktoberfest performance profiling python tools tui

Last synced: about 2 months ago
JSON representation

The top-like text-based user interface for Austin

Awesome Lists containing this project

README 

        


  
Austin TUI





A Top-like Interface for Austin





  

    GitHub Actions: Tests

  

  


  

  

    PyPI

  

  

    PyPI Downloads

  

   

  

    

  

  

    

  

  

  


  

  

    LICENSE

  






  Synopsis •

  Installation •

  Usage •

  Compatibility •

  Contribute






  

  Buy Me A Coffee

  




# 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.





  Austin TUI




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



~~~ console

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



~~~ console

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



~~~ console

austin-tui python3 myscript.py

~~~



or, if `myscript.py` is an executable script,



~~~ console

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



~~~ console

sudo austin-tui -Cp 

~~~



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](https://www.lfd.uci.edu/~gohlke/pythonlibs/#curses) page. Wheel files

> can be installed directly with `pip`, as described in the

> [linked](https://pip.pypa.io/en/latest/user_guide/#installing-from-wheels)

> 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.





  Austin TUI - Default mode




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.





  Austin TUI - Full 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.





  Austin TUI - Live flame graph




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.





  Austin TUI - Save notification




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.





  Austin TUI




## 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





  Austin TUI - Threshold demonstration




# 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.



~~~ console

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](CONTRIBUTING.md) 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](https://www.buymeacoffee.com/Q9C1Hnm28)

on BMC or by chipping in a few pennies on

[PayPal.Me](https://www.paypal.me/gtornetta/1).





  

  Buy Me A Coffee

  




[Austin]: https://github.com/P403n1x87/austin

[austin-python]: https://github.com/P403n1x87/austin-python#installation

[Austin installation]: https://github.com/P403n1x87/austin#installation

[Austin VS Code]: https://marketplace.visualstudio.com/items?itemName=p403n1x87.austin-vscode

[The Austin TUI Way to Resourceful Text-based User Interfaces]: https://p403n1x87.github.io/the-austin-tui-way-to-resourceful-text-based-user-interfaces.html