| Paolo Bonzini | fd41b5a | 2016-05-24 10:41:15 +0200 | [diff] [blame] | 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. |
| Stefan Raspl | 1eaa2f9 | 2017-03-10 13:40:07 +0100 | [diff] [blame] | 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. |
| Paolo Bonzini | fd41b5a | 2016-05-24 10:41:15 +0200 | [diff] [blame] | 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 | |
| Stefan Raspl | 1eaa2f9 | 2017-03-10 13:40:07 +0100 | [diff] [blame] | 29 | INTERACTIVE COMMANDS |
| 30 | -------------------- |
| 31 | [horizontal] |
| Stefan Raspl | 5c1954d25 | 2017-06-25 21:34:16 +0200 | [diff] [blame] | 32 | *b*:: toggle events by guests (debugfs only, honors filters) |
| 33 | |
| Stefan Raspl | 4443084 | 2017-03-10 13:40:14 +0100 | [diff] [blame] | 34 | *c*:: clear filter |
| 35 | |
| Stefan Raspl | 1eaa2f9 | 2017-03-10 13:40:07 +0100 | [diff] [blame] | 36 | *f*:: filter by regular expression |
| Stefan Raspl | 883d25e7 | 2019-04-21 15:26:24 +0200 | [diff] [blame] | 37 | :: *Note*: Child events pull in their parents, and parents' stats summarize |
| 38 | all child events, not just the filtered ones |
| Stefan Raspl | 1eaa2f9 | 2017-03-10 13:40:07 +0100 | [diff] [blame] | 39 | |
| Stefan Raspl | 516f119 | 2018-02-22 12:16:27 +0100 | [diff] [blame] | 40 | *g*:: filter by guest name/PID |
| Stefan Raspl | f9ff108 | 2017-03-10 13:40:13 +0100 | [diff] [blame] | 41 | |
| Stefan Raspl | 1fdea7b | 2017-06-07 21:08:38 +0200 | [diff] [blame] | 42 | *h*:: display interactive commands reference |
| 43 | |
| Stefan Raspl | 6667ae8 | 2017-06-07 21:08:41 +0200 | [diff] [blame] | 44 | *o*:: toggle sorting order (Total vs CurAvg/s) |
| 45 | |
| Stefan Raspl | 516f119 | 2018-02-22 12:16:27 +0100 | [diff] [blame] | 46 | *p*:: filter by guest name/PID |
| Stefan Raspl | 1eaa2f9 | 2017-03-10 13:40:07 +0100 | [diff] [blame] | 47 | |
| 48 | *q*:: quit |
| 49 | |
| Stefan Raspl | 9f114a0 | 2017-03-10 13:40:15 +0100 | [diff] [blame] | 50 | *r*:: reset stats |
| 51 | |
| Stefan Raspl | 64eefad | 2017-06-07 21:08:39 +0200 | [diff] [blame] | 52 | *s*:: set update interval |
| 53 | |
| Stefan Raspl | 1eaa2f9 | 2017-03-10 13:40:07 +0100 | [diff] [blame] | 54 | *x*:: toggle reporting of stats for child trace events |
| Stefan Raspl | fff8c9e | 2017-12-11 12:25:23 +0100 | [diff] [blame] | 55 | :: *Note*: The stats for the parents summarize the respective child trace |
| 56 | events |
| Stefan Raspl | 1eaa2f9 | 2017-03-10 13:40:07 +0100 | [diff] [blame] | 57 | |
| 58 | Press any other key to refresh statistics immediately. |
| 59 | |
| Paolo Bonzini | fd41b5a | 2016-05-24 10:41:15 +0200 | [diff] [blame] | 60 | OPTIONS |
| 61 | ------- |
| 62 | -1:: |
| 63 | --once:: |
| 64 | --batch:: |
| 65 | run in batch mode for one second |
| 66 | |
| 67 | -l:: |
| 68 | --log:: |
| 69 | run in logging mode (like vmstat) |
| 70 | |
| 71 | -t:: |
| 72 | --tracepoints:: |
| 73 | retrieve statistics from tracepoints |
| 74 | |
| 75 | -d:: |
| 76 | --debugfs:: |
| 77 | retrieve statistics from debugfs |
| 78 | |
| Stefan Raspl | ab7ef19 | 2017-06-25 21:34:15 +0200 | [diff] [blame] | 79 | -i:: |
| 80 | --debugfs-include-past:: |
| 81 | include all available data on past events for debugfs |
| 82 | |
| Janosch Frank | f0cf040 | 2016-05-18 13:26:24 +0200 | [diff] [blame] | 83 | -p<pid>:: |
| 84 | --pid=<pid>:: |
| 85 | limit statistics to one virtual machine (pid) |
| 86 | |
| Stefan Raspl | f9ff108 | 2017-03-10 13:40:13 +0100 | [diff] [blame] | 87 | -g<guest>:: |
| 88 | --guest=<guest_name>:: |
| 89 | limit statistics to one virtual machine (guest name) |
| 90 | |
| Paolo Bonzini | fd41b5a | 2016-05-24 10:41:15 +0200 | [diff] [blame] | 91 | -f<fields>:: |
| 92 | --fields=<fields>:: |
| Stefan Raspl | f3d11b0 | 2017-12-11 12:25:24 +0100 | [diff] [blame] | 93 | fields to display (regex), "-f help" for a list of available events |
| Paolo Bonzini | fd41b5a | 2016-05-24 10:41:15 +0200 | [diff] [blame] | 94 | |
| 95 | -h:: |
| 96 | --help:: |
| 97 | show help message |
| 98 | |
| 99 | SEE ALSO |
| 100 | -------- |
| 101 | 'perf'(1), 'trace-cmd'(1) |
| 102 | |
| 103 | AUTHOR |
| 104 | ------ |
| 105 | Stefan Hajnoczi <stefanha@redhat.com> |