Provided by: percona-toolkit_3.2.1-1_all 
NAME
pt-diskstats - An interactive I/O monitoring tool for GNU/Linux.
SYNOPSIS
Usage: pt-diskstats [OPTIONS] [FILES]
pt-diskstats prints disk I/O statistics for GNU/Linux. It is somewhat similar to iostat,
but it is interactive and more detailed. It can analyze samples gathered from another
machine.
RISKS
Percona Toolkit is mature, proven in the real world, and well tested, but all database
tools can pose a risk to the system and the database server. Before using this tool,
please:
• Read the tool's documentation
• Review the tool's known "BUGS"
• Test the tool on a non-production server
• Backup your production server and verify the backups
DESCRIPTION
The pt-diskstats tool is similar to iostat, but has some advantages. It prints read and
write statistics separately, and has more columns. It is menu-driven and interactive, with
several different ways to aggregate the data. It integrates well with the pt-stalk tool.
It also does the "right thing" by default, such as hiding disks that are idle. These
properties make it very convenient for quickly drilling down into I/O performance and
inspecting disk behavior.
This program works in two modes. The default is to collect samples of /proc/diskstats and
print out the formatted statistics at intervals. The other mode is to process a file that
contains saved samples of /proc/diskstats; there is a shell script later in this
documentation that shows how to collect such a file.
In both cases, the tool is interactively controlled by keystrokes, so you can redisplay
and slice the data flexibly and easily. It loops forever, until you exit with the 'q'
key. If you press the '?' key, you will bring up the interactive help menu that shows
which keys control the program.
When the program is gathering samples of /proc/diskstats and refreshing its display, it
prints information about the newest sample each time it refreshes. When it is operating
on a file of saved samples, it redraws the entire file's contents every time you change an
option.
The program doesn't print information about every block device on the system. It hides
devices that it has never observed to have any activity. You can enable and disable this
by pressing the 'i' key.
OUTPUT
In the rest of this documentation, we will try to clarify the distinction between block
devices (/dev/sda1, for example), which the kernel presents to the application via a
filesystem, versus the (usually) physical device underneath the block device, which could
be a disk, a RAID controller, and so on. We will sometimes refer to logical I/O
operations, which occur at the block device, versus physical I/Os which are performed on
the underlying device. When we refer to the queue, we are speaking of the queue
associated with the block device, which holds requests until they're issued to the
physical device.
The program's output looks like the following sample, which is too wide for this manual
page, so we have formatted it as several samples with line breaks:
#ts device rd_s rd_avkb rd_mb_s rd_mrg rd_cnc rd_rt
{6} sda 0.9 4.2 0.0 0% 0.0 17.9
{6} sdb 0.4 4.0 0.0 0% 0.0 26.1
{6} dm-0 0.0 4.0 0.0 0% 0.0 13.5
{6} dm-1 0.8 4.0 0.0 0% 0.0 16.0
... wr_s wr_avkb wr_mb_s wr_mrg wr_cnc wr_rt
... 99.7 6.2 0.6 35% 3.7 23.7
... 14.5 15.8 0.2 75% 0.5 9.2
... 1.0 4.0 0.0 0% 0.0 2.3
... 117.7 4.0 0.5 0% 4.1 35.1
... busy in_prg io_s qtime stime
... 6% 0 100.6 23.3 0.4
... 4% 0 14.9 8.6 0.6
... 0% 0 1.1 1.5 1.2
... 5% 0 118.5 34.5 0.4
The columns are as follows:
#ts This column's contents vary depending on the tool's aggregation mode. In the default
mode, when each line contains information about a single disk but possibly aggregates
across several samples from that disk, this column shows the number of samples that
were included into the line of output, in {curly braces}. In the example shown, each
line of output aggregates {10} samples of /proc/diskstats.
In the "all" group-by mode, this column shows timestamp offsets, relative to the time
the tool began aggregating or the timestamp of the previous lines printed, depending
on the mode. The output can be confusing to explain, but it's rather intuitive when
you see the lines appearing on your screen periodically.
Similarly, in "sample" group-by mode, the number indicates the total time span that is
grouped into each sample.
If you specify "--show-timestamps", this field instead shows the timestamp at which
the sample was taken; if multiple timestamps are present in a single line of output,
then the first timestamp is used.
device
The device name. If there is more than one device, then instead the number of devices
aggregated into the line is shown, in {curly braces}.
rd_s
The average number of reads per second. This is the number of I/O requests that were
sent to the underlying device. This usually is a smaller number than the number of
logical IO requests made by applications. More requests might have been queued to the
block device, but some of them usually are merged before being sent to the disk.
This field is computed from the contents of /proc/diskstats as follows. See "KERNEL
DOCUMENTATION" below for the meaning of the field numbers:
delta[field1] / delta[time]
rd_avkb
The average size of the reads, in kilobytes. This field is computed as follows:
2 * delta[field3] / delta[field1]
rd_mb_s
The average number of megabytes read per second. Computed as follows:
2 * delta[field3] / delta[time]
rd_mrg
The percentage of read requests that were merged together in the queue scheduler
before being sent to the physical device. The field is computed as follows:
100 * delta[field2] / (delta[field2] + delta[field1])
rd_cnc
The average concurrency of the read operations, as computed by Little's Law. This is
the end-to-end concurrency on the block device, not the underlying disk's concurrency.
It includes time spent in the queue. The field is computed as follows:
delta[field4] / delta[time] / 1000 / devices-in-group
rd_rt
The average response time of the read operations, in milliseconds. This is the end-
to-end response time, including time spent in the queue. It is the response time that
the application making I/O requests sees, not the response time of the physical disk
underlying the block device. It is computed as follows:
delta[field4] / (delta[field1] + delta[field2])
wr_s, wr_avkb, wr_mb_s, wr_mrg, wr_cnc, wr_rt
These columns show write activity, and they match the corresponding columns for read
activity.
busy
The fraction of wall-clock time that the device had at least one request in progress;
this is what iostat calls %util, and indeed it is utilization, depending on how you
define utilization, but that is sometimes ambiguous in common parlance. It may also
be called the residence time; the time during which at least one request was resident
in the system. It is computed as follows:
100 * delta[field10] / (1000 * delta[time])
This field cannot exceed 100% unless there is a rounding error, but it is a common
mistake to think that a device that's busy all the time is saturated. A device such
as a RAID volume should support concurrency higher than 1, and solid-state drives can
support very high concurrency. Concurrency can grow without bound, and is a more
reliable indicator of how loaded the device really is.
in_prg
The number of requests that were in progress. Unlike the read and write
concurrencies, which are averages that are generated from reliable numbers, this
number is an instantaneous sample, and you can see that it might represent a spike of
requests, rather than the true long-term average. If this number is large, it
essentially means that the device is heavily loaded. It is computed as follows:
field9
ios_s
The average throughput of the physical device, in I/O operations per second (IOPS).
This column shows the total IOPS the underlying device is handling. It is the sum of
rd_s and wr_s.
qtime
The average queue time; that is, time a request spends in the device scheduler queue
before being sent to the physical device. This is an average over reads and writes.
It is computed in a slightly complex way: the average response time seen by the
application, minus the average service time (see the description of the next column).
This is derived from the queueing theory formula for response time, R = W + S:
response time = queue time + service time. This is solved for W, of course, to give W
= R - S. The computation follows:
delta[field11] / (delta[field1, 2, 5, 6] + delta[field9])
- delta[field10] / delta[field1, 2, 5, 6]
See the description for "stime" for more details and cautions.
stime
The average service time; that is, the time elapsed while the physical device
processes the request, after the request finishes waiting in the queue. This is an
average over reads and writes. It is computed from the queueing theory utilization
formula, U = SX, solved for S. This means that utilization divided by throughput
gives service time:
delta[field10] / (delta[field1, 2, 5, 6])
Note, however, that there can be some kernel bugs that cause field 9 in
/proc/diskstats to become negative, and this can cause field 10 to be wrong, thus
making the service time computation not wholly trustworthy.
Note that in the above formula we use utilization very specifically. It is a duration,
not a percentage.
You can compare the stime and qtime columns to see whether the response time for reads
and writes is spent in the queue or on the physical device. However, you cannot see
the difference between reads and writes. Changing the block device scheduler
algorithm might improve queue time greatly. The default algorithm, cfq, is very bad
for servers, and should only be used on laptops and workstations that perform tasks
such as working with spreadsheets and surfing the Internet.
If you are used to using iostat, you might wonder where you can find the same information
in pt-diskstats. Here are two samples of output from both tools on the same machine at
the same time, for /dev/sda, wrapped to fit:
#ts dev rd_s rd_avkb rd_mb_s rd_mrg rd_cnc rd_rt
08:50:10 sda 0.0 0.0 0.0 0% 0.0 0.0
08:50:20 sda 0.4 4.0 0.0 0% 0.0 15.5
08:50:30 sda 2.1 4.4 0.0 0% 0.0 21.1
08:50:40 sda 2.4 4.0 0.0 0% 0.0 15.4
08:50:50 sda 0.1 4.0 0.0 0% 0.0 33.0
wr_s wr_avkb wr_mb_s wr_mrg wr_cnc wr_rt
7.7 25.5 0.2 84% 0.0 0.3
49.6 6.8 0.3 41% 2.4 28.8
210.1 5.6 1.1 28% 7.4 25.2
297.1 5.4 1.6 26% 11.4 28.3
11.9 11.7 0.1 66% 0.2 4.9
busy in_prg io_s qtime stime
1% 0 7.7 0.1 0.2
6% 0 50.0 28.1 0.7
12% 0 212.2 24.8 0.4
16% 0 299.5 27.8 0.4
1% 0 12.0 4.7 0.3
Dev rrqm/s wrqm/s r/s w/s rMB/s wMB/s
08:50:10 sda 0.00 41.40 0.00 7.70 0.00 0.19
08:50:20 sda 0.00 34.70 0.40 49.60 0.00 0.33
08:50:30 sda 0.00 83.30 2.10 210.10 0.01 1.15
08:50:40 sda 0.00 105.10 2.40 297.90 0.01 1.58
08:50:50 sda 0.00 22.50 0.10 11.10 0.00 0.13
avgrq-sz avgqu-sz await svctm %util
51.01 0.02 2.04 1.25 0.96
13.55 2.44 48.76 1.16 5.79
11.15 7.45 35.10 0.55 11.76
10.81 11.40 37.96 0.53 15.97
24.07 0.17 15.60 0.87 0.97
The correspondence between the columns is not one-to-one. In particular:
rrqm/s, wrqm/s
These columns in iostat are replaced by rd_mrg and wr_mrg in pt-diskstats.
avgrq-sz
This column is in sectors in iostat, and is a combination of reads and writes. The
pt-diskstats output breaks these out separately and shows them in kB. You can derive
it via a weighted average of rd_avkb and wr_avkb in pt-diskstats, and then multiply by
2 to get sectors (each sector is 512 bytes).
avgqu-sz
This column really represents concurrency at the block device scheduler. The pt-
diskstats output shows concurrency for reads and writes separately: rd_cnc and wr_cnc.
await
This column is the average response time from the beginning to the end of a request to
the block device, including queue time and service time, and is not shown in pt-
diskstats. Instead, pt-diskstats shows individual response times at the disk level
for reads and writes (rd_rt and wr_rt), as well as queue time versus service time for
reads and writes in aggregate.
svctm
This column is the average service time at the disk, and is shown as stime in pt-
diskstats.
%util
This column is called busy in pt-diskstats. Utilization is usually defined as the
portion of time during which there was at least one active request, not as a
percentage, which is why we chose to avoid this confusing term.
COLLECTING DATA
It is straightforward to gather a sample of data for this tool. Files should have this
format, with a timestamp line preceding each sample of statistics:
TS <timestamp>
<contents of /proc/diskstats>
TS <timestamp>
<contents of /proc/diskstats>
... et cetera
You can simply use pt-diskstats with "--save-samples" to collect this data for you. If
you wish to capture samples as part of some other tool, and use pt-diskstats to analyze
them, you can include a snippet of shell script such as the following:
INTERVAL=1
while true; do
sleep=$(date +%s.%N | awk "{print $INTERVAL - (\$1 % $INTERVAL)}")
sleep $sleep
date +"TS %s.%N %F %T" >> diskstats-samples.txt
cat /proc/diskstats >> diskstats-samples.txt
done
KERNEL DOCUMENTATION
This documentation supplements the official documentation
<http://www.kernel.org/doc/Documentation/iostats.txt> on the contents of /proc/diskstats.
That documentation can sometimes be difficult to understand for those who are not familiar
with Linux kernel internals. The contents of /proc/diskstats are generated by the
"diskstats_show()" function in the kernel source file block/genhd.c.
Here is a sample of /proc/diskstats on a recent kernel.
8 1 sda1 426 243 3386 2056 3 0 18 87 0 2135 2142
The fields in this sample are as follows. The first three fields are the major and minor
device numbers (8, 1), and the device name (sda1). They are followed by 11 fields of
statistics:
1. The number of reads completed. This is the number of physical reads done by the
underlying disk, not the number of reads that applications made from the block device.
This means that 426 actual reads have completed successfully to the disk on which
/dev/sda1 resides. Reads are not counted until they complete.
2. The number of reads merged because they were adjacent. In the sample, 243 reads were
merged. This means that /dev/sda1 actually received 869 logical reads, but sent only
426 physical reads to the underlying physical device.
3. The number of sectors read successfully. The 426 physical reads to the disk read 3386
sectors. Sectors are 512 bytes, so a total of about 1.65MB have been read from
/dev/sda1.
4. The number of milliseconds spent reading. This counts only reads that have completed,
not reads that are in progress. It counts the time spent from when requests are
placed on the queue until they complete, not the time that the underlying disk spends
servicing the requests. That is, it measures the total response time seen by
applications, not disk response times.
5. Ditto for field 1, but for writes.
6. Ditto for field 2, but for writes.
7. Ditto for field 3, but for writes.
8. Ditto for field 4, but for writes.
9. The number of I/Os currently in progress, that is, they've been scheduled by the queue
scheduler and issued to the disk (submitted to the underlying disk's queue), but not
yet completed. There are bugs in some kernels that cause this number, and thus fields
10 and 11, to be wrong sometimes.
10. The total number of milliseconds spent doing I/Os. This is not the total response
time seen by the applications; it is the total amount of time during which at least
one I/O was in progress. If one I/O is issued at time 100, another comes in at 101,
and both of them complete at 102, then this field increments by 2, not 3.
11. This field counts the total response time of all I/Os. In contrast to field 10, it
counts double when two I/Os overlap. In our previous example, this field would
increment by 3, not 2.
OPTIONS
This tool accepts additional command-line arguments. Refer to the "SYNOPSIS" and usage
information for details.
--columns-regex
type: string; default: .
Print columns that match this Perl regex.
--config
type: Array
Read this comma-separated list of config files; if specified, this must be the first
option on the command line.
--devices-regex
type: string
Print devices that match this Perl regex.
--group-by
type: string; default: all
Group-by mode: disk, sample, or all. In disk mode, each line of output shows one disk
device, with the statistics computed since the tool started. In sample mode, each
line of output shows one sample of statistics, with all disks averaged together. In
all mode, each line of output shows one sample and one disk device.
--headers
type: Hash; default: group,scroll
If "group" is present, each sample will be separated by a blank line, unless the
sample is only one line. If "scroll" is present, the tool will print the headers as
often as needed to prevent them from scrolling out of view. Note that you can press
the space bar, or the enter key, to reprint headers at will.
--help
Show help and exit.
--interval
type: int; default: 1
When in interactive mode, wait N seconds before printing to the screen. Also, how
often the tool should sample /proc/diskstats.
The tool attempts to gather statistics exactly on even intervals of clock time. That
is, if you specify a 5-second interval, it will try to capture samples at 12:00:00,
12:00:05, and so on; it will not gather at 12:00:01, 12:00:06 and so forth.
This can lead to slightly odd delays in some circumstances, because the tool waits one
full cycle before printing out the first set of lines. (Unlike iostat and vmstat, pt-
diskstats does not start with a line representing the averages since the computer was
booted.) Therefore, the rule has an exception to avoid very long delays. Suppose you
specify a 10-second interval, but you start the tool at 12:00:00.01. The tool might
wait until 12:00:20 to print its first lines of output, and in the intervening 19.99
seconds, it would appear to do nothing.
To alleviate this, the tool waits until the next even interval of time to gather,
unless more than 20% of that interval remains. This means the tool will never wait
more than 120% of the sampling interval to produce output, e.g if you start the tool
at 12:00:53 with a 10-second sampling interval, then the first sample will be only 7
seconds long, not 10 seconds.
--iterations
type: int
When in interactive mode, stop after N samples. Run forever by default.
--sample-time
type: int; default: 1
In --group-by sample mode, include N seconds of samples per group.
--save-samples
type: string
File to save diskstats samples in; these can be used for later analysis.
--show-inactive
Show inactive devices.
--show-timestamps
Show a 'HH:MM:SS' timestamp in the "#ts" column. If multiple timestamps are
aggregated into one line, the first timestamp is shown.
--version
Show version and exit.
--[no]version-check
default: yes
Check for the latest version of Percona Toolkit, MySQL, and other programs.
This is a standard "check for updates automatically" feature, with two additional
features. First, the tool checks its own version and also the versions of the
following software: operating system, Percona Monitoring and Management (PMM), MySQL,
Perl, MySQL driver for Perl (DBD::mysql), and Percona Toolkit. Second, it checks for
and warns about versions with known problems. For example, MySQL 5.5.25 had a critical
bug and was re-released as 5.5.25a.
A secure connection to Percona’s Version Check database server is done to perform
these checks. Each request is logged by the server, including software version numbers
and unique ID of the checked system. The ID is generated by the Percona Toolkit
installation script or when the Version Check database call is done for the first
time.
Any updates or known problems are printed to STDOUT before the tool's normal output.
This feature should never interfere with the normal operation of the tool.
For more information, visit
<https://www.percona.com/doc/percona-toolkit/LATEST/version-check.html>.
ENVIRONMENT
The environment variable "PTDEBUG" enables verbose debugging output to STDERR. To enable
debugging and capture all output to a file, run the tool like:
PTDEBUG=1 pt-diskstats ... > FILE 2>&1
Be careful: debugging output is voluminous and can generate several megabytes of output.
SYSTEM REQUIREMENTS
This tool requires Perl v5.8.0 or newer and the /proc filesystem, unless reading from
files.
BUGS
For a list of known bugs, see <http://www.percona.com/bugs/pt-diskstats>.
Please report bugs at <https://jira.percona.com/projects/PT>. Include the following
information in your bug report:
• Complete command-line used to run the tool
• Tool "--version"
• MySQL version of all servers involved
• Output from the tool including STDERR
• Input files (log/dump/config files, etc.)
If possible, include debugging output by running the tool with "PTDEBUG"; see
"ENVIRONMENT".
DOWNLOADING
Visit <http://www.percona.com/software/percona-toolkit/> to download the latest release of
Percona Toolkit. Or, get the latest release from the command line:
wget percona.com/get/percona-toolkit.tar.gz
wget percona.com/get/percona-toolkit.rpm
wget percona.com/get/percona-toolkit.deb
You can also get individual tools from the latest release:
wget percona.com/get/TOOL
Replace "TOOL" with the name of any tool.
AUTHORS
Baron Schwartz, Brian Fraser, and Daniel Nichter
ABOUT PERCONA TOOLKIT
This tool is part of Percona Toolkit, a collection of advanced command-line tools for
MySQL developed by Percona. Percona Toolkit was forked from two projects in June, 2011:
Maatkit and Aspersa. Those projects were created by Baron Schwartz and primarily
developed by him and Daniel Nichter. Visit <http://www.percona.com/software/> to learn
about other free, open-source software from Percona.
COPYRIGHT, LICENSE, AND WARRANTY
This program is copyright 2011-2018 Percona LLC and/or its affiliates, 2010-2011 Baron
Schwartz.
THIS PROGRAM IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE.
This program is free software; you can redistribute it and/or modify it under the terms of
the GNU General Public License as published by the Free Software Foundation, version 2; OR
the Perl Artistic License. On UNIX and similar systems, you can issue `man perlgpl' or
`man perlartistic' to read these licenses.
You should have received a copy of the GNU General Public License along with this program;
if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
MA 02111-1307 USA.
VERSION
pt-diskstats 3.2.1
POD ERRORS
Hey! The above document had some coding errors, which are explained below:
Around line 5575:
Non-ASCII character seen before =encoding in 'Percona’s'. Assuming UTF-8