Package: echion
EchionNear-zero-overhead, in-process CPython frame stack sampler with async supportSynopsisEchion is an in-process CPython frame stack sampler. It can achieve
near-zero-overhead, similar toAustin, by sampling the frame stack of
each thread without holding the GIL. Native stacks can be sampled too, but the
overhead is higher.Echion is also the first example of a high-performance sampling async profiler
for CPython.InstallationCurrently Echion is available to install from PyPI withpip install echionAlternativey, if a wheel is not available for your combination of platform and
architecture, it can be installed from sources withpip install git+https://github.com/p403n1x87/echionCompilation requires a C++ compiler and static versions of thelibunwindandlzmalibraries.UsageThe following is the output of theechion --helpcommand.usage: echion [-h] [-i INTERVAL] [-c] [-n] [-o OUTPUT] [-s] [-w] [-v] [-V] ...

In-process CPython frame stack sampler

positional arguments:
  command               Command string to execute.

options:
  -h, --help            show this help message and exit
  -i INTERVAL, --interval INTERVAL
                        sampling interval in microseconds
  -c, --cpu             sample on-CPU stacks only
  -x EXPOSURE, --exposure EXPOSURE
                        exposure time, in seconds
  -n, --native          sample native stacks
  -o OUTPUT, --output OUTPUT
                        output location (can use %(pid) to insert the process ID)
  -p PID, --pid PID     Attach to the process with the given PID
  -s, --stealth         stealth mode (sampler thread is not accounted for)
  -w WHERE, --where WHERE
                        where mode: display thread stacks of the given process
  -v, --verbose         verbose logging
  -V, --version         show program's version number and exitThe output is written to a file specified with the--outputoption. Curretly, this is in
the format of the normalAustinformat, that is collapsed stacks with
metadata at the top. This makes it easy to re-use existing visualisation tools,
like theAustin VS Codeextension.CompatibilitySupported platforms: Linux (amd64, i686), Darwin (amd64, aarch64)Supported interpreters: CPython 3.8-3.11NotesAttaching to a process (including in where mode) requires extra permissions. On
Unix, you can attach to a running process withsudo. On Linux, one may also
set the ptrace scope to0withsudo sysctl kernel.yama.ptrace_scope=0to
allow attaching to any process. However, this is not recommended for security
reasons.Where modeThe where mode is similar toAustin's where mode, that is Echion will
dump the stacks of all running threads to standard error. This is useful for
debugging deadlocks and other issues that may occur in a running process.When running or attaching to a process, you can also send aSIGQUITsignal to
dump the stacks of all running threads. The result is similar to the where mode.
You can normally send aSIGQUITsignal with theCTRL+\key combination.Why Echion?Sampling in-process comes with some benefits. One has easier access to more
information, like thread names, and potentially the task abstraction of async
frameworks, likeasyncio,gevent, ... . Also available is more accurate
per-thread CPU timing information.Currently, Echion supports sampling asyncio-based applications, but not in
native mode. This makes Echion the very first example of an async profiler for
CPython.Echion relies on some assumptions to collect and sample all the running threads
without holding the GIL. This makes Echion very similar to tools likeAustin. However, some features, like multiprocess support, are more
complicated to handle and would require the use of e.g. IPC solutions.
Furthermore, Echion normally requires that you install it within your
environment, wheareasAustincan be installed indepdendently.How it worksOn a fundamental level, there is one key assumption that Echion relies upon:The interpreter state object lives as long as the CPython process itself.All unsafe memory reads are performed indirectly via copies of data structure
obtained with the use of system calls likeprocess_vm_readv. This is
essentially what allows Echion to run its sampling thread without the GIL.As for attaching to a running process, we make use of thehypnolibrary
to inject Python code that bootstraps Echion into the target process.