Package: austin-dist
A Frame Stack Sampler for CPythonSynopsis•Installation•Usage•Cheat sheet•Compatibility•WhyAustin•Examples•ContributeThis 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 intoflamegraph.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 onlobste.rsIf people are looking for a profiler, Austin looks pretty
cool. Check it out!-- Michael Kennedy onPython Bytes 180FollowonSynopsisAustin 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 theVS
Codeextension or combine it withFlameGraphorSpeedscope. However, Austin's
simple output format can be piped into any other external or custom tool for
further processing. Look, for instance, at the following Python TUICheck outA Survey of Open-Source Python
Profilersby 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,
considersponsoringthis
project.🙏InstallationAustin is available to install fromPyPIand from the major software
repositories of the most popular platforms. Check out thelatest releasepage
for pre-compiled binaries and installation packages.On all supported platforms and architectures, Austin can be installed from PyPI
withpiporpipxvia the commandspip install austin-distorpipx install austin-distOn Linux, it can be installed usingautotoolsor as a snap from theSnap
Store. The latter will automatically perform the
steps of theautotoolsmethod with a single command. On distributions derived
from Debian, Austin can be installed from the official repositories with
Aptitude. Anaconda users can install Austin fromConda Forge.On Windows, Austin can be easily installed from the command line using eitherChocolateyorScoop. Alternatively, you can download the installer from thelatest releasepage.On macOS, Austin can be easily installed from the command line usingHomebrew.
Anaconda users can install Austin fromConda Forge.For any other platforms, compiling Austin from sources is as easy as cloning the
repository and running the C compiler. TheReleasespage has many
pre-compiled binaries that are ready to be uncompressed and used.WithautotoolsInstalling Austin usingautotoolsamounts to the usual./configure,makeandmake installfinger gymnastic. The only dependency is the standard C
library. Before proceeding with the steps below, make sure that theautotoolsare 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 austinautoreconf --install./configuremakemake installNOTESome Linux distributions, like Manjaro, might require the execution
ofautomake --add-missingbefore./configure.Alternatively, sources can be compiled with just a C compiler (see below).From the Snap StoreAustin can be installed onmany major Linux
distributionsfrom the Snap Store
with the following commandsudo snap install austin --classicOn Debian and DerivativesOn March 30 2019 Austin was accepted into the official Debian repositories and
can therefore be installed with theaptutility.sudo apt-get update -y && sudo apt-get install austin -yOn macOSAustin can be installed on macOS usingHomebrew:brew install austinFrom ChocolateyTo installAustin from Chocolatey, run
the following command from the command line or from PowerShellchoco install austinTo upgrade run the following command from the command line or from PowerShell:choco upgrade austinFrom ScoopTo install Austin using Scoop, run the following command from the command line
or PowerShellscoop install austinTo upgrade run the following command from the command line or PowerShell:scoop updateFrom Conda ForgeAnaconda users on Linux and macOS can install Austin fromConda Forgewith the
commandconda install -c conda-forge austinFrom Sources withoutautotoolsTo install Austin from sources using the GNU C compiler, withoutautotools,
clone the repository withgit clone --depth=1 https://github.com/P403n1x87/austin.gitOn Linux, one can then use the commandgcc -O3 -Os -Wall -pthread src/*.c -o src/austinwhereas on macOS it is enough to rungcc -O3 -Os -Wall src/*.c -o src/austinOn Windows, the-lpsapi -lntdllswitches are neededgcc -O3 -Os -Wall -lpsapi -lntdll src/*.c -o src/austinAdd-DDEBUGif you need a more verbose log. This is useful if you encounter a
bug with Austin and you want to report it here.UsageUsage: 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.

  -b, --binary               Emit data in the MOJO binary format. See
                             https://github.com/P403n1x87/austin/wiki/The-MOJO-file-format
                             for more details.
  -C, --children             Attach to child processes.
  -e, --exclude-empty        Do not output samples of threads with no frame
                             stacks.
  -f, --full                 Produce the full set of metrics (time +mem -mem).
  -g, --gc                   Sample the garbage collector state.
  -h, --heap=n_mb            Maximum heap size to allocate to increase sampling
                             accuracy, in MB (default is 0).
  -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.
  -s, --sleepless            Suppress idle samples to estimate CPU time.
  -t, --timeout=n_ms         Start up wait time in milliseconds (default is
                             100). 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>.The output is a sequence of frame stack samples, one on each line. The format is
the collapsed one that is recognised byFlameGraphso that it can be piped
straight toflamegraph.plfor a quick visualisation, or redirected to a file
for some further processing.By default, each line has the following structure:P<pid>;T<iid>:<tid>[;[frame]]* [metric]*where the structure of[frame]and the number and type of metrics on each line
depend on the mode. The<pid>,<iid>and<tid>component represent the
process ID, the sub-interpreter ID, and the thread ID respectively.Environment variablesSome behaviour of Austin can be configured via environment variables.VariableEffectAUSTIN_NO_LOGGINGDisables alllog messages(since Austin 3.4.0).Normal ModeIn normal mode, the[frame]part of each emitted sample has the structure[frame] := <module>:<function>:<line number>Each line then ends with a single[metric], i.e. the sampling time measured in
microseconds.NOTEThis was changed in Austin 3. In previous version, the alternative
format used to be the default one.Binary ModeThe output generated by Austin by default can be quickly visualised by some
existing tools without further processing. However, this comes at the cost of
potentially big raw output files. The binary mode can be used to produce a more
compact binary representation of the collected data, and more efficiently, by
exploiting the performance enhancement of internal caching of frame data.Themojo2austinCLI tool that comes with theaustin-pythonPython package
can be used to convert a MOJO file back to the standard Austin output. Be aware
that the resulting file might be quite large, well over 4 times the size of the
MOJO file itself.More details about theMOJObinary format can be found in theWiki.Since Austin 3.4.0.Column-level Location InformationSince 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 MetricsWhen profiling in memory mode with the-mor--memoryswitch, the metric
value at the end of each line is the memory delta between samples, measured in
bytes. In full mode (-for--fullswitches), each sample ends with a
comma-separated list of three values: the time delta, the idle state (1 for
idle, 0 otherwise) and the RSS memory delta (positive for memory allocations,
negative for deallocations). This way it is possible to estimate wall-clock
time, CPU time and memory pressure, all from a single run.NOTEThe reported memory allocations and deallocations are obtained by
computing resident memory deltas between samples. Hence these values give an
idea of how muchphysicalmemory is being requested/released.Multi-process ApplicationsAustin can be told to profile multi-process applications with the-Cor--childrenswitch. This way Austin will look for new children of the parent
process.Sub-interpretersAustin has support for Python applications that make use of sub-interpreters.
This means that Austin will sample all the sub-interpreters that are running
within each process making up the Python application.Since Austin 3.6.0.Garbage Collector SamplingAustin can sample the Python garbage collector state for applications running
with Python 3.7 and later versions. If the-g/--gcoption is passed, Austin
will append:GC:at the end of each collected frame stack whenever the garbage
collector is collecting. This gives you a measure of howbusythe Python GC is
during a run.Since Austin 3.1.0.Where?If you are only interested in what is currently happening inside a Python
process, you can have a quick overview printed on the terminal with the-w/--whereoption. This takes the PID of the process whose threads you want to
inspect, e.g.sudo austin -w `pgrep -f my-running-python-app`Below is an example of what the output looks likeThis works with the-C/--childrenoption too. The emojis to the left indicate
whether the thread is active or sleeping and whether the process is a child or
not.Since Austin 3.3.0.Sampling AccuracyAustin tries to keep perturbations to the tracee at a minimum. To do so, the
tracee is never halted. To improve sampling accuracy, Austin can allocate a heap
that is used to get large snapshots of the private VM of the tracee that is
likely to contain frame information in a single attempt. The larger the heap is
allowed the grow, the more accurate the results. The maximum size of the heap
that Austin is allowed to allocate can be controlled with the-h/--heapoption, followed by the maximum size in bytes. By default, Austin does not
allocate a heap, which is ideal for systems with limited resources. If you think
your results are not accurate, try setting this parameter.Since Austin 3.2.0.Changed in Austin 3.3.0: the default heap size is 0.Native Frame StackIf you want observability into the native frame stacks, you can use theaustinpvariant ofaustinwhich can be obtained by compiling the source
with-DAUSTINPon Linux, or from the released binaries.austinpmakes use ofptraceto halt the application and grab a
snapshot of the call stack withlibunwind. If you are compilingaustinpfrom
sources make sure that you have the development version of thelibunwindlibrary available on your system, for example on Ubuntu,sudo apt install libunwind-dev binutils-devand compile withgcc -O3 -Os -Wall -pthread src/*.c -DAUSTINP -lunwind-ptrace -lunwind-generic -lbfd -o src/austinpthen use as per normal. The extra-k/--kerneloption is available withaustinpwhich allows sampling kernel call stacks as well.WARNINGSinceaustinpusesptrace, the impact on the tracee is no
longer minimal and it becomes higher at smaller sampling intervals. Therefore
the use ofaustinpis not recommended in production environments. For this
reason, the default sampling interval foraustinpis 10 milliseconds.Theaustinp-resolvetool from theaustin-pythonPython package can be used
to resolve the VM addresses to source and line numbers, provided that the
referenced binaries have DWARF debug symbols. Internally, the tool usesaddr2line(1)to determine the source name and line number given an address,
when possible.Whilstaustinpcomes with a stripped-down implementation ofaddr2line, it
is only used for the "where" option, as resolving symbols at runtime is
expensive. This is to minimise the impact of austinp on the tracee, increase
accuracy and maximise the sampling rate.Thewhereoption is also available for theaustinpvariant and will
show both native and Python frames. Highlighting helps tell frames apart. The-koption outputs Linux kernel frames too, as shown in this exampleNOTEIf you have installed Austin from the Snap Store, theaustinpexecutable will be available asaustin.pfrom the command line.LoggingAustin usessyslogon Linux and macOS, and%TEMP%\austin.logon Windows
for log messages, so make sure to watch these to get execution details and
statistics.Badframes 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.Logging can be disabled usingenvironment variables.Cheat sheetAll the above Austin options and arguments are summarised in a cheat sheet that
you can find in thedocfolder in either the SVG, PDF or PNG formatCompatibilityAustin supports Python 3.8 through 3.12, and has been tested on the following
platforms and architecturesx86_64✓✓✓i686✓✓armv7✓arm64✓✓ppc64le✓NOTEAustinmightwork 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. If you are looking for support for Python <
3.8, you can use Austin 3.5.Because of platform-specific details, Austin usage may vary slightly. Below are
further compatibility details to be aware of.On LinuxAustin requires theCAP_SYS_PTRACEcapability to attach to an external
process. This means that you will have to either usesudowhen attaching to
a running Python process or grant the CAP_SYS_PTRACE capability to the Austin
binary with, e.g.sudo setcap cap_sys_ptrace+ep `which austin`To use Austin with Docker, the--cap-add SYS_PTRACEoption needs to be passed
when starting a container.On MacOSDue to theSystem Integrity Protection, introduced inMacOSwith El
Capitan, and theHardened Runtime, introduced in Mojave,
Austin cannot profile Python processes that use an executable located in the/binfolder, or code-signed, even withsudo. This is the case for the
system-provided version of Python, and the one installed with the official
installers frompython.org. Other installation methods,
likepyenvorAnacondaorHomebreware known to work with
Austin, out of the box.To use Austin with Python from the official installer, you could remove the
signature from the binaries withcodesign --remove-signature /Library/Frameworks/Python.framework/Versions/<M.m>/bin/python3codesign --remove-signature /Library/Frameworks/Python.framework/Versions/<M.m>/Resources/Python.app/Contents/MacOS/PythonAlternatively, you could self-sign the Austin binary with theDebugging Tool
Entitlement, as done for debugging tools like GDB. However, this method
has not been tested.Austin requires the use ofsudoto work on MacOS. To avoid having to type
the password every time you use Austin, consider adding a rule to thesudoersfile, e.g.yourusername  ALL = (root) NOPASSWD: /usr/local/bin/austinWhy AustinWhen 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 except for 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 alternatives that perform
some aggregations at run-time.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 aplayerthat 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.ExamplesThe following flame graph has been obtained with the commandaustin -i 1ms ./test.py | sed '/^#/d' | ./flamegraph.pl --countname=μs > test.svgwhere the sampletest.pyscript has the execute permission and the following
content#!/usr/bin/env python3importdisforiinrange(1000):dis.dis(dis.dis)To profile Apache2 WSGI application, one can attach Austin to the web server
withaustin -Cp `pgrep apache2 | head -n 1`Any child processes will be automatically detected as they are created and
Austin will sample them too.IDE ExtensionsIt is easy to write your own extension for your favourite text editor. This, for
example, is a demo of aVisual Studio Codeextension that highlights the most
hit lines of code straight into the editorAustin TUITheAustin TUIis a text-based user interface for Austin that gives you a
top-like view of what is currently running inside a Python application. It is
most useful for scripts that have long-running procedures as you can see where
execution is at without tracing instructions in your code. You can also save the
collected data from within the TUI and feed it to Flame Graph for visualisation,
or convert it to thepprofformat.If you want to give it a go you can install it usingpipwithpip install austin-tui --upgradeand run it withaustin-tui [OPTION...] command [ARG...]with the same command line as Austin. Please note that theaustinbinary
should be available from within thePATHenvironment variable in order for the
TUI to work.The TUI is based onpython-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 wheel of the port to Windows fromthispage. Wheel files
can be installed directly withpip, as described in thelinkedpage.Austin WebAustin Webis a web application that wraps around Austin. At its core, Austin
Web is based ond3-flame-graphto display aliveflame graph in the browser,
that refreshes every 3 seconds with newly collected samples. Austin Web can also
be used forremoteprofiling by setting the--hostand--portoptions.If you want to give it a go you can install it usingpipwithpip install austin-web --upgradeand run it withaustin-web [OPTION...] command [ARG...]with the same command line as Austin. This starts a simple HTTP server that
serves onlocalhostby default. When no explicit port is given, Austin Web
will use an ephemeral one.Please note that theaustinbinary should be available from within thePATHenvironment variable in order for Austin Web to work.SpeedscopeAustin output is now supported bySpeedscope. However, theaustin-pythonlibrary comes with format conversion tools that allow converting the output from
Austin to the Speedscope JSON format.If you want to give it a go you can install it usingpipwithpip install austin-python --upgradeand run it withaustin2speedscope [-h] [--indent INDENT] [-V] input outputwhereinputis a file containing the output from Austin andoutputis the
name of the JSON file to use to save the result of the conversion, ready to be
used onSpeedscope.Google pprofAustin's format can also be converted to the Google pprof format using theaustin2pprofutility that comes withaustin-python. If you want to give it
a go you can install it usingpipwithpip install austin-python --upgradeand run it withaustin2pprof [-h] [-V] input outputwhereinputis a file containing the output from Austin andoutputis the
name of the protobuf file to use to save the result of the conversion, ready to
be used withGoogle's pprof tools.ContributeIf 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 thecontributing guidelinesbefore you
open a pull request.You can also contribute to the development of the Austin by becoming a sponsor
and/or bybuying me a coffeeon BMC or
by chipping in a few pennies onPayPal.Me.Followon