.. program:: pt-ioprofile ======================= :program:`pt-ioprofile` ======================= NAME ==== :program:`pt-ioprofile` - Watch process IO and print a table of file and I/O activity. SYNOPSIS ======== Usage ----- :: pt-ioprofile [OPTIONS] [FILE] :program:`pt-ioprofile` does two things: 1) get lsof+strace for -s seconds, 2) aggregate the result. If you specify a FILE, then step 1) is not performed. RISKS ===== **WARNING**: :program:`pt-ioprofile` freezes the server and may crash the process, or make it perform badly after detaching, or leave it in a sleeping state! 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 :program:`pt-ioprofile` should be considered an intrusive tool, and should not be used on production servers unless you understand and accept the risks. DESCRIPTION =========== :program:`pt-ioprofile` uses ``strace`` and ``lsof`` to watch a process's IO and print out a table of files and I/O activity. By default, it watches the mysqld process for 30 seconds. The output is like: .. code-block:: bash Tue Dec 27 15:33:57 PST 2011 Tracing process ID 1833 total read write lseek ftruncate filename 0.000150 0.000029 0.000068 0.000038 0.000015 /tmp/ibBE5opS You probably need to run this tool as root. :program:`pt-ioprofile` works by attaching ``strace`` to the process using ``ptrace()``, which will make it run very slowly until ``strace`` detaches. In addition to freezing the server, there is some risk of the process crashing or performing badly after ``strace`` detaches from it, or of ``strace`` not detaching cleanly and leaving the process in a sleeping state. As a result, this should be considered an intrusive tool, and should not be used on production servers unless you are comfortable with that. OPTIONS ======= .. option:: --aggregate short form: -a; type: string; default: sum The aggregate function, either ``sum`` or ``avg``. If sum, then each cell will contain the sum of the values in it. If avg, then each cell will contain the average of the values in it. .. option:: --cell short form: -c; type: string; default: times The cell contents. Valid values are: .. code-block:: bash VALUE CELLS CONTAIN ===== ======================= count Count of I/O operations sizes Sizes of I/O operations times I/O operation timing .. option:: --group-by short form: -g; type: string; default: filename The group-by item. Valid values are: .. code-block:: bash VALUE GROUPING ===== ====================================== all Summarize into a single line of output filename One line of output per filename pid One line of output per process ID .. option:: --help Print help and exit. .. option:: --profile-pid short form: -p; type: int The PID to profile, overrides :option:`--profile-process`. .. option:: --profile-process short form: -b; type: string; default: mysqld The process name to profile. .. option:: --run-time type: int; default: 30 How long to profile. .. option:: --save-samples type: string Filename to save samples in; these can be used for later analysis. .. option:: --version Print the tool's version and exit. ENVIRONMENT =========== This tool does not use any environment variables. SYSTEM REQUIREMENTS =================== This tool requires the Bourne shell (*/bin/sh*). BUGS ==== For a list of known bugs, see `https://jira.percona.com/projects/PT/issues `_. 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 :option:`--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". ATTENTION ========= Using might expose passwords. When debug is enabled, all command line parameters are shown in the output. 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: .. code-block:: bash 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: .. code-block:: bash wget percona.com/get/TOOL Replace ``TOOL`` with the name of any tool. AUTHORS ======= Baron Schwartz 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-2021 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 ======= :program:`pt-ioprofile` 3.5.7