Dunfell ======= Dunfell provides a library for extracting events from GLib main contexts and visualising them for the purposes of debugging and optimisation. It provides graphical utilities for this purpose. See the test programs in libdunfell/tests/ for simple examples of how to use the code. libdunfell’s API is currently unstable and is likely to change wildly. What is the GLib main context ============================= This is handily written up elsewhere: https://developer.gnome.org/programming-guidelines/unstable/main-contexts.html.en Using Dunfell ============= Dunfell can be used as a set of utility programs or as a library. Initial setup ------------- Install systemtap-client and systemtap-server. If you are using a custom version of GLib, you must add its tapset files to the stap-server include path: sudo mkdir -p /etc/stap-server/conf.d echo "INCLUDE+=/opt/gnome3/build/share/systemtap/tapset" | \ sudo tee /etc/stap-server/conf.d/main.conf You will also need to add your user to the stapusr group in order for this configuration to be read (if you have modified the configuration): sudo usermod -a -G stapusr $USER Running Dunfell recorder ------------------------ Dunfell has two parts: a recorder, which is used to trace what happens in your process; and a viewer, which is used afterwards to visualise the trace. There is currently no way to visualise a process while it is running. To run the recorder on my-favourite-process with some arguments: dunfell-record -- my-favourite-process --arguments --to --it The result will be written to /tmp/dunfell.log. To view the result: dunfell-viewer /tmp/dunfell.log Dependencies ============ • glib-2.0 • gio-2.0 • gtk+-3.0 Design ====== Use cases --------- Here are the use cases Dunfell was designed to meet, which should give some insight into its design. • Detect GSources which are never added to a GMainContext. • Detect GSources which are dispatched too often (i.e. every main context iteration). • Detect GSources whose dispatch function takes too long (and hence blocks the main context). • Detect GSources which are never removed from their GMainContext after being dispatched (but which are never dispatched again). • Detect GMainContexts which have GSources attached or (especially) events pending, but which aren’t being iterated. • Monitor the load on each GMainContext, such as how many GSources it has attached, and how many events are processed each iteration. • Monitor ongoing asynchronous calls and GTasks, giving insight into their nesting and dependencies. • Monitor unfinished or stalled asynchronous calls. • Allow users to record logs to send to the developers for debugging on a different machine. The users may have to install additional software to record these logs (some component of Dunfell, plus its dependencies), but should not have to recompile or otherwise modify the program being debugged. • Work with programs which purely use GLib, through to programs which use GLib, GIO and GTK+. • Allow visualisation of this data, both in a standalone program, and in an IDE such as GNOME Builder. • Allow visualising differences between two traces. • Minimise runtime overhead of logging a program, to reduce the risk of disturbing race conditions by enabling logging. • Connecting to an already-running program is not a requirement, since by the time you’ve decided there’s a problem with a program, it’s already in the wrong state. Prior art --------- • Record and Replay (http://rr-project.org/) • perf tool • perfkit (https://github.com/chergert/perfkit) • G_DEBUG=instance-count • GTK+ Inspector (https://wiki.gnome.org/Projects/GTK%2B/Inspector) Deprecation guards ================== If LIBDUNFELL_DISABLE_DEPRECATED is defined when compiling against libdunfell, all deprecated API will be removed from included headers. Licensing ========= libdunfell is licensed under the LGPL; see COPYING for more details. Bugs ==== Bug reports and (git formatted) patches should be e-mailed to one of the addresses listed in the ‘Contact’ section below. Thank you! Contact ======= Philip Withnall <email@example.com> https://gitlab.com/pwithnall/dunfell
Dunfell provides a library for extracting events from GLib main contexts and visualising them for the purposes of debugging and optimisation. It provides graphical utilities for this purpose.