A Frame Stack Sampler for CPython

         

Synopsis • Installation • Usage • Cheat sheet • Compatibility • Why Austin • Examples • Contribute

---

This is the nicest profiler I’ve found for Python. It’s cross-platform, doesn’t need me to change the code that’s being profiled, and its output can be piped directly into flamegraph.pl. I just used it to pinpoint a gross misuse of SQLAlchemy at work that’s run in some code at the end of each day, and now I can go home earlier.

-- gthm on lobste.rs

If people are looking for a profiler, Austin looks pretty cool. Check it out!

-- Michael Kennedy on Python Bytes 180

Follow on

---

Synopsis

Austin is a Python frame stack sampler for CPython written in pure C. Samples are collected by reading the CPython interpreter virtual memory space to retrieve information about the currently running threads along with the stack of the frames that are being executed. Hence, one can use Austin to easily make powerful statistical profilers that have minimal impact on the target application and that don't require any instrumentation.

The key features of Austin are: - Zero instrumentation; - Minimal impact; - Fast and lightweight; - Time and memory profiling; - Built-in support for multi-process applications (e.g. mod_wsgi).

The simplest way to turn Austin into a full-fledged profiler is to use together with the VS Code extension or combine it with [FlameGraph] or [Speedscope]. However, Austin's binary output can be piped into any other external or custom tools for further processing. Look, for instance, at the following Python TUI

Check out A Survey of Open-Source Python Profilers by Peter Norton for a general overview of Austin.

Keep reading for more tool ideas and examples!

---

💜

Austin is a free and open-source project. A lot of effort goes into its development to ensure the best performance and that it stays up-to-date with the latest Python releases. If you find it useful, consider sponsoring this project.

🙏

---

Installation

Austin is available to install from PyPI and from the major software repositories of the most popular platforms. Check out the [latest release] page for pre-compiled binaries and installation packages.

On all supported platforms and architectures, Austin can be installed from PyPI with pip or pipx via the commands

pip install austin-dist

or

pipx install austin-dist

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 repositories with apt. Anaconda users can install Austin from [Conda Forge].

On Windows, Austin can be easily installed from the command line using either [Chocolatey] or [Scoop]. Alternatively, you can download the installer from the [latest release] page.

On macOS, Austin can be easily installed from the command line using [Homebrew]. Anaconda users can install Austin from [Conda Forge].

For any other platforms, compiling Austin from sources is as easy as cloning the repository and running the C compiler. The [Releases][releases] page has many pre-compiled binaries that are ready to be uncompressed and used.

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. Before proceeding with the steps below, make sure that the autotools are installed on your system. Refer to your distro's documentation for details on how to do so.

git clone --depth=1 https://github.com/P403n1x87/austin.git && cd austin
autoreconf --install
./configure
make
make install

NOTE Some Linux distributions, like Manjaro, might require the execution of automake --add-missing before ./configure.

Alternatively, sources can be compiled with just a C compiler (see below).

From the Snap Store

Austin can be installed on many major Linux distributions from the Snap Store with the following command

sudo snap install austin --classic

On Debian and Derivatives

On March 30 2019 Austin was accepted into the official Debian repositories and can therefore be installed with the apt utility.

sudo apt update -y && sudo apt install austin -y

On macOS

Austin can be installed on macOS using Homebrew:

brew install austin

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 Scoop

To install Austin using Scoop, run the following command from the command line or PowerShell

scoop install austin

To upgrade run the following command from the command line or PowerShell:

scoop update

From Conda Forge

Anaconda users on Linux and macOS can install Austin from [Conda Forge] with the command

conda install -c conda-forge austin

From Sources without autotools

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

On Linux, one can then use the command

gcc -O3 -Os -Wall -pthread src/*.c -o src/austin

whereas on macOS it is enough to run

gcc -O3 -Os -Wall src/*.c -o src/austin

On Windows, the -lpsapi -lntdll switches are needed

gcc -O3 -Os -Wall -lpsapi -lntdll src/*.c -o src/austin

Add -DDEBUG if you need a more verbose log. This is useful if you encounter a bug with Austin and you want to report it here.

Usage

Usage: austin [OPTION...] command [ARG...]
Austin is a frame stack sampler for CPython that is used to extract profiling
data out of a running Python process (and all its children, if required) that
requires no instrumentation and has practically no impact on the tracee.

  -c, --cpu                  Sample on-CPU stacks only.
  -C, --children             Attach to child processes.
  -f, --full                 Produce the full set of metrics (time +mem -mem).
  -g, --gc                   Sample the garbage collector state.
  -i, --interval=n_us        Sampling interval in microseconds (default is
                             100). Accepted units: s, ms, us.
  -m, --memory               Profile memory usage.
  -o, --output=FILE          Specify an output file for the collected samples.
  -p, --pid=PID              Attach to the process with the given PID.
  -P, --pipe                 Pipe mode. Use when piping Austin output.
  -t, --timeout=n_ms         Start up wait time in milliseconds (default is
                             3000). Accepted units: s, ms.
  -w, --where=PID            Dump the stacks of all the threads within the
                             process with the given PID.
  -x, --exposure=n_sec       Sample for n_sec seconds only.
  -?, --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.

Report bugs to <https://github.com/P403n1x87/austin/issues>.

Austin generates binary output in the [MOJO] format. This is a compact binary representation of the collected data that can be processed by the mojo2austin tool that comes with the [austin-python] Python package to produce the more commonly used collapsed stack format. The MOJO format can also be converted to the [Speedscope] JSON format using the austin2speedscope tool that also comes with the [austin-python] Python package. If you use Visual Studio Code, you can use the [Austin VS Code extension] to visualise the profile data directly in the editor.

[!IMPORTANT] If you are running Austin directly in a terminal, make sure to either redirect the output to a file or give a destination file with the -o/--output option to avoid the terminal being flooded with binary data.

Environment variables

Some behaviour of Austin can be configured via environment variables.

Variable	Effect
AUSTIN_NO_LOGGING	Disables all log messages (since Austin 3.4.0).
AUSTIN_PAGE_SIZE_CAP	Cap the page size used to perform remote reads (since Austin 4.0.0).

Column-level Location Information

Since Python 3.11, code objects carry finer-grained location information at the column level. When using the binary MOJO format, Austin can extract this extra location information when profiling code running with versions of the interpreter that expose this data.

Since Austin 3.5.0.

Memory and Full Metrics

When profiling in memory mode with the -m or --memory switch, the metric value associated with each stack is the memory delta between samples, measured in bytes. In full mode (-f or --full switches), each sample will include both a time and memory metric, plus the information of whether the stack was on CPU. This is useful if you want to collect wall-time/CPU-time and memory profiles in a single run.

[!NOTE] The reported memory allocations and deallocations are obtained by computing resident memory deltas between samples. Hence these values give an idea of how much physical memory is being requested/released.

Multi-process Applications

Austin can be told to profile multi-proc