delroth/austin-python

Python wrapper for Austin, the CPython frame stack sampler.

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:

from austin.aio import AsyncAustin


# Make your sub-class of AsyncAustin
class EchoAsyncAustin(AsyncAustin):
    def on_ready(self, process, child_process, command_line):
        print(f"Austin PID: {process.pid}")
        print(f"Python PID: {child_process.pid}")
        print(f"Command Line: {command_line}")

    def on_sample_received(self, line):
        print(line)

    def on_terminate(self, data):
        print(data)


# Use the Proactor event loop on Windows
if sys.platform == "win32":
    asyncio.set_event_loop(asyncio.ProactorEventLoop())

try:
    # Start the Austin application with some command line arguments
    austin = EchoAsyncAustin()
    asyncio.get_event_loop().run_until_complete(
        austin.start(["-i", "10000", "python3", "myscript.py"])
    )
except (KeyboardInterrupt, asyncio.CancelledError):
    pass

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. For example, to convert the Austin profile data file myscript.aprof to the Google pprof data file myscript.pprof, you can run

austin2pprof myscript.aprof myscript.pprof

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

Compatibility

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

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.