Mention branches and keyring.
[releases.git] / kvm / kvm_stat / kvm_stat.txt
1 kvm_stat(1)
2 ===========
3
4 NAME
5 ----
6 kvm_stat - Report KVM kernel module event counters
7
8 SYNOPSIS
9 --------
10 [verse]
11 'kvm_stat' [OPTION]...
12
13 DESCRIPTION
14 -----------
15 kvm_stat prints counts of KVM kernel module trace events.  These events signify
16 state transitions such as guest mode entry and exit.
17
18 This tool is useful for observing guest behavior from the host perspective.
19 Often conclusions about performance or buggy behavior can be drawn from the
20 output.
21 While running in regular mode, use any of the keys listed in section
22 'Interactive Commands' below.
23 Use batch and logging modes for scripting purposes.
24
25 The set of KVM kernel module trace events may be specific to the kernel version
26 or architecture.  It is best to check the KVM kernel module source code for the
27 meaning of events.
28
29 INTERACTIVE COMMANDS
30 --------------------
31 [horizontal]
32 *b*::   toggle events by guests (debugfs only, honors filters)
33
34 *c*::   clear filter
35
36 *f*::   filter by regular expression
37  ::     *Note*: Child events pull in their parents, and parents' stats summarize
38                 all child events, not just the filtered ones
39
40 *g*::   filter by guest name/PID
41
42 *h*::   display interactive commands reference
43
44 *o*::   toggle sorting order (Total vs CurAvg/s)
45
46 *p*::   filter by guest name/PID
47
48 *q*::   quit
49
50 *r*::   reset stats
51
52 *s*::   set delay between refreshs
53
54 *x*::   toggle reporting of stats for child trace events
55  ::     *Note*: The stats for the parents summarize the respective child trace
56                 events
57
58 Press any other key to refresh statistics immediately.
59
60 OPTIONS
61 -------
62 -1::
63 --once::
64 --batch::
65         run in batch mode for one second
66
67 -c::
68 --csv::
69         log in csv format. Requires option -l/--log or -L/--log-to-file.
70         When used with option -L/--log-to-file, the header is only ever
71         written to start of file to preserve the format.
72
73 -d::
74 --debugfs::
75         retrieve statistics from debugfs
76
77 -f<fields>::
78 --fields=<fields>::
79         fields to display (regex), "-f help" for a list of available events
80
81 -g<guest>::
82 --guest=<guest_name>::
83         limit statistics to one virtual machine (guest name)
84
85 -h::
86 --help::
87         show help message
88
89 -i::
90 --debugfs-include-past::
91         include all available data on past events for debugfs
92
93 -l::
94 --log::
95         run in logging mode (like vmstat)
96
97
98 -L<file>::
99 --log-to-file=<file>::
100         like -l/--log, but logging to a file. Appends to existing files.
101
102 -p<pid>::
103 --pid=<pid>::
104         limit statistics to one virtual machine (pid)
105
106 -s::
107 --set-delay::
108         set delay between refreshs (value range: 0.1-25.5 secs)
109
110 -t::
111 --tracepoints::
112         retrieve statistics from tracepoints
113
114 -z::
115 --skip-zero-records::
116         omit records with all zeros in logging mode
117
118 SEE ALSO
119 --------
120 'perf'(1), 'trace-cmd'(1)
121
122 AUTHOR
123 ------
124 Stefan Hajnoczi <stefanha@redhat.com>