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

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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@xxxxxxxxxx>
> ---
> 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






[Index of Archives]     [Virt Tools]     [Libvirt Users]     [Lib OS Info]     [Fedora Users]     [Fedora Desktop]     [Fedora SELinux]     [Big List of Linux Books]     [Yosemite News]     [KDE Users]     [Fedora Tools]

  Powered by Linux