Signed-off-by: Han Han <hhan(a)redhat.com&gt; --- docs/kbase.rst | 3 ++ docs/kbase/meson.build | 1 + docs/kbase/systemtap.rst | 113 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 117 insertions(+) create mode 100644 docs/kbase/systemtap.rst diff --git a/docs/kbase.rst b/docs/kbase.rst index 78daaa5989..d8bff5d41e 100644 --- a/docs/kbase.rst +++ b/docs/kbase.rst @@ -36,6 +36,9 @@ Knowledge base Examination of the security protections used for QEMU and how they need configuring to allow use of QEMU passthrough with host files/devices. + `Systemtap <kbase/systemtap.html>`__ + Explanation of how to use systemtap for libvirt tracing. + `Virtio-FS <kbase/virtiofs.html>`__ Share a filesystem between the guest and the host diff --git a/docs/kbase/meson.build b/docs/kbase/meson.build index d7f254e163..ca032a4b9b 100644 --- a/docs/kbase/meson.build +++ b/docs/kbase/meson.build @@ -13,6 +13,7 @@ docs_kbase_files = [ 'rpm-deployment', 's390_protected_virt', 'secureusage', + 'systemtap', 'virtiofs', ] diff --git a/docs/kbase/systemtap.rst b/docs/kbase/systemtap.rst new file mode 100644 index 0000000000..34420efbb2 --- /dev/null +++ b/docs/kbase/systemtap.rst @@ -0,0 +1,113 @@ +======================= +Systemtap of Libvirt +======================= + +.. contents:: + +`Systemtap <https://sourceware.org/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 <https://libvirt.org/compiling.html>`__): + +:: + + 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 <https://sourceware.org/systemtap/documentation.html>`__ -- 2.27.0