From 19547e96e6061ba237d05245fe760eb99d69dd8c Mon Sep 17 00:00:00 2001
From: Christian Hergert <chergert@redhat.com>
Date: Mon, 17 Mar 2025 18:47:00 -0700
Subject: [PATCH] DESIGN.md: add some information on how sysprof is built

---
 src/DESIGN.md | 87 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 87 insertions(+)
 create mode 100644 src/DESIGN.md

diff --git a/src/DESIGN.md b/src/DESIGN.md
new file mode 100644
index 00000000..11eb8bca
--- /dev/null
+++ b/src/DESIGN.md
@@ -0,0 +1,87 @@
+# 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.