'\" t
.\"     Title: kvm_stat
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 07/14/2026
.\"    Manual: \ \&
.\"    Source: \ \&
.\"  Language: English
.\"
.TH "KVM_STAT" "1" "07/14/2026" "\ \&" "\ \&"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
kvm_stat \- Report KVM kernel module event counters
.SH "SYNOPSIS"
.sp
.nf
\fIkvm_stat\fR [OPTION]\&...
.fi
.SH "DESCRIPTION"
.sp
kvm_stat prints counts of KVM kernel module trace events\&. These events signify state transitions such as guest mode entry and exit\&.
.sp
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\&. While running in regular mode, use any of the keys listed in section \fIInteractive Commands\fR below\&. Use batch and logging modes for scripting purposes\&.
.sp
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\&.
.SH "INTERACTIVE COMMANDS"
.TS
tab(:);
lt lt
lt lt
lt lt
lt lt
lt lt
lt lt
lt lt
lt lt
lt lt
lt lt
lt lt
lt lt
lt lt.
T{
.sp
\fBb\fR
T}:T{
.sp
toggle events by guests (debugfs only, honors filters)
T}
T{
.sp
\fBc\fR
T}:T{
.sp
clear filter
T}
T{
.sp
\fBf\fR
T}:T{
.sp
filter by regular expression
T}
T{
.sp
T}:T{
.sp
\fBNote\fR: Child events pull in their parents, and parents\*(Aq stats summarize all child events, not just the filtered ones
T}
T{
.sp
\fBg\fR
T}:T{
.sp
filter by guest name/PID
T}
T{
.sp
\fBh\fR
T}:T{
.sp
display interactive commands reference
T}
T{
.sp
\fBo\fR
T}:T{
.sp
toggle sorting order (Total vs CurAvg/s)
T}
T{
.sp
\fBp\fR
T}:T{
.sp
filter by guest name/PID
T}
T{
.sp
\fBq\fR
T}:T{
.sp
quit
T}
T{
.sp
\fBr\fR
T}:T{
.sp
reset stats
T}
T{
.sp
\fBs\fR
T}:T{
.sp
set delay between refreshs
T}
T{
.sp
\fBx\fR
T}:T{
.sp
toggle reporting of stats for child trace events
T}
T{
.sp
T}:T{
.sp
\fBNote\fR: The stats for the parents summarize the respective child trace events
T}
.TE
.sp 1
.sp
Press any other key to refresh statistics immediately\&.
.SH "OPTIONS"
.PP
\-1, \-\-once, \-\-batch
.RS 4
run in batch mode for one second
.RE
.PP
\-c, \-\-csv
.RS 4
log in csv format\&. Requires option \-l/\-\-log or \-L/\-\-log\-to\-file\&. When used with option \-L/\-\-log\-to\-file, the header is only ever written to start of file to preserve the format\&.
.RE
.PP
\-d, \-\-debugfs
.RS 4
retrieve statistics from debugfs
.RE
.PP
\-f<fields>, \-\-fields=<fields>
.RS 4
fields to display (regex), "\-f help" for a list of available events
.RE
.PP
\-g<guest>, \-\-guest=<guest_name>
.RS 4
limit statistics to one virtual machine (guest name)
.RE
.PP
\-h, \-\-help
.RS 4
show help message
.RE
.PP
\-i, \-\-debugfs\-include\-past
.RS 4
include all available data on past events for debugfs
.RE
.PP
\-l, \-\-log
.RS 4
run in logging mode (like vmstat)
.RE
.PP
\-L<file>, \-\-log\-to\-file=<file>
.RS 4
like \-l/\-\-log, but logging to a file\&. Appends to existing files\&.
.RE
.PP
\-p<pid>, \-\-pid=<pid>
.RS 4
limit statistics to one virtual machine (pid)
.RE
.PP
\-s, \-\-set\-delay
.RS 4
set delay between refreshs (value range: 0\&.1\-25\&.5 secs)
.RE
.PP
\-t, \-\-tracepoints
.RS 4
retrieve statistics from tracepoints
.RE
.PP
\-z, \-\-skip\-zero\-records
.RS 4
omit records with all zeros in logging mode
.RE
.SH "SEE ALSO"
.sp
\fIperf\fR(1), \fItrace\-cmd\fR(1)
.SH "AUTHOR"
.sp
Stefan Hajnoczi <stefanha@redhat\&.com>
