Permalink
Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
130 lines (98 sloc) 4.23 KB
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 <philip@tecnocode.co.uk>
https://gitlab.com/pwithnall/dunfell