Product SiteDocumentation Site

Chapter 11. Debugging / Logging

11.1. Environment Variables
Libvirt includes logging facilities to facilitate the tracing of library execution. These logs will frequently be requested when trying to obtain support for libvirt, so familiarity with them is essential.
The logging facilities in libvirt are based on 3 key concepts:
  1. Log messages - generated at runtime by the libvirt code, they include a timestamp, a priority level (DEBUG = 1, INFO = 2, WARNING = 3, ERROR = 4), a category, function name and line number indicating where the message originated from, and a formatted message.
  2. Log filters - patterns and priorities which control whether or not a particular message is displayed. The format for a filter is:
    x:name
    where "x" is the minimal priority level where the match should apply, and "name" is a string to match against. The priority levels are:
    • 1 (or debug) - log all messages
    • 2 (or info) - log all non-debugging information
    • 3 (or warn) - log only warnings and errors - this is the default
    • 4 (or error) - log only errors
    For instance, to log all debug messages to the qemu driver, the following filter can be used:
    1:qemu
    Multiple filters can be specified together by space separating them; the following example logs all debug messages from qemu, and logs all error messages from the remote driver:
    1:qemu 4:remote
  3. Log outputs - where to send the message once it has passed through filters. The format for a log output is one of the forms:
    x:stderr - log to stderr
    x:syslog:name - log to syslog with a prefix of "name"
    x:file:file_path - log to a file specified by "file_path"
    where "x" is the minimal priority level. For instance, to log all warnings and errors to syslog with a prefix of "libvirtd", the following output can be used:
    3:syslog:libvirtd
    Multiple outputs can be specified by space separating them; the following example logs all error and warning messages to syslog, and logs all debug, information, warning, and error messages to /tmp/libvirt.log:
    3:syslog:libvirtd 1:file:/tmp/libvirt.log

11.1. Environment Variables

The desired log priority level, filters, and outputs are specified to the libvirt library through the use of environment variables:
  1. LIBVIRT_DEBUG specifies the minimum priority level messages that will be logged. This can be thought of as a "global" priority level; if a particular log message does not match a specific filter in LIBVIRT_LOG_FILTERS, it will be compared to this global priority and logged as appropriate.
  2. LIBVIRT_LOG_FILTERS specifies the filters to apply.
  3. LIBVIRT_LOG_OUTPUTS specifies the outputs to send the message to.

Example 11.1. Running virsh with environment variables

To see more detailed information about what is going on with virsh, we may run it like the following:
LIBVIRT_DEBUG=error LIBVIRT_LOG_FILTERS="1:remote" virsh list
This example will only print error messages from virsh, except that the remote driver will print all debug, information, warning, and error messages.