3.0 KiB
Sysprof Overview
libsysprof-capture
This static-library contains everything you need to read and write the raw sysprof capture format.
It does not depend on modern tooling like GLib precisely because it is also used by GLib to implement capturing profiling data.
That roughly means POSIX and C11.
libsysprof
This shared library (can also be used statically, internally) provides a
high-level API to the capture format (SysprofDocument) as well as a
convenient profiler API (SysprofProfiler and SysprofInstrument).
It heavily relies on GLib, GObject, and libdex for futures and fibers. This empowers the heavy use of "await" even though we are in C.
Instruments provide data to the recording and ultimately land in a capture.
Symbolizers also live here to take instruction pointers and convert them into symbol names. There is a decent amount of complexity around this to handle mount namespaces, flatpaks, containers, and other modern Linux features.
preload
Some profiler instruments require code running in the target process. This
directory contains *.so modules which can be used with LD_PRELOAD.
They will, once used in the target process, use the sysprof collector API to communicate with a Sysprof instance (sysprof-cli, the full UI process, etc).
sysprof
This is the UI process.
It uses libsysprof to access capture files and visualize that information.
sysprof-agent
This agent is installed in most GNOME SDKs and allows IDEs such as Builder to
run a profiler instance inside the SDK container. Such tooling is necessary
when you want to inject LD_PRELOAD modules into a process.
sysprof-cat
This is a simple tool which helps you see what is inside a sysprof capture.
sysprof-cli
This is a command line tool which allows you to do most of what the UI process can do to record a profiling session. It is often handy to use this in scripts, on servers, or other embedded devices.
sysprofd
Most users cannot directly access Perf or even where their kernel symbols are laid out in memory. We obviously need that to make a profiler so sysprofd gates access to that via D-Bus and polkit.
The UI application, sysprof-cli, or any libsysprof-enabled application can
connect to sysprofd and request a new perf FD. That FD is passed to the calling
application which may mmap() it to read perf data.
It also provides unredacted access to sensitive /proc files for authenticated
clients.
sysprof-diff
This is a simple tool which tries to find the difference in two captures as far as samples are concerned.
sysprof-live-unwinder
Many distros have switched to using frame-pointers out of practicality. Fedora is the notable example leading that.
However, some platforms such as RHEL and CentOS do not as of this time of
writing. To allow for some form of useful stack traces we have a
sysprof-live-unwinder which can take samples from perf and unwind them in
user-space in real-time by looking at the captured stack contents and register
data.
Libsysprof accesses this through the SysprofLiveUnwinder instrument.