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
Signed-off-by: Han Han <hhan@redhat.com>
---
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
On Thu, Aug 06, 2020 at 02:34:02PM +0800, Han Han wrote: > Signed-off-by: Han Han <hhan@redhat.com> > --- > 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 > +======================= The "===" are too long here and all the other headings. > + > +.. 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>`__ > -- Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> and pushed after trimming the heading markers Regards, Daniel -- |: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
On 8/6/20 3:34 AM, Han Han wrote: > Signed-off-by: Han Han <hhan@redhat.com> > --- > 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 s/type/types With this nit fixed: Reviewed-by: Daniel Henrique Barboza <danielhb413@gmail.com> > +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>`__ >
ping, any more reviews? On Thu, Aug 6, 2020 at 9:44 PM Daniel Henrique Barboza < danielhb413@gmail.com> wrote: > > On 8/6/20 3:34 AM, Han Han wrote: > > Signed-off-by: Han Han <hhan@redhat.com> > > --- > > 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 > > s/type/types > > Thanks > > With this nit fixed: > > > Reviewed-by: Daniel Henrique Barboza <danielhb413@gmail.com> > > > > > +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>`__ > > > > -- Best regards, ----------------------------------- Han Han Senior Quality Engineer Redhat. Email: hhan@redhat.com Phone: +861065339333
© 2016 - 2024 Red Hat, Inc.