libvirt/docs/kbase/systemtap.rst

Systemtap of Libvirt

Systemtap is a scripting language and tool for dynamically probing or tracing in Linux kernel space or user space. This page is about the usage of systemtap in libvirt tracing.

Preparation

Libvirt

Libvirt should be configured with the systemtap option to support libvirt probing events in systemtap.

For libvirt before 6.7.0, it can be configured by:

mkdir build
cd build
../configure --with-dtrace

For libvirt 6.7.0 or later, configure it by the meson (seeing libvirt compiling):

meson build -Ddtrace=enabled

For the libvirt binaries installed by the package manager like dnf or apt, if libvirt systemtap tapset /usr/share/systemtap/tapset/libvirt_* exists, it means the libvirt enables the systemtap feature.

Systemtap

For most of linux distributions, execute stap-prep by root to prepare the environment for systemtap after installing the systemtap. If your distribution doesn't have stap-prep, install the kernel debuginfo packages manually.

After these above, run this test command to confirm the systemtap works well:

stap -e 'probe oneshot{ printf("hello world\n")}'

Tracing events

The libvirt systemtap tracing events are defined in tapset /usr/share/systemtap/tapset/libvirt_*. Libvirt support these type of tracing events: dbus, event_glib, object, qemu, rpc.

List all tracing events in libvirt:

grep 'probe libvirt.[a-z_0-9.]*' /usr/share/systemtap/tapset/libvirt_* -o|cut -f 2 -d :

Tracing examples

Here is an example of the systemtap script to trace the QMP messages sent from libvirtd daemon to the qemu process. qmp.stp:

probe begin
{
  printf("Start tracing\n")
}
probe libvirt.qemu.monitor_send_msg
{
  printf("QMPs: %s", msg);
}

Then run the systemtap script attaching to the libvirtd process:

stap qmp.stp -x `pidof libvirtd`

To trace a libvirtd started from command line, use the option -c

stap qmp.stp -c "/usr/sbin/libvirtd"

Then after seeing the welcome message "Start tracing" from systemtap, then execute a virsh command associated with QMP, for example virsh domstats. Then get the QMP tracing logs from systemtap. For example, the result from virsh domstats

QMPs: {"execute":"query-balloon","id":"libvirt-393"}
QMPs: {"execute":"qom-get","arguments":{"path":"/machine/peripheral/balloon0","property":"guest-stats"},"id":"libvirt-394"}
QMPs: {"execute":"query-blockstats","id":"libvirt-395"}
QMPs: {"execute":"query-named-block-nodes","id":"libvirt-396"}
QMPs: {"execute":"query-iothreads","id":"libvirt-397"}

For more examples of libvirt systemtap scripts, see the scripts in /usr/share/doc/libvirt-docs/examples/systemtap For more details of systemtap language, see document of systemtap