libguestfs-boot-analysis man page

boot-analysis — Trace and analyze the appliance boot process


 ./run utils/boot-analysis/boot-analysis


Trace and analyze the appliance boot process to find out which steps are taking the most time.  It is not part of the standard tests.

This needs to be run on a quiet machine, so that other processes disturb the timing as little as possible.  The program is completely safe to run at any time.  It doesn't read or write any external files, and it doesn't require root.

You can run it from the build directory on the built copy of libguestfs like this:

 ./run utils/boot-analysis/boot-analysis

If you omit ./run then it is run on the installed copy of libguestfs.

How it works

We create a libguestfs handle and register callback handlers so we can see appliance messages, trace events and so on.

We then launch the handle and shut it down as quickly as possible.

While the handle is running, events (seen by the callback handlers) are written verbatim into an in-memory buffer, with timestamps.

Afterwards we analyze the result using regular expressions to try to identify a “timeline” for the handle (eg. at what time did the BIOS hand control to the kernel).  This analysis is done in utils/boot-analysis/boot-analysis-timeline.c.

The whole process is repeated across a few runs, and the final timeline (including statistical analysis of the variation between runs) gets printed.

The program is very sensitive to the specific messages printed by BIOS/kernel/supermin/userspace.  It only works on x86-64 or aarch64. It will require periodic adjustment of the regular expressions in order to keep things up to date.



Display brief help.

--append “OPTIONS”

Append OPTIONS to the kernel command line.


Output colours (as ANSI escape sequences), even if the output is not a terminal.

-m MB
--memsize MB

Set the appliance memory size in MB.

--smp N

Enable N virtual CPUs.


More verbose output, useful for debugging problems.

See Also



Richard W.M. Jones


This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.


To get a list of bugs against libguestfs, use this link:

To report a new bug against libguestfs, use this link:

When reporting a bug, please supply:


2019-09-02 libguestfs-1.41.4 Virtualization Support