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

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

On 05/24/2016 10:50 AM, Paolo Bonzini wrote:
> On 24/05/2016 10:17, Janosch Frank wrote:
>> 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?
> 
> I will include the following as a separate patch:

Great, thanks!
Don't forget the manpage changes for the pid monitoring, i.e. the
-p/--pid argument and the removal of the note.

> 
> ---------------- 8< ---------------
> From ccceb628a51e52a4b6384e6ef1cc9d88daf00a62 Mon Sep 17 00:00:00 2001
> From: Paolo Bonzini <pbonzini@redhat.com>
> Date: Tue, 24 May 2016 10:41:15 +0200
> Subject: [PATCH] tools: Add kvm_stat man page
> 
> Converted from the Texinfo source in QEMU to asciidoc.  The a2x
> incantation was provided by Frank Janosch.

s/Frank Janosch/Janosch Frank/
Janosch is my first name.

> 
> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
> ---
>  tools/kvm/kvm_stat/Makefile     | 40 ++++++++++++++++++++++++--
>  tools/kvm/kvm_stat/kvm_stat.txt | 62 +++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 100 insertions(+), 2 deletions(-)
>  create mode 100644 tools/kvm/kvm_stat/kvm_stat.txt
> 
> diff --git a/tools/kvm/kvm_stat/Makefile b/tools/kvm/kvm_stat/Makefile
> index c639b8d30688..5b1cba57e3b3 100644
> --- a/tools/kvm/kvm_stat/Makefile
> +++ b/tools/kvm/kvm_stat/Makefile
> @@ -1,5 +1,41 @@
> +include ../../scripts/Makefile.include
> +include ../../scripts/utilities.mak
>  BINDIR=usr/bin
> +MANDIR=usr/share/man
> +MAN1DIR=$(MANDIR)/man1
> 
> -install:
> -	mkdir -p $(INSTALL_ROOT)/$(BINDIR)
> +MAN1=kvm_stat.1
> +
> +A2X=a2x
> +a2x_path := $(call get-executable,$(A2X))
> +
> +all: man
> +
> +ifneq ($(findstring $(MAKEFLAGS),s),s)
> +  ifneq ($(V),1)
> +     QUIET_A2X = @echo '  A2X     '$@;
> +  endif
> +endif
> +
> +%.1: %.txt
> +ifeq ($(a2x_path),)
> +	$(error "You need to install asciidoc for man pages")
> +else
> +	$(QUIET_A2X)$(A2X) --doctype manpage --format manpage $<
> +endif
> +
> +clean:
> +	rm -f $(MAN1)
> +
> +man: $(MAN1)
> +
> +install-man: man
> +	install -d -m 755 $(INSTALL_ROOT)/$(MAN1DIR)
> +	install -m 644 kvm_stat.1 $(INSTALL_ROOT)/$(MAN1DIR)
> +
> +install-tools:
> +	install -d -m 755 $(INSTALL_ROOT)/$(BINDIR)
>  	install -m 755 -p "kvm_stat" "$(INSTALL_ROOT)/$(BINDIR)/$(TARGET)"
> +
> +install: install-tools install-man
> +.PHONY: all clean man install-tools install-man install
> diff --git a/tools/kvm/kvm_stat/kvm_stat.txt b/tools/kvm/kvm_stat/kvm_stat.txt
> new file mode 100644
> index 000000000000..039dee80ddcb
> --- /dev/null
> +++ b/tools/kvm/kvm_stat/kvm_stat.txt
> @@ -0,0 +1,62 @@
> +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.
> +
> +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
> +
> +-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>
>