Dunfell
=======

DEPRECATED: Dunfell is deprecated in favour of using sysprof with the sysprof
marks which ship with GLib 2.65.1 and later versions.

See https://gitlab.gnome.org/GNOME/sysprof

---

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 protected]>
https://gitlab.com/pwithnall/dunfell