[libvirt PATCH] docs: kbase: add a page about debugging
Andrea Bolognani
abologna at redhat.com
Thu Apr 16 17:23:35 UTC 2020
On Wed, 2020-04-15 at 17:10 +0200, Ján Tomko wrote:
> Migrate the following wiki articles:
> https://wiki.libvirt.org/page/DebugLogs
> https://wiki.libvirt.org/page/Debugging
>
> With the syntax changed to rST and rewrapped.
>
> Signed-off-by: Ján Tomko <jtomko at redhat.com>
> ---
> I might've changed an article or two, too.
> Or rather: the article 'the'.
>
> docs/kbase.html.in | 3 +
> docs/kbase/debugging.rst | 303 +++++++++++++++++++++++++++++++++++++++
> 2 files changed, 306 insertions(+)
> create mode 100644 docs/kbase/debugging.rst
This fails to apply for me:
Applying: docs: kbase: add a page about debugging
error: corrupt patch at line 335
Patch failed at 0001 docs: kbase: add a page about debugging
hint: Use 'git am --show-current-patch' to see the failed patch
When you have resolved this problem, run "git am --continue".
If you prefer to skip this patch, run "git am --skip" instead.
To restore the original branch and stop patching, run "git am --abort".
[...]
> +++ b/docs/kbase/debugging.rst
> @@ -0,0 +1,303 @@
> +=================
> +Debugging libvirt
> +=================
> +
> +.. contents::
> +
> +
> +If you `report a bug <https://libvirt.org/bugs.html>`_ against libvirt, in most
I think we want to make links to other libvirt documentation
relative, so that they work correctly even when browsing an offline
copy locally.
[...]
> +The daemon configuration files location is dependent on the `connection URI
> +<http://libvirt.org/uri.html>`_. For ``qemu:///system``:
> +
> +* open ``/etc/libvirt/libvirtd.conf`` in your favourite editor
> +* find & replace, or set these variables::
> +
> + # LEGACY SETTINGS PRIOR LIBVIRT 4.4.0 SEE BELOW! #
> + log_level = 1
> + log_filters="1:qemu 3:remote 4:event 3:util.json 3:rpc"
> + log_outputs="1:file:/var/log/libvirt/libvirtd.log"
> +
> +
> + # PREFERRED SETTINGS AFTER LIBVIRT 4.4.0 #
> + log_filters="3:remote 4:event 3:util.json 3:rpc 1:*"
> + log_outputs="1:file:/var/log/libvirt/libvirtd.log"
You should have the code block marker on a separate line according
to https://libvirt.org/styleguide.html#code-blocks.
That also makes it possible to replicate the original layout of the
page, where each set of variables lived in its own box:
* find & replace, or set these variables:
::
# LEGACY SETTINGS PRIOR LIBVIRT 4.4.0 SEE BELOW! #
log_level = 1
log_filters="1:qemu 3:remote 4:event 3:util.json 3:rpc"
log_outputs="1:file:/var/log/libvirt/libvirtd.log"
::
# PREFERRED SETTINGS AFTER LIBVIRT 4.4.0 #
log_filters="3:remote 4:event 3:util.json 3:rpc 1:*"
log_outputs="1:file:/var/log/libvirt/libvirtd.log"
> +In the config variables above, we have set logging level to 1 (debug level),
> +set some filters (to filter out noise), e.g. from rpc only warnings (=level 3)
> +and above will be reported. The logs are saved into
> +``/var/log/libvirt/libvirtd.log``. Since libvirt *4.4.0* log filters
Bold text looks **like this**, not *like this*, in reStructuredText.
Unless you did that on purpose, in which case why not drop the markup
for the version number altogether? :)
[...]
> +In order to change this set, run the same command as root, this time with your own set of filters::
> +
> + ## LEGACY APPROACH ENUMERATING ALL THE DESIRED MODULES ##
> + # virt-admin daemon-log-filters "1:util 1:libvirt 1:storage 1:network 1:nodedev 1:qemu"
> +
> + ## CURRENT APPROACH USING SHELL GLOBBING ##
> + # virt-admin daemon-log-filters "3:remote 4:util.json 4:rpc 1:*"
These are two separate boxes in the original as well.
[...]
> +Prerequisites
> +-------------
> +
> +In cases where you want to see details of what is happening, you need to have
> +debugging symbols installed, at least for the package you are trying to debug.
> +Although having debugging symbols for all dependent libraries is usually
> +helpful as well. Usually ``gdb`` will tell you what you need to do in order to
> +get the proper data to your machine when you run it with a binary.
> +
> +=== Example: ===
You forgot to convert this into a reStructuredText section title.
More specifically, it's a subsection of "Prerequisites", so it should
look like
Example
~~~~~~~
[...]
> +When the package is installed, we can break on main and run until then (gdb's
> +command ``start`` is perfect for this)::
> +
> + # gdb $(which libvirtd)
> + GNU gdb (GDB) Fedora 8.2-6.fc29
> + ...
> + Reading symbols from /usr/sbin/libvirtd...Reading symbols from /usr/lib/debug/usr/sbin/libvirtd-4.7.0-1.fc29.i386.debug...done.
> + done.
> + (gdb) start
> + Temporary breakpoint 1 at 0x18fc0: file remote/remote_daemon.c, line 1030.
> + Starting program: /usr/sbin/libvirtd
> + Missing separate debuginfos, use: dnf debuginfo-install glibc-2.28-26.fc29.i686
> + Missing separate debuginfo for /lib/libvirt-lxc.so.0
> + Try: dnf --enablerepo='*debug*' install /usr/lib/debug/.build-id/4d/16496b686ec54ca4201bd769b04293f6c756b3.debug
> + Missing separate debuginfo for /lib/libvirt-qemu.so.0
> + Try: dnf --enablerepo='*debug*' install /usr/lib/debug/.build-id/ea/91d5346bd3e265ffb12ae641ca93643443e6e7.debug
> + Missing separate debuginfo for /lib/libvirt.so.0
> + Try: dnf --enablerepo='*debug*' install /usr/lib/debug/.build-id/02/af3a96fc6227ed5e3a447344bcbb672bde14ba.debug
> + ...
> + Temporary breakpoint 1, main (argc=1, argv=0xbffff614) at remote/remote_daemon.c:1030
> + 1030 int main(int argc, char **argv) {
> + Missing separate debuginfos, use: dnf debuginfo-install audit-libs-3.0-0.5.20181218gitbdb72c0.fc29.i686 avahi-libs-0.7-16.fc29.i686 brotli-1.0.5-1.fc29.i686 cyrus-sasl-lib-2.1.27-0.3rc7.fc29.i686 dbus-libs-1.12.12-1.fc29.i686 device-mapper-libs-1.02.154-1.fc29.i686 gmp-6.1.2-9.fc29.i686 gnutls-3.6.6-1.fc29.i686 keyutils-libs-1.5.10-8.fc29.i686 krb5-libs-1.16.1-25.fc29.i686 libacl-2.2.53-2.fc29.i686 libattr-2.4.48-3.fc29.i686 libblkid-2.32.1-1.fc29.i686 libcap-2.25-12.fc29.i686 libcap-ng-0.7.9-5.fc29.i686 libcom_err-1.44.4-1.fc29.i686 libcurl-7.61.1-10.fc29.i686 libffi-3.1-18.fc29.i686 libgcrypt-1.8.4-1.fc29.i686 libidn2-2.1.1a-1.fc29.i686 libmount-2.32.1-1.fc29.i686 libnghttp2-1.34.0-1.fc29.i686 libnl3-3.4.0-6.fc29.i686 libpsl-0.20.2-5.fc29.i686 libselinux-2.8-6.fc29.i686 libsepol-2.8-3.fc29.i686 libssh-0.8.7-1.fc29.i686 libssh2-1.8.1-1.fc29.i686 libtirpc-1.1.4-2.rc2.fc29.i686 libunistring-0.9.10-4.fc29.i686 libuuid-2.32.1-1.fc29.i686 libwsman1-2.6.5-8.fc29.i686 libxcrypt-4.4.4-2
> .fc29.i686 libxml2-2.9.8-5.fc29.i686 lz4-libs-1.8.3-1.fc29.i686 numactl-libs-2.0.12-1.fc29.i686 openldap-2.4.46-10.fc29.i686 openssl-libs-1.1.1b-3.fc29.i686 p11-kit-0.23.15-2.fc29.i686 pcre2-10.32-8.fc29.i686 xz-libs-5.2.4-3.fc29.i686 yajl-2.1.0-11.fc29.i686 zlib-1.2.11-14.fc29.i686
Wow, this one breaks the page layout pretty horribly :D
We will probably want to snip it or wrap it somehow. Let's leave that
for a second pass, though.
[...]
> +This command will attach to currently running libvirtd process and run ``t a a
> +bt f``, which is short for ``thread apply all backtrace full``, feel free to
> +combine with ``sudo`` for users. If you are using this for virsh, or any other
> +binary which might have multiple processes running, then make sure you supply
> +the right pid for the ``-p`` option. For more info, read below about how to
> +automate gdb.
This should be a link, but you need to tweak the text a bit for it
to work: something like
For more info, read the section about `automating gdb`_ below.
will do the trick.
[...]
> +* **setup your own** -- you can do one of these things:
> +
> + * set the ulimit for the service (depends on your init system) and look for
> + the file that gets created
> + * set kernel.core_pattern using sysctl to a command (rather than a filename
> + template) that gets ran with each core dump. This one does not need any
> + ulimit setting, but you need to know what to specify there.
Perhaps outside of the scope of your conversion, but I think that
"kernel.core_pattern" should be enclosed in ``s.
> +Automating gdb
> +--------------
> +
> +When you need more specific behaviour from gdb, you can automate that, but for
> +multiline commands you need an input redirection or execute them from the file.
> +
> +
> +Multiline example
> +-----------------
This, as well as the next section, is also a subsection of
"Automating gdb", and should be marked accordingly.
[...]
> +Daemon needs to be reloaded to know about this file::
> +
> + # systemctl daemon-reload
> +
> +We also need to make sure that the file we created will be readable by the
> +service. DAC should be fine, SELinux might get tricky. By placing the file
> +under ``/var/lib/libvirt`` this should be readable by both the init system and
> +the libvirt daemon, but we need to make sure it has a proper context::
> +
> + # restorecon -F /var/lib/libvirt/gdbabortscript /etc/systemd/system/libvirtd.service.d/override.conf
These two code blocks are indented by only two spaces instead of the
standard three. We should probably figure out a way to check this
kind of stuff automatically, because I got many wrong as well O:-)
--
Andrea Bolognani / Red Hat / Virtualization
More information about the libvir-list
mailing list