Austin: Python frame stack sampler for CPython
source link: https://www.tuicool.com/articles/6ZFZva2
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
A Frame Stack Sampler for CPython
Synopsis
Austin is a Python frame stack sampler for CPython written in pure C. It samples the stack traces of a Python application so that they can be visualised and analysed. As such, it serves the basis for building powerful profilers for Python.
Key features are:
- no instrumentation required;
- minimal impact on the performance of the profiling target;
- fast and lightweight;
- time and memory profiling modes.
The most interesting use of Austin is probably in conjunction with FlameGraph to profile Python applications while they are running, without the need of instrumentation. This means that Austin can be used on production code with little or even no impact on performance.
However, the output format can be grabbed from any other external tool for further processing. Look, for instance, at the following Python TUI, similar in spirit to py-spy .
Installation
Austin is available from the major software repositories of the most popular platforms.
On Linux, it can be installed using autotools
or as a snap from the Snap Store. The latter will automatically perform the steps of the autotools
method with a single command. On distributions derived from Debian, Austin can be installed from the official repositores with Aptitude.
On Windows, Austin can be easily installed from the command line from the Chocolatey repositories.
For any other platform, compiling Austin from sources is as easy as cloning the repository and running the C compiler.
With autotools
Installing Austin using autotools
amounts to the usual ./configure
, make
and make install
finger gymnastic. The only dependency is the standard C library.
git clone --depth=1 https://github.com/P403n1x87/austin.git autoreconf --install ./configure make make install
Compilation has been tested with GNU GCC 7.3.0 on Linux, MinGW 2.28-1 on Windows and LLVM 8.0.0 with clang-800.0.42.1. The code is so simple that it really compiles with just
gcc -O3 -Wall src/*.c -o src/austin
so you can use just this command if you don't have autoreconf
installed.
Add -DDEBUG
if you want a more verbose syslog output on UNIX-like systems, or %TEMP%/austin.log
on Windows.
From the Snap Store
Austin can be installed from the Snap Store with the following command
sudo snap install austin --classic
On Debian and derivatives
On March 30 2019, Austin has been accepted into the official Debian repositories and can therefore be installed with apt
. The first Ubuntu release to include Austin is 19.10.
From Chocolatey
To install Austin from Chocolatey , run the following command from the command line or from PowerShell
choco install austin
To upgrade run the following command from the command line or from PowerShell:
choco upgrade austin
From sources
To install Austin from sources using the GNU C compiler, without autotools
, clone the repository with
git clone --depth=1 https://github.com/P403n1x87/austin.git
and then run
gcc -s -Wall -O3 -o src/austin src/*.c
An extra flag is required on Windows, so the command to use in this case is
gcc -s -Wall -O3 -o src/austin src/*.c -lpsapi
Usage
Usage: austin [OPTION...] command [ARG...] Austin -- A frame stack sampler for Python. -a, --alt-format Alternative collapsed stack sample format. -e, --exclude-empty Do not output samples of threads with no frame stacks. -f, --full Produce the full set of metrics (time +mem -mem). -i, --interval=n_us Sampling interval (default is 500us). -m, --memory Profile memory usage. -o, --output=FILE Specify an output file for the collected samples. -p, --pid=PID The the ID of the process to which Austin should attach. -s, --sleepless Suppress idle samples. -t, --timeout=n_ms Approximate start up wait time. Increase on slow machines (default is 100ms). -?, --help Give this help list --usage Give a short usage message -V, --version Print program version Mandatory or optional arguments to long options are also mandatory or optional for any corresponding short options.
The output is a sequence of frame stack samples, one on each line. The format is the collapsed one that is recognised by FlameGraph so that it can be piped to flamegraph.pl
in order to produce flame graphs, or redirected to a file for some further processing.
Normal mode
By default, each line has the following structure:
Thread [tid];[func] ([mod]);#[line no];[func] ...;L[line no] [usec]
The reason why the line number is not included in the ([mod])
part, as done by py-spy, is that, this way, the flame graph will show the total time spent at each function, plus the finer detail of the time spent on each line. A drawback of this format is that frame stacks double in height. If you prefer something more conventional, you can use the -a
option to switch to the alternative format
Thread [tid];[func] ([mod]:[line no]);#[line no];[func] ... ([mod]:[line no]) [usec]
Memory and Full modes
When profiling in memory mode with the -m
or --memory
switch, the metric value at the end of each line is the memory delta between samples, measured in KB. In full mode ( -f
or --full
switches), the last three values on each line are the time delta, any positive memory delta (memory allocations) or zero and any negative memory delta (memory releases) or zero, i.e.
Thread [tid];[func] ([mod]:[line no]);#[line no];[func] ... ([mod]:[line no]) [usec] [+KB] [-KB]
Logging
Austin uses syslog
on Linux and Mac OS, and %TEMP%\austin.log
on Windows for log messages so make sure to watch these to get execution details and statistics. Bad frames are output together with the other frames. In general, entries for bad frames will not be visible in a flame graph as all tests show error rates below 1% on average.
Compatibility
Austin has been tested on the following systems (both 32- and 64-bit, unless otherwise specified).
NOTEAustin might work with other versions of Python on all the platforms and architectures above. So it is worth giving it a try even if your system is not listed below.
Linux
-
Python 2.3 (2.3.7) on Ubuntu 18.04.1
-
Python 2.4 (2.4.6) on Ubuntu 18.04.1
-
Python 2.5 (2.5.6) on Ubuntu 18.04.1
-
Python 2.6 (2.6.9) on Ubuntu 18.04.1
-
Python 2.7 (2.7.15rc1) on Ubuntu 18.04.1
-
Python 3.3 (3.3.7) on Ubuntu 18.04.1
-
Python 3.4 (3.4.9+) on Ubuntu 18.04.1
-
Python 3.5 (3.5.2) on Ubuntu 18.04.1
-
Python 3.6 (3.6.5, 3.6.6, 3.6.7) on Ubuntu 18.04.x
-
Python 3.7 (3.7.0, 3.7.1, 3.7.3, 3.7.4) on Ubuntu 18.04.x
Mac OS
-
Python 2.7 (2.7.10) on OS X "El Capitan" 10.11.4
-
Python 3.7 (3.7.0) on OS X "El Capitan" 10.11.4
Due to the introduction of the System Integrity Protection, Austin cannot be used to profile Python applications that run using binaries located in system folders. The simplest solution is to create a virtual environment and use the local Python binaries instead.
Windows
-
Python 2.7 (2.7.13) on windows 10 64-bit
-
Python 3.6 (3.6.6) on Windows 10 64-bit
-
Python 3.7 (3.7.0) on Windows 10 64-bit
-
Python 3.6 (3.6.5, 3.6.6) on Ubuntu 18.04 x86-64 via WSL
Why Austin
When there already are similar tools out there, it's normal to wonder why one should be interested in yet another one. So here is a list of features that currently distinguish Austin.
-
Written in pure CAustin is written in pure C code. There are no dependencies on third-party libraries with the exception of the standard C library and the API provided by the Operating System.
-
Just a samplerAustin is just a frame stack sampler. It looks into a running Python application at regular intervals of time and dumps whatever frame stack it finds. The samples can then be analysed at a later time so that Austin can sample at rates higher than other non-C alternative that also analyse the samples as they run.
-
Simple output, powerful toolsAustin uses the collapsed stack format of FlameGraph that is easy to parse. You can then go and build your own tool to analyse Austin's output. You could even make a player that replays the application execution in slow motion, so that you can see what has happened in temporal order.
-
Small sizeAustin compiles to a single binary executable of just a bunch of KB.
-
Easy to maintainOccasionally, the Python C API changes and Austin will need to be adjusted to new releases. However, given that Austin, like CPython, is written in C, implementing the new changes is rather straight-forward.
Examples
The following flame graph has been obtained with the command
./austin -i 50 ./test.py | ./flamegraph.pl --countname=us > test.svg
where the sample test.py
script has the following content
import psutil for i in range(1000): list(psutil.process_iter())
Austin TUI
The Python TUI that is currently included in this repository provides an example of how to use Austin to profile Python applications. You can use PageUp
and PageDown
to navigate the frame stack of each frame as the Python application runs.
If you want to give it a go you can install it using pip
with
pip install git+https://github.com/P403n1x87/austin.git
and run it with
austin-tui [OPTION...] command [ARG...]
with the same command line as Austin.
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.
Web Austin
Web Austin is yet another example of how to use Austin to make a profiling tool. It makes use of d3-flame-graph to display a live flame graph in the web browser that refreshes every 3 seconds with newly collected samples. Web Austin can also be used for remote profiling by setting the WEBAUSTIN_HOST
and WEBAUSTIN_PORT
environment variables.
If you want to give it a go you can install it using pip
with
pip install git+https://github.com/P403n1x87/austin.git
and run it with
austin-web [OPTION...] command [ARG...]
with the same command line as Austin. This starts a simple HTTP server that serves on WEBAUSTIN_HOST
if set or on localhost
otherwise. The port can be controlled with the WEBAUSTIN_PORT
environment variable. If it is not set, Web Austin will use an ephemeral port.
Contribute
If you like Austin 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 Austin by either becoming a Patron on Patreon
by buying me a coffee on BMC
or by chipping in a few pennies on PayPal.Me .
License
GNU GPLv3
Recommend
About Joyk
Aggregate valuable and interesting links.
Joyk means Joy of geeK