{"id":13460244,"url":"https://github.com/P403n1x87/austin","last_synced_at":"2025-03-24T18:33:30.185Z","repository":{"id":37271345,"uuid":"149680486","full_name":"P403n1x87/austin","owner":"P403n1x87","description":"Python frame stack sampler for CPython","archived":false,"fork":false,"pushed_at":"2024-10-17T21:11:48.000Z","size":39645,"stargazers_count":1881,"open_issues_count":7,"forks_count":54,"subscribers_count":18,"default_branch":"master","last_synced_at":"2024-10-29T15:06:52.797Z","etag":null,"topics":["debugging-tools","performance","profiling","python"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/austin-dist/","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/P403n1x87.png","metadata":{"files":{"readme":"README","changelog":"ChangeLog","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"COPYING","code_of_conduct":"CODE-OF-CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"p403n1x87","patreon":"P403n1x87","custom":["https://www.buymeacoffee.com/Q9C1Hnm28","https://www.paypal.me/gtornetta/1"]}},"created_at":"2018-09-20T23:00:40.000Z","updated_at":"2024-10-28T13:08:06.000Z","dependencies_parsed_at":"2024-01-06T01:04:57.825Z","dependency_job_id":"8cd1a2c6-c5e4-4ea5-83a6-93c129d7b9f3","html_url":"https://github.com/P403n1x87/austin","commit_stats":{"total_commits":288,"total_committers":9,"mean_commits":32.0,"dds":"0.26388888888888884","last_synced_commit":"b48d980f6f3d0808d9221ee611a9c3094e02bb50"},"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/P403n1x87%2Faustin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/P403n1x87%2Faustin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/P403n1x87%2Faustin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/P403n1x87%2Faustin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/P403n1x87","download_url":"https://codeload.github.com/P403n1x87/austin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245078144,"owners_count":20557278,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["debugging-tools","performance","profiling","python"],"created_at":"2024-07-31T10:00:37.989Z","updated_at":"2025-03-24T18:33:30.158Z","avatar_url":"https://github.com/P403n1x87.png","language":"C","funding_links":["https://github.com/sponsors/p403n1x87","https://patreon.com/P403n1x87","https://www.buymeacoffee.com/Q9C1Hnm28","https://www.paypal.me/gtornetta/1","https://github.com/sponsors/P403n1x87"],"categories":["C","Profiling","语言资源库","Python"],"sub_categories":["Python","python","Python tools"],"readme":"\u003cp align=\"center\"\u003e\u003cimg src=\"art/austin_die_cut_sticker.png\" alt=\"Austin\"\u003e\u003c/p\u003e\n\n\u003ch3 align=\"center\"\u003eA Frame Stack Sampler for CPython\u003c/h3\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"art/tux.svg\"\n       height=\"24px\" /\u003e\n  \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\n  \u003cimg src=\"art/apple.svg\" /\u003e\n  \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\n  \u003cimg src=\"art/win.svg\"\n       height=\"24px\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/P403n1x87/austin/actions?query=workflow%3ATests\"\u003e\u003cimg src=\"https://github.com/P403n1x87/austin/actions/workflows/tests.yml/badge.svg\" alt=\"GitHub Action Status: Tests\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/P403n1x87/austin/actions?query=workflow%3AChecks\"\u003e\u003cimg src=\"https://github.com/P403n1x87/austin/actions/workflows/checks.yml/badge.svg\" alt=\"GitHub Action Status: Checks\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://codecov.io/gh/P403n1x87/austin\"\u003e\u003cimg src=\"https://codecov.io/gh/P403n1x87/austin/branch/master/graph/badge.svg?token=OEDWB2IYBR\" alt=\"Code coverage\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/P403n1x87/austin/releases/latest\"\u003e\u003cimg src=\"http://img.shields.io/github/v/release/p403n1x87/austin\" alt=\"latest release\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/P403n1x87/austin/blob/master/LICENSE.md\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-GPLv3-ff69b4.svg\" alt=\"LICENSE\" /\u003e\u003c/a\u003e\n\n  \u003cbr/\u003e\n  \u003ca href=\"https://badge.fury.io/py/austin-dist\"\u003e\u003cimg src=\"https://badge.fury.io/py/austin-dist.svg\" alt=\"PyPI version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://chocolatey.org/packages/austin/\"\u003e\u003cimg src=\"https://img.shields.io/chocolatey/v/austin\" alt=\"Chocolatey Version\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://anaconda.org/conda-forge/austin\"\u003e\u003cimg src=\"https://img.shields.io/conda/vn/conda-forge/austin.svg\" alt=\"Conda Version\" /\u003e\u003c/a\u003e\n  \u003c!-- \u003ca href=\"https://packages.debian.org/unstable/austin\"\u003e\n    \u003cimg src=\"https://badges.debian.net/badges/debian/unstable/austin/version.svg\"\n         alt=\"Debian package status\" /\u003e\n  \u003c/a\u003e --\u003e\n  \u003ca href=\"https://formulae.brew.sh/formula/austin\"\u003e\u003cimg src=\"https://img.shields.io/homebrew/v/austin\" alt=\"homebrew\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://snapcraft.io/austin\"\u003e\u003cimg src=\"https://snapcraft.io/austin/badge.svg\" alt=\"austin Snap Store Build Status\" /\u003e\u003c/a\u003e\n\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://snapcraft.io/austin\" title=\"Get it from the Snap Store\"\u003e\n    \u003cimg src=\"https://snapcraft.io/static/images/badges/en/snap-store-black.svg\"\n         alt=\"Get it from the Snap Store\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#synopsis\"\u003e\u003cb\u003eSynopsis\u003c/b\u003e\u003c/a\u003e\u0026nbsp;\u0026bull;\n  \u003ca href=\"#installation\"\u003e\u003cb\u003eInstallation\u003c/b\u003e\u003c/a\u003e\u0026nbsp;\u0026bull;\n  \u003ca href=\"#usage\"\u003e\u003cb\u003eUsage\u003c/b\u003e\u003c/a\u003e\u0026nbsp;\u0026bull;\n  \u003ca href=\"#cheat-sheet\"\u003e\u003cb\u003eCheat sheet\u003c/b\u003e\u003c/a\u003e\u0026nbsp;\u0026bull;\n  \u003ca href=\"#compatibility\"\u003e\u003cb\u003eCompatibility\u003c/b\u003e\u003c/a\u003e\u0026nbsp;\u0026bull;\n  \u003ca href=\"#why--austin\"\u003e\u003cb\u003eWhy \u003cimg src=\"art/austin_logo.svg\" height=\"20px\" /\u003e Austin\u003c/b\u003e\u003c/a\u003e\u0026nbsp;\u0026bull;\n  \u003ca href=\"#examples\"\u003e\u003cb\u003eExamples\u003c/b\u003e\u003c/a\u003e\u0026nbsp;\u0026bull;\n  \u003ca href=\"#contribute\"\u003e\u003cb\u003eContribute\u003c/b\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.buymeacoffee.com/Q9C1Hnm28\" target=\"_blank\"\u003e\n    \u003cimg src=\"https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png\"\n         alt=\"Buy Me A Coffee\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n----\n\n\u003cp align=\"center\"\u003e\u003ci\u003eThis is the nicest profiler I’ve found for Python. It’s\ncross-platform, doesn’t need me to change the code that’s being profiled, and\nits output can be piped directly into \u003ccode\u003eflamegraph.pl\u003c/code\u003e. I just used it\nto pinpoint a gross misuse of SQLAlchemy at work that’s run in some code at the\nend of each day, and now I can go home earlier.\u003c/i\u003e\u003cbr/\u003e\u003cbr/\u003e-- gthm on \u003ca\nhref=\"https://lobste.rs/s/qairy5/austin_python_frame_stack_sampler_for\"\u003elobste.rs\u003c/a\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003ci\u003eIf people are looking for a profiler, Austin looks pretty\ncool. Check it out!\u003c/i\u003e\u003cbr/\u003e\u003cbr/\u003e-- Michael Kennedy on \u003ca\nhref=\"https://www.youtube.com/watch?v=eFgybynhMrs\"\u003ePython Bytes 180\u003c/a\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e \u003ca href=\"https://twitter.com/AustinSampler\"\u003eFollow \u003cimg\nsrc=\"art/austin_logo.svg\" height=\"20px\" /\u003e on \u003cimg\nsrc=\"https://upload.wikimedia.org/wikipedia/en/thumb/9/9f/Twitter_bird_logo_2012.svg/1024px-Twitter_bird_logo_2012.svg.png\"\nheight=\"18px\" alt=\"Twitter\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n----\n\n\n# Synopsis\n\nAustin is a Python frame stack sampler for CPython written in pure C. Samples\nare collected by reading the CPython interpreter virtual memory space to\nretrieve information about the currently running threads along with the stack of\nthe frames that are being executed. Hence, one can use Austin to easily make\npowerful statistical profilers that have minimal impact on the target\napplication and that don't require any instrumentation.\n\n\nThe key features of Austin are:\n- Zero instrumentation;\n- Minimal impact;\n- Fast and lightweight;\n- Time and memory profiling;\n- Built-in support for multi-process applications (e.g. `mod_wsgi`).\n\nThe simplest way to turn Austin into a full-fledged profiler is to use together\nwith the [VS\nCode](https://marketplace.visualstudio.com/items?itemName=p403n1x87.austin-vscode)\nextension or combine it with [FlameGraph] or [Speedscope]. However, Austin's\nsimple output format can be piped into any other external or custom tool for\nfurther processing. Look, for instance, at the following Python TUI\n\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"art/austin-tui.png\"\n       style=\"box-shadow: #111 0px 0px 16px;\" /\u003e\n\u003c/p\u003e\n\nCheck out [A Survey of Open-Source Python\nProfilers](https://www.usenix.org/system/files/login/articles/login_winter19_12_norton.pdf)\nby Peter Norton for a general overview of Austin.\n\nKeep reading for more tool ideas and examples!\n\n---\n\n\u003cp align=\"center\"\u003e💜\u003c/br\u003e\u003ci\u003eAustin is a free and open-source project. A lot of\neffort goes into its development to ensure the best performance and that it\nstays up-to-date with the latest Python releases. If you find it useful,\nconsider \u003ca href=\"https://github.com/sponsors/P403n1x87\"\u003esponsoring\u003c/a\u003e this\nproject.\u003c/i\u003e\u003c/br\u003e🙏\u003c/p\u003e\n\n---\n\n# Installation\n\nAustin is available to install from [PyPI](pypi) and from the major software\nrepositories of the most popular platforms. Check out the [latest release] page\nfor pre-compiled binaries and installation packages.\n\nOn all supported platforms and architectures, Austin can be installed from PyPI\nwith `pip` or `pipx` via the commands\n\n~~~\npip install austin-dist\n~~~\nor\n~~~\npipx install austin-dist\n~~~\n\nOn Linux, it can be installed using `autotools` or as a snap from the [Snap\nStore](https://snapcraft.io/store). The latter will automatically perform the\nsteps of the `autotools` method with a single command. On distributions derived\nfrom Debian, Austin can be installed from the official repositories with\n`apt`. Anaconda users can install Austin from [Conda Forge].\n\nOn Windows, Austin can be easily installed from the command line using either\n[Chocolatey] or [Scoop]. Alternatively, you can download the installer from the\n[latest release] page.\n\nOn macOS, Austin can be easily installed from the command line using [Homebrew].\nAnaconda users can install Austin from [Conda Forge].\n\nFor any other platforms, compiling Austin from sources is as easy as cloning the\nrepository and running the C compiler. The [Releases][releases] page has many\npre-compiled binaries that are ready to be uncompressed and used.\n\n## With `autotools`\n\nInstalling Austin using `autotools` amounts to the usual `./configure`, `make`\nand `make install` finger gymnastic. The only dependency is the standard C\nlibrary. Before proceeding with the steps below, make sure that the `autotools`\nare installed on your system. Refer to your distro's documentation for details\non how to do so.\n\n~~~ console\ngit clone --depth=1 https://github.com/P403n1x87/austin.git \u0026\u0026 cd austin\nautoreconf --install\n./configure\nmake\nmake install\n~~~\n\n\u003e **NOTE** Some Linux distributions, like Manjaro, might require the execution\n\u003e of `automake --add-missing` before `./configure`.\n\nAlternatively, sources can be compiled with just a C compiler (see below).\n\n\n## From the Snap Store\n\nAustin can be installed on [many major Linux\ndistributions](https://snapcraft.io/docs/installing-snapd) from the Snap Store\nwith the following command\n\n~~~ console\nsudo snap install austin --classic\n~~~\n\n\n## On Debian and Derivatives\n\nOn March 30 2019 Austin was accepted into the official Debian repositories and\ncan therefore be installed with the `apt` utility.\n\n~~~ console\nsudo apt update -y \u0026\u0026 sudo apt install austin -y\n~~~\n\n## On macOS\n\nAustin can be installed on macOS using [Homebrew](https://docs.brew.sh):\n\n~~~ console\nbrew install austin\n~~~\n\n\n## From Chocolatey\n\nTo install [Austin from Chocolatey](https://chocolatey.org/packages/austin), run\nthe following command from the command line or from PowerShell\n\n~~~ console\nchoco install austin\n~~~\n\nTo upgrade run the following command from the command line or from PowerShell:\n\n~~~ console\nchoco upgrade austin\n~~~\n\n\n## From Scoop\n\nTo install Austin using Scoop, run the following command from the command line\nor PowerShell\n\n~~~ console\nscoop install austin\n~~~\n\nTo upgrade run the following command from the command line or PowerShell:\n\n~~~ console\nscoop update\n~~~\n\n\n## From Conda Forge\n\nAnaconda users on Linux and macOS can install Austin from [Conda Forge] with the\ncommand\n\n~~~ console\nconda install -c conda-forge austin\n~~~\n\n## From Sources without `autotools`\n\nTo install Austin from sources using the GNU C compiler, without `autotools`,\nclone the repository with\n\n~~~ console\ngit clone --depth=1 https://github.com/P403n1x87/austin.git\n~~~\n\nOn Linux, one can then use the command\n\n~~~ console\ngcc -O3 -Os -Wall -pthread src/*.c -o src/austin\n~~~\n\nwhereas on macOS it is enough to run\n\n~~~ console\ngcc -O3 -Os -Wall src/*.c -o src/austin\n~~~\n\nOn Windows, the `-lpsapi -lntdll` switches are needed\n\n~~~ console\ngcc -O3 -Os -Wall -lpsapi -lntdll src/*.c -o src/austin\n~~~\n\nAdd `-DDEBUG` if you need a more verbose log. This is useful if you encounter a\nbug with Austin and you want to report it here.\n\n\n# Usage\n\n\u003c!-- [[[cog\nfrom subprocess import check_output\nprint(\"~~~\")\nprint(check_output([\"src/austin\", \"--help\"]).decode().strip())\nprint(\"~~~\")\n]]] --\u003e\n~~~\nUsage: austin [OPTION...] command [ARG...]\nAustin is a frame stack sampler for CPython that is used to extract profiling\ndata out of a running Python process (and all its children, if required) that\nrequires no instrumentation and has practically no impact on the tracee.\n\n  -b, --binary               Emit data in the MOJO binary format. See\n                             https://github.com/P403n1x87/austin/wiki/The-MOJO-file-format\n                             for more details.\n  -C, --children             Attach to child processes.\n  -f, --full                 Produce the full set of metrics (time +mem -mem).\n  -g, --gc                   Sample the garbage collector state.\n  -h, --heap=n_mb            Maximum heap size to allocate to increase sampling\n                             accuracy, in MB (default is 0).\n  -i, --interval=n_us        Sampling interval in microseconds (default is\n                             100). Accepted units: s, ms, us.\n  -m, --memory               Profile memory usage.\n  -o, --output=FILE          Specify an output file for the collected samples.\n  -p, --pid=PID              Attach to the process with the given PID.\n  -P, --pipe                 Pipe mode. Use when piping Austin output.\n  -s, --sleepless            Suppress idle samples to estimate CPU time.\n  -t, --timeout=n_ms         Start up wait time in milliseconds (default is\n                             100). Accepted units: s, ms.\n  -w, --where=PID            Dump the stacks of all the threads within the\n                             process with the given PID.\n  -x, --exposure=n_sec       Sample for n_sec seconds only.\n  -?, --help                 Give this help list\n      --usage                Give a short usage message\n  -V, --version              Print program version\n\nMandatory or optional arguments to long options are also mandatory or optional\nfor any corresponding short options.\n\nReport bugs to \u003chttps://github.com/P403n1x87/austin/issues\u003e.\n~~~\n\u003c!-- [[[end]]] --\u003e\n\nThe output is a sequence of frame stack samples, one on each line. The format is\nthe collapsed one that is recognised by [FlameGraph] so that it can be piped\nstraight to `flamegraph.pl` for a quick visualisation, or redirected to a file\nfor some further processing.\n\nBy default, each line has the following structure:\n\n~~~\nP\u003cpid\u003e;T\u003ciid\u003e:\u003ctid\u003e[;[frame]]* [metric]*\n~~~\n\nwhere the structure of `[frame]` and the number and type of metrics on each line\ndepend on the mode. The `\u003cpid\u003e`, `\u003ciid\u003e` and `\u003ctid\u003e` component represent the\nprocess ID, the sub-interpreter ID, and the thread ID respectively.\n\n\n## Environment variables\n\nSome behaviour of Austin can be configured via environment variables.\n\n| Variable            | Effect                                                      |\n| ------------------- | ----------------------------------------------------------- |\n| `AUSTIN_NO_LOGGING` | Disables all [log messages](#logging) (since Austin 3.4.0). |\n\n\n## Normal Mode\n\nIn normal mode, the `[frame]` part of each emitted sample has the structure\n\n~~~\n[frame] := \u003cmodule\u003e:\u003cfunction\u003e:\u003cline number\u003e\n~~~\n\nEach line then ends with a single `[metric]`, i.e. the sampling time measured in\nmicroseconds.\n\n\n\u003e **NOTE** This was changed in Austin 3. In previous version, the alternative\n\u003e format used to be the default one.\n\n\n## Binary Mode\n\nThe output generated by Austin by default can be quickly visualised by some\nexisting tools without further processing. However, this comes at the cost of\npotentially big raw output files. The binary mode can be used to produce a more\ncompact binary representation of the collected data, and more efficiently, by\nexploiting the performance enhancement of internal caching of frame data.\n\nThe `mojo2austin` CLI tool that comes with the [`austin-python`] Python package\ncan be used to convert a MOJO file back to the standard Austin output. Be aware\nthat the resulting file might be quite large, well over 4 times the size of the\nMOJO file itself.\n\nMore details about the [MOJO] binary format can be found in the [Wiki].\n\n*Since Austin 3.4.0*.\n\n\n## Column-level Location Information\n\nSince Python 3.11, code objects carry finer-grained location information at the\ncolumn level. When using the binary MOJO format, Austin can extract this extra\nlocation information when profiling code running with versions of the\ninterpreter that expose this data.\n\n*Since Austin 3.5.0*.\n\n\n## Memory and Full Metrics\n\nWhen profiling in memory mode with the `-m` or `--memory` switch, the metric\nvalue at the end of each line is the memory delta between samples, measured in\nbytes. In full mode (`-f` or `--full` switches), each sample ends with a\ncomma-separated list of three values: the time delta, the idle state (1 for\nidle, 0 otherwise) and the RSS memory delta (positive for memory allocations,\nnegative for deallocations). This way it is possible to estimate wall-clock\ntime, CPU time and memory pressure, all from a single run.\n\n\u003e **NOTE** The reported memory allocations and deallocations are obtained by\n\u003e computing resident memory deltas between samples. Hence these values give an\n\u003e idea of how much _physical_ memory is being requested/released.\n\n\n## Multi-process Applications\n\nAustin can be told to profile multi-process applications with the `-C` or\n`--children` switch. This way Austin will look for new children of the parent\nprocess.\n\n\n## Sub-interpreters\n\nAustin has support for Python applications that make use of sub-interpreters.\nThis means that Austin will sample all the sub-interpreters that are running\nwithin each process making up the Python application.\n\n*Since Austin 3.6.0*.\n\n\n## Garbage Collector Sampling\n\nAustin can sample the Python garbage collector state for applications running\nwith Python 3.7 and later versions. If the `-g`/`--gc` option is passed, Austin\nwill append `:GC:` at the end of each collected frame stack whenever the garbage\ncollector is collecting. This gives you a measure of how *busy* the Python GC is\nduring a run.\n\n*Since Austin 3.1.0*.\n\n\n## Where?\n\nIf you are only interested in what is currently happening inside a Python\nprocess, you can have a quick overview printed on the terminal with the\n`-w/--where` option. This takes the PID of the process whose threads you want to\ninspect, e.g.\n\n~~~ console\nsudo austin -w `pgrep -f my-running-python-app`\n~~~\n\nBelow is an example of what the output looks like\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"art/austin-where.png\"\n       alt=\"Austin where mode example\"\n       style=\"box-shadow: #111 0px 0px 16px;\" /\u003e\n\u003c/p\u003e\n\nThis works with the `-C/--children` option too. The emojis to the left indicate\nwhether the thread is active or sleeping and whether the process is a child or\nnot.\n\n*Since Austin 3.3.0*.\n\n\n## Sampling Accuracy\n\nAustin tries to keep perturbations to the tracee at a minimum. To do so, the\ntracee is never halted. To improve sampling accuracy, Austin can allocate a heap\nthat is used to get large snapshots of the private VM of the tracee that is\nlikely to contain frame information in a single attempt. The larger the heap is\nallowed the grow, the more accurate the results. The maximum size of the heap\nthat Austin is allowed to allocate can be controlled with the `-h/--heap`\noption, followed by the maximum size in bytes. By default, Austin does not\nallocate a heap, which is ideal for systems with limited resources. If you think\nyour results are not accurate, try setting this parameter.\n\n*Since Austin 3.2.0*.\n\n*Changed in Austin 3.3.0*: the default heap size is 0.\n\n\n## Native Frame Stack\n\nIf you want observability into the native frame stacks, you can use the\n`austinp` variant of `austin` which can be obtained by compiling the source\nwith `-DAUSTINP` on Linux, or from the released binaries.\n\n`austinp` makes use of `ptrace` to halt the application and grab a\nsnapshot of the call stack with `libunwind`. If you are compiling `austinp` from\nsources make sure that you have the development version of the `libunwind`\nlibrary available on your system, for example on Ubuntu,\n\n~~~ console\nsudo apt install libunwind-dev binutils-dev\n~~~\n\nand compile with\n\n~~~ console\ngcc -O3 -Os -Wall -pthread src/*.c -DAUSTINP -lunwind-ptrace -lunwind-generic -lbfd -o src/austinp\n~~~\n\nthen use as per normal. The extra `-k/--kernel` option is available with\n`austinp` which allows sampling kernel call stacks as well.\n\n\u003e **WARNING** Since `austinp` uses `ptrace`, the impact on the tracee is no\n\u003e longer minimal and it becomes higher at smaller sampling intervals. Therefore\n\u003e the use of `austinp` is not recommended in production environments. For this\n\u003e reason, the default sampling interval for `austinp` is 10 milliseconds.\n\nThe `austinp-resolve` tool from the [`austin-python`] Python package can be used\nto resolve the VM addresses to source and line numbers, provided that the\nreferenced binaries have DWARF debug symbols. Internally, the tool uses\n`addr2line(1)` to determine the source name and line number given an address,\nwhen possible.\n\n\u003e Whilst `austinp` comes with a stripped-down implementation of `addr2line`, it\n\u003e is only used for the \"where\" option, as resolving symbols at runtime is\n\u003e expensive. This is to minimise the impact of austinp on the tracee, increase\n\u003e accuracy and maximise the sampling rate.\n\nThe [where](#where) option is also available for the `austinp` variant and will\nshow both native and Python frames. Highlighting helps tell frames apart. The\n`-k` option outputs Linux kernel frames too, as shown in this example\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"art/austin-where-kernel.png\"\n       alt=\"Austin where mode example\"\n       style=\"box-shadow: #111 0px 0px 16px;\" /\u003e\n\u003c/p\u003e\n\n\u003e **NOTE** If you have installed Austin from the Snap Store, the `austinp`\n\u003e executable will be available as `austin.p` from the command line.\n\n\n## Logging\n\nAustin uses `syslog` on Linux and macOS, and `%TEMP%\\austin.log` on Windows\nfor log messages, so make sure to watch these to get execution details and\nstatistics. _Bad_ frames are output together with the other frames. In general,\nentries for bad frames will not be visible in a flame graph as all tests show\nerror rates below 1% on average.\n\nLogging can be disabled using [environment variables](#environment-variables).\n\n\n## Cheat sheet\n\nAll the above Austin options and arguments are summarised in a cheat sheet that\nyou can find in the [doc](https://github.com/P403n1x87/austin/blob/master/doc/)\nfolder in either the SVG, PDF or PNG format\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"doc/cheatsheet.png\"\n       style=\"box-shadow: #111 0px 0px 16px;\" /\u003e\n\u003c/p\u003e\n\n# Compatibility\n\nAustin supports Python 3.8 through 3.13, and has been tested on the following\nplatforms and architectures\n\n|             | \u003cimg src=\"art/tux.svg\" /\u003e | \u003cimg src=\"art/win.svg\"/\u003e | \u003cimg src=\"art/apple.svg\"/\u003e |\n| ----------- | ------------------------- | ------------------------ | -------------------------- |\n| **x86_64**  | ✓                         | ✓                        | ✓                          |\n| **i686**    | ✓                         |                          | ✓                          |\n| **armv7**   | ✓                         |                          |                            |\n| **arm64**   | ✓                         |                          | ✓                          |\n| **ppc64le** | ✓                         |                          |                            |\n\n\u003e **NOTE** Austin *might* work with other versions of Python on all the\n\u003e platforms and architectures above. So it is worth giving it a try even if\n\u003e your system is not listed below. If you are looking for support for Python \u003c\n\u003e 3.8, you can use Austin 3.5.\n\nBecause of platform-specific details, Austin usage may vary slightly. Below are\nfurther compatibility details to be aware of.\n\n\n## On Linux\n\nAustin requires the `CAP_SYS_PTRACE` capability to attach to an external\nprocess. This means that you will have to either use ``sudo`` when attaching to\na running Python process or grant the CAP_SYS_PTRACE capability to the Austin\nbinary with, e.g.\n\n~~~ console\nsudo setcap cap_sys_ptrace+ep `which austin`\n~~~\n\nTo use Austin with Docker, the `--cap-add SYS_PTRACE` option needs to be passed\nwhen starting a container.\n\n\n## On MacOS\n\nDue to the **System Integrity Protection**, introduced in **MacOS** with El\nCapitan, and the [Hardened Runtime][hardened runtime], introduced in Mojave,\nAustin cannot profile Python processes that use an executable located in the\n`/bin` folder, or code-signed, even with `sudo`. This is the case for the\nsystem-provided version of Python, and the one installed with the official\ninstallers from [python.org](https://python.org). Other installation methods,\nlike [pyenv][pyenv] or [Anaconda][anaconda] or\n[Homebrew](https://formulae.brew.sh/formula/austin) are known to work with\nAustin, out of the box.\n\nTo use Austin with Python from the official installer, you could remove the\nsignature from the binaries with\n~~~ console\ncodesign --remove-signature /Library/Frameworks/Python.framework/Versions/\u003cM.m\u003e/bin/python3\ncodesign --remove-signature /Library/Frameworks/Python.framework/Versions/\u003cM.m\u003e/Resources/Python.app/Contents/MacOS/Python\n~~~\nAlternatively, you could self-sign the Austin binary with the [Debugging Tool\nEntitlement][dte], as done for debugging tools like GDB. However, this method\nhas not been tested.\n\n\u003e Austin requires the use of `sudo` to work on MacOS. To avoid having to type\n\u003e the password every time you use Austin, consider adding a rule to the\n\u003e `sudoers` file, e.g.\n\u003e ~~~\n\u003e yourusername  ALL = (root) NOPASSWD: /usr/local/bin/austin\n\u003e ~~~\n\n\n# Why Austin\n\nWhen there already are similar tools out there, it's normal to wonder why one\nshould be interested in yet another one. So here is a list of features that\ncurrently distinguish Austin.\n\n- **Written in pure C** Austin is written in pure C code. There are no\n  dependencies on third-party libraries except for the standard C library and\n  the API provided by the Operating System.\n\n- **Just a sampler** Austin is just a frame stack sampler. It looks into a\n  running Python application at regular intervals of time and dumps whatever\n  frame stack it finds. The samples can then be analysed at a later time so that\n  Austin can sample at rates higher than other non-C alternatives that perform\n  some aggregations at run-time.\n\n- **Simple output, powerful tools** Austin uses the collapsed stack format of\n  FlameGraph that is easy to parse. You can then go and build your own tool to\n  analyse Austin's output. You could even make a _player_ that replays the\n  application execution in slow motion, so that you can see what has happened in\n  temporal order.\n\n- **Small size** Austin compiles to a single binary executable of just a bunch\nof KB.\n\n- **Easy to maintain** Occasionally, the Python C API changes and Austin will\nneed to be adjusted to new releases. However, given that Austin, like CPython,\nis written in C, implementing the new changes is rather straight-forward.\n\n\n# Examples\n\nThe following flame graph has been obtained with the command\n\n~~~ console\naustin -i 1ms ./test.py | sed '/^#/d' | ./flamegraph.pl --countname=μs \u003e test.svg\n~~~\n\nwhere the sample `test.py` script has the execute permission and the following\ncontent\n\n~~~ python\n#!/usr/bin/env python3\n\nimport dis\n\nfor i in range(1000):\n    dis.dis(dis.dis)\n~~~\n\n\u003cobject data=\"art/dis_fg.svg\" type=\"image/svg+xml\" width=\"100%\" \u003e\n  \u003cimg src=\"art/dis_fg.svg\" style=\"width:100%;\"/\u003e\n\u003c/object\u003e\n\nTo profile Apache2 WSGI application, one can attach Austin to the web server\nwith\n\n~~~ console\naustin -Cp `pgrep apache2 | head -n 1`\n~~~\n\nAny child processes will be automatically detected as they are created and\nAustin will sample them too.\n\n\n## IDE Extensions\n\nIt is easy to write your own extension for your favourite text editor. This, for\nexample, is a demo of a [Visual Studio Code] extension that highlights the most\nhit lines of code straight into the editor\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"art/vscode-demo.gif\"\n       style=\"box-shadow: #111 0px 0px 16px;\" /\u003e\n\u003c/p\u003e\n\n\n## Austin TUI\n\nThe [Austin TUI] is a text-based user interface for Austin that gives you a\ntop-like view of what is currently running inside a Python application. It is\nmost useful for scripts that have long-running procedures as you can see where\nexecution is at without tracing instructions in your code. You can also save the\ncollected data from within the TUI and feed it to Flame Graph for visualisation,\nor convert it to the [pprof] format.\n\nIf you want to give it a go you can install it using `pip` with\n\n~~~ console\npip install austin-tui --upgrade\n~~~\n\nand run it with\n\n~~~ console\naustin-tui [OPTION...] command [ARG...]\n~~~\n\nwith the same command line as Austin. Please note that the `austin` binary\nshould be available from within the `PATH` environment variable in order for the\nTUI to work.\n\n\u003e The TUI is based on `python-curses`. The version included with the standard\n\u003e Windows installations of Python is broken so it won't work out of the box. A\n\u003e solution is to install the wheel of the port to Windows from\n\u003e [this](https://www.lfd.uci.edu/~gohlke/pythonlibs/#curses) page. Wheel files\n\u003e can be installed directly with `pip`, as described in the\n\u003e [linked](https://pip.pypa.io/en/latest/user_guide/#installing-from-wheels)\n\u003e page.\n\n\u003c!-- ![austin-tui thread navigation](art/austin-tui_threads_nav.gif) --\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"art/austin-tui.gif\"\n       style=\"box-shadow: #111 0px 0px 16px;\" /\u003e\n\u003c/p\u003e\n\n\n## Austin Web\n\n[Austin Web] is a web application that wraps around Austin. At its core, Austin\nWeb is based on [d3-flame-graph] to display a _live_ flame graph in the browser,\nthat refreshes every 3 seconds with newly collected samples. Austin Web can also\nbe used for _remote_ profiling by setting the `--host` and `--port` options.\n\nIf you want to give it a go you can install it using `pip` with\n\n~~~ console\npip install austin-web --upgrade\n~~~\n\nand run it with\n\n~~~ console\naustin-web [OPTION...] command [ARG...]\n~~~\n\nwith the same command line as Austin. This starts a simple HTTP server that\nserves on `localhost` by default. When no explicit port is given, Austin Web\nwill use an ephemeral one.\n\nPlease note that the `austin` binary should be available from within the `PATH`\nenvironment variable in order for Austin Web to work.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"art/austin-web.gif\"\n       style=\"box-shadow: #111 0px 0px 16px;\" /\u003e\n\u003c/p\u003e\n\n\n## Speedscope\n\nAustin output is now supported by [Speedscope]. However, the [`austin-python`]\nlibrary comes with format conversion tools that allow converting the output from\nAustin to the Speedscope JSON format.\n\nIf you want to give it a go you can install it using `pip` with\n\n~~~ console\npip install austin-python --upgrade\n~~~\n\nand run it with\n\n~~~ console\naustin2speedscope [-h] [--indent INDENT] [-V] input output\n~~~\n\nwhere `input` is a file containing the output from Austin and `output` is the\nname of the JSON file to use to save the result of the conversion, ready to be\nused on [Speedscope].\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"art/speedscope.png\"\n       style=\"box-shadow: #111 0px 0px 16px;\" /\u003e\n\u003c/p\u003e\n\n## Google pprof\n\nAustin's format can also be converted to the Google pprof format using the\n`austin2pprof` utility that comes with [`austin-python`]. If you want to give it\na go you can install it using `pip` with\n\n~~~ console\npip install austin-python --upgrade\n~~~\n\nand run it with\n\n~~~ console\naustin2pprof [-h] [-V] input output\n~~~\n\nwhere `input` is a file containing the output from Austin and `output` is the\nname of the protobuf file to use to save the result of the conversion, ready to\nbe used with [Google's pprof tools][pprof].\n\n\n# Contribute\n\nIf you like Austin and you find it useful, there are ways for you to contribute.\n\nIf you want to help with the development, then have a look at the open issues\nand have a look at the [contributing guidelines](CONTRIBUTING.md) before you\nopen a pull request.\n\nYou can also contribute to the development of the Austin by becoming a sponsor\nand/or by [buying me a coffee](https://www.buymeacoffee.com/Q9C1Hnm28) on BMC or\nby chipping in a few pennies on [PayPal.Me](https://www.paypal.me/gtornetta/1).\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.buymeacoffee.com/Q9C1Hnm28\"\n     target=\"_blank\"\u003e\n  \u003cimg src=\"https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png\"\n       alt=\"Buy Me A Coffee\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\n----\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://twitter.com/AustinSampler\"\u003e\n    Follow \u003cimg src=\"art/austin_logo.svg\" height=\"20px\" /\u003e on \u003cimg src=\"https://upload.wikimedia.org/wikipedia/en/thumb/9/9f/Twitter_bird_logo_2012.svg/1024px-Twitter_bird_logo_2012.svg.png\" height=\"18px\" alt=\"Twitter\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\n[anaconda]: https://www.anaconda.com/\n[`austin-python`]: https://github.com/P403n1x87/austin-python\n[Austin TUI]: https://github.com/P403n1x87/austin-tui\n[Austin Web]: https://github.com/P403n1x87/austin-web\n[Chocolatey]: https://chocolatey.org/\n[Conda Forge]: https://anaconda.org/conda-forge/austin\n[d3-flame-graph]: https://github.com/spiermar/d3-flame-graph\n[dte]: https://developer.apple.com/documentation/bundleresources/entitlements/com_apple_security_cs_debugger\n[FlameGraph]: https://github.com/brendangregg/FlameGraph\n[hardened runtime]: https://developer.apple.com/documentation/security/hardened_runtime\n[Homebrew]: https://formulae.brew.sh/formula/austin\n[latest release]: https://github.com/P403n1x87/austin/releases/latest\n[MOJO]: https://github.com/P403n1x87/austin/wiki/The-MOJO-file-format\n[pprof]: https://github.com/google/pprof\n[pyenv]: https://github.com/pyenv/pyenv\n[pypi]: https://pypi.org/project/austin-dist/\n[releases]: https://github.com/P403n1x87/austin/releases\n[Scoop]: https://scoop.sh/\n[Speedscope]: https://speedscope.app\n[Visual Studio Code]: https://marketplace.visualstudio.com/items?itemName=p403n1x87.austin-vscode\n[Wiki]: https://github.com/P403n1x87/austin/wiki\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FP403n1x87%2Faustin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FP403n1x87%2Faustin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FP403n1x87%2Faustin/lists"}