[libvirt PATCH] docs: kbase: add a page about debugging

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(a)redhat.com&gt; --- 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 diff --git a/docs/kbase.html.in b/docs/kbase.html.in index c586e0f676..1a50428805 100644 --- a/docs/kbase.html.in +++ b/docs/kbase.html.in @@ -36,6 +36,9 @@ <dt><a href="kbase/virtiofs.html">Virtio-FS</a></dt> <dd>Share a filesystem between the guest and the host</dd> + + <dt><a href="kbase/debugging.html">Debugging libvirt</a></dt> + <dd>How to capture debug logs and use a debugger on libvirt</dd> </dl> </div> diff --git a/docs/kbase/debugging.rst b/docs/kbase/debugging.rst new file mode 100644 index 0000000000..a9bc02aa55 --- /dev/null +++ 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 +cases you will be asked to attach debug logs. These are bare text files which +tracks transition between different states of libvirtd, what it has tried to +achieve, etc. Because of client -- server schema used in libvirt, the logs can +be either client or server too. Usually, it's server side that matters as +nearly all interesting work takes place there. Moreover, libvirt catches stderr +of all running domains. These can be useful as well. + + +How to turn on debug logs for libvirt +===================================== + +Persistent setting +------------------ + +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" + +* save and exit +* restart libvirtd service:: + + systemctl restart libvirtd.service + +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 +support shell globbing, therefore the usage of ``log_level`` is considered +deprecated in favour of pure usage of ``log_filters``. + +In case you want to get the client logs, you need to set this environment variable:: + + export LIBVIRT_LOG_OUTPUTS="1:file:/tmp/libvirt_client.log" + +However, when you are using the session mode ``qemu:///session`` or you run the +``libvirtd`` as unprivileged user you will find configuration file under +``$XDG_CONFIG_HOME/libvirt/libvirt.conf``. + + +Runtime setting +--------------- + +Debugging anomalies can be very painful, especially when trying to reproduce it +after the daemon restarts, since the new session can make the anomaly +"disappear". Therefore, it's possible to enable the debug logs during runtime +using libvirt administration API. To use it conveniently, there's a ``virt-admin`` +client provided by the ``libvirt-admin`` package. Use the package manager provided +by your distribution to install this package. Once you have it installed, run +the following as root to see the set of log filters currently being active:: + + # virt-admin daemon-log-filters + Logging filters: 3:remote 4:util.json 4:rpc + +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:*" + +Analogically, the same procedure can be performed with log outputs:: + + # virt-admin daemon-log-outputs + Logging outputs: 3:syslog:libvirtd + # virt-admin daemon-log-outputs "1:file:/var/log/libvirt/libvirtd.log" + +NOTE: It's always good practice to return the settings to the original state +once you're finished debugging, just remember to save the original sets of +filters and outputs and restore them at the end the same way as described +above. + + +Removing filters and outputs +---------------------------- + +It's also possible to remove all the filters and produce an enormous log file, +but it is not recommended since some of libvirt's modules can produce a large +amount of noise. However, should you really want to do this, you can specify an +empty set of filters:: + + # virt-admin daemon-log-filters "" + Logging filters: + +The situation is a bit different with outputs, since libvirt always has to log +somewhere and resetting the outputs to an empty set will restore the default +setting which depends on the host configuration, ''journald'' in our case:: + + # virt-admin daemon-log-outputs + Logging outputs: 1:file:/var/log/libvirt/libvirtd.log + # virt-admin daemon-log-outputs "" + Logging outputs: 2:journald + + +What to attach? +--------------- + +Now you should go and reproduce the bug. Once you're finished, attach: + +* ``/var/log/libvirt/libvirtd.log`` or whatever path you set for the daemon logs. +* If the problem is related to a domain attach ``/var/log/libvirt/qemu/$dom.log`` + then. Or substitute ``qemu`` with whatever hypervisor you are using. +* If you are asked for client logs, ``/tmp/libvirt_client.log``. + + +Using a debugger +================ + +When trying to figure out what libvirt does, debug logs might not always be +enough. And sometimes you might want to get some information from a user, but +you do not want to waste both your and their time by explaining how to do stuff +in gdb to, for example, get a backtrace. Here are some useful tips that you +might use. + + +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: === + +Running this command on 32bit Fedora 29 tells us what to install in order to +get the proper debugging symbols:: + + # gdb $(which libvirtd) + GNU gdb (GDB) Fedora 8.2-6.fc29 + ... + Reading symbols from /usr/sbin/libvirtd...(no debugging symbols found)...done. + Missing separate debuginfos, use: dnf debuginfo-install libvirt-daemon-4.7.0-1.fc29.i686 + +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 + +You might need to run the above commands for more complete output. It is very +dependent on the actually problem, whether you need this or not, but it will +never hurt to actually have all the data installed. + + +When libvirt hangs +------------------ + +When a process hangs, we usually ask for a backtrace. To avoid problems with +paging and so on, it is usually very helpful to just get a backtrace for one +instance of the particular process. For that you can use something like this:: + + # gdb -batch -p $(pidof libvirtd) -ex 't a a bt f' + +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. + + +When libvirt crashes +-------------------- + +Different distros have different mechanisms of catching and reporting crashes. +The automated ones are usually enabled only for the packaged binaries, but that +should be enough for users. Developers will have their own way of doing things +anyway. + +* **systemd-coredump** -- ``coredumpctl show`` shows all needed information + (even a backtrace) of the last crash, use ``coredumpctl ls`` to list all + crashes cordumpctl knows about. + +* **abrt** -- ``abrt-cli`` works similarly to the above (TBD: how to get the + backtrace using abrt-cli) + +* **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. + +For more information see related documentation. + + +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 +----------------- + +Simple example that will print backtrace when ``abort()`` is reached:: + + $ cat >/var/lib/libvirt/gdbabortscript <<EOF + start + break abort + commands + t a a bt full + end + continue + EOF + +This file instructs gdb to ``start`` the program (run until ``main()``), that +will load all the libraries so that we can setup a breakpoint for (p[retty +much) any existing function. It then sets up a breakpoint for the ``abort()`` +function and immediately sets up a list of ``commands`` that will run when that +breakpoint is hit (list of commands ends with ``end``). After that it allows +the process to ``continue`` its execution. + + +Systemd example +--------------- + +Let's say you need to debug an issue which happens only when the daemon is run +as a service as it does not happen when run manually. Ideally you would +connect to a running instance, but if the issue happens right after starting +the daemon. One option would be utilizing ``systemtap`` to add a ``sleep()`` +in one of the early functions (TBD: add an automated way of doing that or +remove this tip if it's not worth it). Another idea is to make the init system +run the gdb command we need. + +In systemd world we can do this easily by overriding the ``ExecStart`` parameter:: + + # cat >/etc/systemd/system/libvirtd.service.d/override.conf <<EOF + [Service] + ExecStart= + ExecStart=/usr/bin/gdb --batch -x /var/lib/libvirt/gdbabortscript /usr/sbin/libvirtd $LIBVIRTD_ARGS + EOF + +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 + +We actually do not need this to be read by the init system, but gdb will most +probably run under the same SELinux context as init, the context for libvirtd +gets changed by a transition rule which depends on the current runnning context +and the context of the binary being executed, so that whould apply only when +libvirtd is being started. This ''should'' work most of the time. If it does +not work for you, please figure out a way and add it here. + +Now we need to restart the daemon:: + + # systemctl restart libvirtd.service + +Beware, the command will not end until libvirtd itself ends as systemd is +waiting for ``sd_notify()`` from gdb's PID, but that function is being called +by libvirtd. + +You should get the full backtrace in the output of:: + + # journalctl -u libvirtd.service -- 2.25.1