Re: [PATCH v2 0/5] Improve KVM per VM monitoring

[Janosch Frank <frankja@linux.vnet.ibm.com>]

On 05/23/2016 04:07 PM, Paolo Bonzini wrote:
> On 18/05/2016 13:26, Janosch Frank wrote:
>> This patchset introduces KVM per VM exit statistics monitoring via
>> debugfs, as well as moves a tool to display VM statistics from qemu to
>> tools/.
>>
>> The new debugfs per VM statistics are an alternative to the already
>> available VM tracepoints. They are easier to read and have low
>> overhead.
>>
>> The kvm_stat python script is moved to the kernel, as we can make sure
>> here that the right version of the script is used with the right
>> kernel version. This is not given for qemu, as it supports a wide
>> range of linux kernel versions.
> 
> The patches look good, but you are not moving over the documentation.
> 
> I started looking at asciidoc, but perf's documentation Makefiles seem
> to be overkill for our purposes.  (My prototype conversion of the docs
> to asciidoc after my signature).
> 
> Perhaps pod2man could be an alternative (using QEMU's texi2pod to
> build the kvm_stat.pod input)?

The script already outputs a help text, which could be extended to the
man's text. I.e. I left it out on purpose.

Anyway, creating the manpage from asciidoc sources is a matter of having
the right packages and simply calling:
a2x --doctype manpage --format manpage file.txt

Works flawlessly with your example and is much more readable than the
texi source. I would give it a try and add it to the first patch if you
do not have any concerns?

The makefile would come down to (feel free to improve, I rarely write
makefiles):

include ../../scripts/Makefile.include
include ../../scripts/utilities.mak
BINDIR=usr/bin
MANDIR=usr/share/man/man1
ASCIIDOC=asciidoc
asciidoc_path := $(call get-executable,$(ASCIIDOC))

check-asciidoc:
ifeq ($(asciidoc_path),)
	$(error "You need to install asciidoc for man pages")
endif

man: check-asciidoc
	a2x --doctype manpage --format manpage kvm_stat.txt

install-man: man
	install -d -m 755 $(INSTALL_ROOT)/$(MANDIR)
	install -m 644 kvm_stat.1 $(INSTALL_ROOT)/$(MANDIR)

install:
	mkdir -p $(INSTALL_ROOT)/$(BINDIR)
	install -m 755 -p "kvm_stat" "$(INSTALL_ROOT)/$(BINDIR)/$(TARGET)"

> 
> Paolo
> 
> 
> kvm_stat(1)
> ===========
> 
> NAME
> ----
> kvm_stat - Report KVM kernel module event counters
> 
> SYNOPSIS
> --------
> [verse]
> 'kvm_stat' [OPTION]...
> 
> DESCRIPTION
> -----------
> kvm_stat prints counts of KVM kernel module trace events.  These events signify
> state transitions such as guest mode entry and exit.
> 
> This tool is useful for observing guest behavior from the host perspective.
> Often conclusions about performance or buggy behavior can be drawn from the
> output.
> 
> The set of KVM kernel module trace events may be specific to the kernel version
> or architecture.  It is best to check the KVM kernel module source code for the
> meaning of events.
> 
> Note that trace events are counted globally across all running guests.
Let's not forget this for the pid monitoring patch:

Events can be fetched globally for all guests or for single guests only.

> 
> OPTIONS
> -------
> -1::
> --once::
> --batch::
> 	run in batch mode for one second
> 
> -l::
> --log::
> 	run in logging mode (like vmstat)
> 
> -t::
> --tracepoints::
> 	retrieve statistics from tracepoints
> 
> -d::
> --debugfs::
> 	retrieve statistics from debugfs
Let's not forget this for the pid monitoring patch:

-p<pid>::
--pid=<pid>::
	restrict statistics to pid

> 
> -f<fields>::
> --fields=<fields>::
> 	fields to display (regex)
> 
> -h::
> --help::
> 
>   show help message
> 
> SEE ALSO
> --------
> perf(1), trace-cmd(1)
> 
> AUTHOR
> ------
> Stefan Hajnoczi <stefanha@redhat.com>
>