Python wrapper for Austin

Synopsis • Installation • Usage • Compatibility • Documentation • Contribute

Synopsis

The austin-python package is a Python wrapper around the Austin binary that provides convenience classes to quickly develop your statistical profiling tools. Whether your code is thread-based or asynchronous, austin-python has you covered. This is, for instance, how you would turn Austin into a Python application:

import asyncio
import sys

from austin.aio import AsyncAustin
from austin.format.collapsed_stack import AustinEventCollapsedStackFormatter

FORMATTER = AustinEventCollapsedStackFormatter()


class CollapsedStackAsyncAustin(AsyncAustin):
    async def on_sample(self, sample):
        print(FORMATTER.format(sample))

    async def on_metadata(self, metadata):
        print(FORMATTER.format(metadata))


if sys.platform == "win32":
    asyncio.set_event_loop(asyncio.ProactorEventLoop())


async def main():
    austin = CollapsedStackAsyncAustin()
    await austin.start(["-i", "10ms", "python", "myscript.py"])
    await austin.wait()


asyncio.run(main())

The austin-python package is at the heart of the Austin TUI and the Austin Web Python applications. Go check them out if you are looking for full-fledged usage examples.

Included with the package come two applications for the conversion of Austin collected output, which is in the form of collapsed stacks, to either the Speedscope JSON format or the Google pprof format. Note, however, that the Speedscope web application supports Austin native format directly.

Installation

This package can be installed from PyPI with

pip install --user austin-python --upgrade

Please note that austin-python requires the Austin binary. The default lookup locations are, in order,

• current working directory;
• the AUSTINPATH environment variable which gives the path to the folder that contains the Austin binary;
• the .austinrc TOML configuration file in the user's home folder, e.g. ~/.austinrc on Linux (see below for a sample .austinrc file);
• the PATH environment variable.

A sample .austinrc file would look like so

binary = "/path/to/austin"

Usage

A simple example of an echo application was shown above. Other examples using, e.g., threads, can be found in the official documentation. You can also browse through the code of the Austin TUI and the Austin Web Python applications to see how they leverage austin-python.

Format conversion

As it was mentioned before, this package also comes with two scripts for format conversion, namely austin2speedscope and austin2pprof. They both take two mandatory arguments, that is, the input and output file. The input file can be either in the MOJO binary format (the default output of Austin 4) or in the collapsed stack format, and is detected automatically. For example, to convert the Austin profile data file myscript.mojo to the Google pprof data file myscript.pprof, you can run

austin2pprof myscript.mojo myscript.pprof

The package also provide the austin-compress utility to compress the Austin raw samples by aggregation.

Querying profiles

The austin.query module provides the ProfileQuery class to answer the most common questions about a profile, like which functions are the hottest, what the sampled stacks are, or who calls a given function:

from austin.query import ProfileQuery

q = ProfileQuery.from_file("myscript.mojo")

print(q.top(10))                       # hottest functions
print(q.callers("db.py:execute"))      # who calls execute
print(q.filter(thread="main").tree())  # call tree of the main thread

Every result renders as a text table when printed, and can be converted to JSON-ready data with to_dict(). For asyncio profiles (Python 3.14+), q.tasks() shows the task trees, q.task_stacks("worker-0") where a task was running and awaiting, and q.filter(task="worker-0") narrows any query down to the samples in which a task was running.

The same queries are available from the command line with austin-query:

austin-query myscript.mojo top -n 10
austin-query myscript.mojo callers db.py:execute --thread main
austin-query myscript.mojo tasks --json
austin-query myscript.mojo task-stacks worker-0  # where a task ran and awaited

Run austin-query --help for the selector syntax and a suggested workflow.

Compatibility

The latest austin-python package is tested on Linux, macOS and Windows with Python 3.11-3.15.

Documentation

The official documentation is hosted on readthedocs.io at austin-python.readthedocs.io.

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 by either becoming a Patron on Patreon, by buying me a coffee on BMC or by chipping in a few pennies on PayPal.Me.