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.

2.5.8 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: disk

Group-by mode: disk, sample, or all. In disk mode, each line of output shows one disk device. In sample mode, each line of output shows one sample of statistics. 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 scrollis 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.

2.5.9 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.

2.5.10 SYSTEM REQUIREMENTS

This tool requires Perl v5.8.0 or newer and the /proc filesystem, unless reading from files.

2.5.11 BUGS

For a list of known bugs, seehttp://www.percona.com/bugs/pt-diskstats.

Please report bugs athttps://bugs.launchpad.net/percona-toolkit. 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”.

2.5.12 DOWNLOADING

Visithttp://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.

2.5.13 AUTHORS

Baron Schwartz, Brian Fraser, and Daniel Nichter

2.5.14 ABOUT PERCONA TOOLKIT

This tool is part of Percona Toolkit, a collection of advanced command-line tools developed by Percona for MySQL support and consulting. Percona Toolkit was forked from two projects in June, 2011: Maatkit and Aspersa. Those projects were created by Baron Schwartz and developed primarily by him and Daniel Nichter, both of whom are employed by Percona. Visithttp://www.percona.com/software/for more software developed by Percona.

2.5.15 COPYRIGHT, LICENSE, AND WARRANTY

This program is copyright 2010-2011 Baron Schwartz, 2011-2012 Percona Inc. Feedback and improvements are welcome.

THIS PROGRAM IS PROVIDED “AS IS” AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, IN-CLUDING, 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.

2.5.16 VERSION

pt-diskstats 2.1.1