From 2a22fa0fcbf2ede40927599232b242d94d3f06e9 Mon Sep 17 00:00:00 2001 From: Daniel Nichter Date: Wed, 3 Aug 2011 17:17:46 -0600 Subject: [PATCH] Complete user docs. --- bin/pt-diskstats | 2 +- bin/pt-query-digest | 6 +- bin/pt-query-profiler | 4 +- docs/percona-toolkit.pod | 19 +- docs/user/authors.rst | 12 + docs/user/bugs.rst | 35 +++ docs/user/configuration_files.rst | 138 +++++++++++ docs/user/copyright_license_and_warranty.rst | 25 ++ docs/user/environment.rst | 20 ++ docs/user/index.rst | 38 ++- docs/user/pt-align.rst | 187 --------------- docs/user/pt-archiver.rst | 60 ++--- docs/user/pt-checksum-filter.rst | 60 ++--- docs/user/pt-collect.rst | 23 ++ docs/user/pt-config-diff.rst | 60 ++--- docs/user/pt-deadlock-logger.rst | 60 ++--- docs/user/pt-diskstats.rst | 25 +- docs/user/pt-duplicate-key-checker.rst | 60 ++--- docs/user/pt-fifo-split.rst | 60 ++--- docs/user/pt-find.rst | 60 ++--- docs/user/pt-fk-error-logger.rst | 60 ++--- docs/user/pt-heartbeat.rst | 60 ++--- docs/user/pt-index-usage.rst | 60 ++--- docs/user/pt-kill.rst | 60 ++--- docs/user/pt-log-player.rst | 74 +++--- docs/user/pt-mext.rst | 29 ++- docs/user/pt-mysql-summary.rst | 23 ++ docs/user/pt-online-schema-change.rst | 60 ++--- docs/user/pt-pmp.rst | 23 ++ docs/user/pt-profile-compact.rst | 60 ++--- docs/user/pt-query-advisor.rst | 83 ++++--- docs/user/pt-query-digest.rst | 87 +++---- docs/user/pt-query-profiler.rst | 64 ++--- docs/user/pt-rel.rst | 210 ----------------- docs/user/pt-show-grants.rst | 60 ++--- docs/user/pt-sift.rst | 23 ++ docs/user/pt-slave-delay.rst | 60 ++--- docs/user/pt-slave-find.rst | 60 ++--- docs/user/pt-slave-restart.rst | 60 ++--- docs/user/pt-stalk.rst | 23 ++ docs/user/pt-summary.rst | 29 ++- docs/user/pt-table-checksum.rst | 155 ++++++------ docs/user/pt-table-sync.rst | 60 ++--- docs/user/pt-tcp-model.rst | 60 ++--- docs/user/pt-trend.rst | 68 +++--- docs/user/pt-upgrade.rst | 68 +++--- docs/user/pt-variable-advisor.rst | 68 +++--- docs/user/pt-visual-explain.rst | 60 ++--- docs/user/system_requirements.rst | 40 ++++ docs/user/tools.rst | 235 ++++++++++++++++++- docs/user/version.rst | 10 + util/extract-text | 19 ++ util/write-user-docs | 89 +++++-- 53 files changed, 1727 insertions(+), 1427 deletions(-) create mode 100644 docs/user/authors.rst create mode 100644 docs/user/bugs.rst create mode 100644 docs/user/configuration_files.rst create mode 100644 docs/user/copyright_license_and_warranty.rst create mode 100644 docs/user/environment.rst delete mode 100644 docs/user/pt-align.rst delete mode 100644 docs/user/pt-rel.rst create mode 100644 docs/user/system_requirements.rst create mode 100644 docs/user/version.rst create mode 100755 util/extract-text diff --git a/bin/pt-diskstats b/bin/pt-diskstats index 2149f633..5f0e4a5a 100755 --- a/bin/pt-diskstats +++ b/bin/pt-diskstats @@ -762,7 +762,7 @@ scheduler before reaching the device. =item wr_s, wr_avgkb, and wr_mrg -These are analogous to their rd_* cousins. +These are analogous to their C cousins. =back diff --git a/bin/pt-query-digest b/bin/pt-query-digest index 8b9cd22c..6b3206da 100755 --- a/bin/pt-query-digest +++ b/bin/pt-query-digest @@ -13978,9 +13978,9 @@ See L<"--group-by"> for more. When parsing memcached input (L<"--type"> memcached), the fingerprint is an abstracted version of the command and key, with placeholders removed. For -example, "get user_123_preferences" fingerprints to "get user_?_preferences". -There is also a "key_print" which a fingerprinted version of the key. This -example's key_print is "user_?_preferences". +example, C fingerprints to C. +There is also a C which a fingerprinted version of the key. This +example's key_print is C. Query fingerprinting accommodates a great many special cases, which have proven necessary in the real world. For example, an IN list with 5 literals is really diff --git a/bin/pt-query-profiler b/bin/pt-query-profiler index a5319d25..82b84fd4 100755 --- a/bin/pt-query-profiler +++ b/bin/pt-query-profiler @@ -2450,7 +2450,7 @@ from other connections in MySQL 5.0.7 and greater. It is not available before 5.0.1. The total number of questions is not protected, but the breakdown of -individual question types is, because it comes from the Com_ status variables. +individual question types is, because it comes from the C status variables. =head2 Table and index accesses @@ -2476,7 +2476,7 @@ read the next entry in an index. Depending on your MySQL version, you'll either see one or two columns of information in this section. The one headed "Handler" is all from the -Handler_ variables, and those statistics are protected. If your MySQL version +C variables, and those statistics are protected. If your MySQL version supports it, you'll also see a column headed "InnoDB," which is unprotected. =head2 I/O Operations diff --git a/docs/percona-toolkit.pod b/docs/percona-toolkit.pod index 713d89e0..811de30a 100644 --- a/docs/percona-toolkit.pod +++ b/docs/percona-toolkit.pod @@ -15,9 +15,10 @@ they are professionally developed, formally tested, and fully documented. They are also fully self-contained, so installation is quick and easy and no libraries are installed. -Percona Toolkit is developed and supported by Percona Inc. For more -information and other free, open-source software developed by Percona, -visit L. +Percona Toolkit is derived from Maatkit and Aspersa, two of the best-known +toolkits for MySQL server administration. It is developed and supported by +Percona Inc. For more information and other free, open-source software +developed by Percona, visit L. =head1 TOOLS @@ -25,10 +26,6 @@ This release of Percona Toolkit includes the following tools: =over -=item pt-align - -Read lines and split them into words. - =item pt-archiver Archive rows from a MySQL table into another table or a file. @@ -117,10 +114,6 @@ Analyze query execution logs and generate a query report, filter, replay, or tra Execute SQL statements and print statistics, or measure activity caused by other processes. -=item pt-rel - -Make each number in a line of text relative to the previous matching line. - =item pt-show-grants Canonicalize and print MySQL grants so you can effectively replicate, compare and version-control them. @@ -169,10 +162,6 @@ Compute statistics over a set of time-series data points. Execute queries on multiple servers and check for differences. -=item pt-usl - -Model Universal Scalability Law. - =item pt-variable-advisor Analyze MySQL variables and advise on possible problems. diff --git a/docs/user/authors.rst b/docs/user/authors.rst new file mode 100644 index 00000000..420d77bb --- /dev/null +++ b/docs/user/authors.rst @@ -0,0 +1,12 @@ +.. highlight:: perl + + +******* +AUTHORS +******* + + +Percona Toolkit is primarily developed by Baron Schwartz and Daniel Nichter, +both of whom are employed by Percona Inc. See each program's documenation +for details. + diff --git a/docs/user/bugs.rst b/docs/user/bugs.rst new file mode 100644 index 00000000..2760d1a0 --- /dev/null +++ b/docs/user/bugs.rst @@ -0,0 +1,35 @@ +.. highlight:: perl + + +**** +BUGS +**** + + +Please report bugs at `https://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". + diff --git a/docs/user/configuration_files.rst b/docs/user/configuration_files.rst new file mode 100644 index 00000000..1a631af8 --- /dev/null +++ b/docs/user/configuration_files.rst @@ -0,0 +1,138 @@ +.. highlight:: perl + + +******************* +CONFIGURATION FILES +******************* + + +Percona Toolkit tools can read options from configuration files. The +configuration file syntax is simple and direct, and bears some resemblances +to the MySQL command-line client tools. The configuration files all follow +the same conventions. + +Internally, what actually happens is that the lines are read from the file and +then added as command-line options and arguments to the tool, so just +think of the configuration files as a way to write your command lines. + +SYNTAX +====== + + +The syntax of the configuration files is as follows: + + +\* + + Whitespace followed by a hash (#) sign signifies that the rest of the line is a + comment. This is deleted. + + + +\* + + Whitespace is stripped from the beginning and end of all lines. + + + +\* + + Empty lines are ignored. + + + +\* + + Each line is permitted to be in either of the following formats: + + + .. code-block:: perl + + option + option=value + + + Whitespace around the equals sign is deleted during processing. + + + +\* + + Only long options are recognized. + + + +\* + + A line containing only two hyphens signals the end of option parsing. Any + further lines are interpreted as additional arguments (not options) to the + program. + + + + +READ ORDER +========== + + +The tools read several configuration files in order: + + +1. + + The global Percona Toolkit configuration file, + \ */etc/percona-toolkit/percona-toolkit.conf*\ . All tools read this file, + so you should only add options to it that you want to apply to all tools. + + + +2. + + The global tool-specific configuration file, \ */etc/percona-toolkit/TOOL.conf*\ , + where \ ``TOOL``\ is a tool name like \ ``pt-query-digest``\ . This file is named + after the specific tool you're using, so you can add options that apply + only to that tool. + + + +3. + + The user's own Percona Toolkit configuration file, + \ *$HOME/.percona-toolkit.conf*\ . All tools read this file, so you should only + add options to it that you want to apply to all tools. + + + +4. + + The user's tool-specific configuration file, \ *$HOME/.TOOL.conf*\ , + where \ ``TOOL``\ is a tool name like \ ``pt-query-digest``\ . This file is named + after the specific tool you're using, so you can add options that apply + only to that tool. + + + + +SPECIFYING +========== + + +There is a special \ ``--config``\ option, which lets you specify which +configuration files Percona Toolkit should read. You specify a +comma-separated list of files. However, its behavior is not like other +command-line options. It must be given \ **first**\ on the command line, +before any other options. If you try to specify it anywhere else, it will +cause an error. Also, you cannot specify \ ``--config=/path/to/file``\ ; +you must specify the option and the path to the file separated by whitespace +\ *without an equal sign*\ between them, like: + + +.. code-block:: perl + + --config /path/to/file + + +If you don't want any configuration files at all, specify \ ``--config ''``\ to +provide an empty list of files. + + diff --git a/docs/user/copyright_license_and_warranty.rst b/docs/user/copyright_license_and_warranty.rst new file mode 100644 index 00000000..3e6087f4 --- /dev/null +++ b/docs/user/copyright_license_and_warranty.rst @@ -0,0 +1,25 @@ +.. highlight:: perl + + +******************************** +COPYRIGHT, LICENSE, AND WARRANTY +******************************** + + +Percona Toolkit is copyright 2011 Percona Inc. and others. +See each program's documentation for complete copyright notices. + +THIS PROGRAM IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED +WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF +MERCHANTIBILITY 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. + diff --git a/docs/user/environment.rst b/docs/user/environment.rst new file mode 100644 index 00000000..e9cb0ff8 --- /dev/null +++ b/docs/user/environment.rst @@ -0,0 +1,20 @@ +.. highlight:: perl + + +*********** +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: + + +.. code-block:: perl + + PTDEBUG=1 pt-table-checksum ... > FILE 2>&1 + + +Be careful: debugging output is voluminous and can generate several megabytes +of output. + diff --git a/docs/user/index.rst b/docs/user/index.rst index 0eda4968..eae00dd9 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -1,17 +1,33 @@ -Welcome to Percona Toolkit's documentation! -=========================================== +.. highlight:: perl -Contents: + +*********** +DESCRIPTION +*********** + + +Percona Toolkit is a collection of advanced command-line tools used by +Percona (`http://www.percona.com/ `_) support staff to perform a variety of +MySQL and system tasks that are too difficult or complex to perform manually. + +These tools are ideal alternatives to private or "one-off" scripts because +they are professionally developed, formally tested, and fully documented. +They are also fully self-contained, so installation is quick and easy and +no libraries are installed. + +Percona Toolkit is derived from Maatkit and Aspersa, two of the best-known +toolkits for MySQL server administration. It is developed and supported by +Percona Inc. For more information and other free, open-source software +developed by Percona, visit `http://www.percona.com/software/ `_. .. toctree:: :maxdepth: 2 tools - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - + configuration_files + environment + system_requirements + bugs + authors + copyright_license_and_warranty + version diff --git a/docs/user/pt-align.rst b/docs/user/pt-align.rst deleted file mode 100644 index 84ae356e..00000000 --- a/docs/user/pt-align.rst +++ /dev/null @@ -1,187 +0,0 @@ - -######## -pt-align -######## - -.. highlight:: perl - - -**** -NAME -**** - - -pt-align - Read lines and split them into words. - - -******** -SYNOPSIS -******** - - -Usage: pt-align [FILES] - -pt-align reads lines in files and splits them into words. This is useful for -things like aligning the output of vmstat or iostat so it is easier to read. - - -*********** -DESCRIPTION -*********** - - -pt-align counts how many words each line has, and if there is one number that -predominates, it assumes this is the number of words in each line. Then it -discards all lines that don't have that many words, and looks at the 2nd line -that does. It assumes this is the first non-header line. Based on whether -each word looks numeric or not, it decides on column alignment. Finally, it -goes through and decides how wide each column should be, and then prints them -out. - -The tool's behavior has some important consequences. Reading the entire input -before formatting means that you can't use it for aligning data as it is -generated incrementally, and you probably don't want to use this tool on very -large files. Discarding lines with the wrong number of words means that some -lines won't be printed. - - -******* -OPTIONS -******* - - -This tool does not have any command-line options. - - -*********** -ENVIRONMENT -*********** - - -This tool does not use any environment variables. - - -******************* -SYSTEM REQUIREMENTS -******************* - - -This tool requires Perl v5.8 or newer built with core modules. - - -**** -BUGS -**** - - -For a list of known bugs, see `http://www.percona.com/bugs/pt-align `_. - -Please report bugs at `https://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". - - -*********** -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:: perl - - 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:: perl - - 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 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. Visit -`http://www.percona.com/software/ `_ for more software developed by Percona. - - -******************************** -COPYRIGHT, LICENSE, AND WARRANTY -******************************** - - -This program is copyright 2010 Baron Schwartz, 2011 Percona Inc. -Feedback and improvements are welcome. - -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 -******* - - -Percona Toolkit v1.0.0 released 2011-08-01 - diff --git a/docs/user/pt-archiver.rst b/docs/user/pt-archiver.rst index e7b79db8..4e4092d6 100644 --- a/docs/user/pt-archiver.rst +++ b/docs/user/pt-archiver.rst @@ -1403,36 +1403,6 @@ A sample module might look like this: -*********** -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:: perl - - 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:: perl - - wget percona.com/get/TOOL - - -Replace \ ``TOOL``\ with the name of any tool. - - *********** ENVIRONMENT *********** @@ -1495,6 +1465,36 @@ 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: + + +.. code-block:: perl + + 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:: perl + + wget percona.com/get/TOOL + + +Replace \ ``TOOL``\ with the name of any tool. + + ******* AUTHORS ******* diff --git a/docs/user/pt-checksum-filter.rst b/docs/user/pt-checksum-filter.rst index bc6c411f..98a6a4a9 100644 --- a/docs/user/pt-checksum-filter.rst +++ b/docs/user/pt-checksum-filter.rst @@ -173,36 +173,6 @@ This tool accepts additional command-line arguments. Refer to the -*********** -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:: perl - - 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:: perl - - wget percona.com/get/TOOL - - -Replace \ ``TOOL``\ with the name of any tool. - - *********** ENVIRONMENT *********** @@ -265,6 +235,36 @@ 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: + + +.. code-block:: perl + + 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:: perl + + wget percona.com/get/TOOL + + +Replace \ ``TOOL``\ with the name of any tool. + + ******* AUTHORS ******* diff --git a/docs/user/pt-collect.rst b/docs/user/pt-collect.rst index 6e4ce4a2..97762cac 100644 --- a/docs/user/pt-collect.rst +++ b/docs/user/pt-collect.rst @@ -27,6 +27,29 @@ and wants to collect information to assist in diagnosis. Four options must be specified on the command line: -dgios. +***** +RISKS +***** + + +The following section is included to inform users about the potential risks, +whether known or unknown, of using this tool. The two main categories of risks +are those created by the nature of the tool (e.g. read-only tools vs. read-write +tools) and those created by bugs. + +pt-collect is a read-only tool. It should be very low-risk. + +At the time of this release, we know of no bugs that could cause serious harm +to users. + +The authoritative source for updated information is always the online issue +tracking system. Issues that affect this tool will be marked as such. You can +see a list of such issues at the following URL: +`http://www.percona.com/bugs/pt-collect `_. + +See also "BUGS" for more information on filing bugs and getting help. + + *********** DESCRIPTION *********** diff --git a/docs/user/pt-config-diff.rst b/docs/user/pt-config-diff.rst index 9f0bec1e..d12127f0 100644 --- a/docs/user/pt-config-diff.rst +++ b/docs/user/pt-config-diff.rst @@ -373,36 +373,6 @@ comma-separated. See the percona-toolkit manpage for full details. -*********** -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:: perl - - 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:: perl - - wget percona.com/get/TOOL - - -Replace \ ``TOOL``\ with the name of any tool. - - *********** ENVIRONMENT *********** @@ -465,6 +435,36 @@ 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: + + +.. code-block:: perl + + 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:: perl + + wget percona.com/get/TOOL + + +Replace \ ``TOOL``\ with the name of any tool. + + ******* AUTHORS ******* diff --git a/docs/user/pt-deadlock-logger.rst b/docs/user/pt-deadlock-logger.rst index c95e8b64..43511656 100644 --- a/docs/user/pt-deadlock-logger.rst +++ b/docs/user/pt-deadlock-logger.rst @@ -615,36 +615,6 @@ comma-separated. See the percona-toolkit manpage for full details. -*********** -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:: perl - - 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:: perl - - wget percona.com/get/TOOL - - -Replace \ ``TOOL``\ with the name of any tool. - - *********** ENVIRONMENT *********** @@ -707,6 +677,36 @@ 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: + + +.. code-block:: perl + + 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:: perl + + wget percona.com/get/TOOL + + +Replace \ ``TOOL``\ with the name of any tool. + + ******* AUTHORS ******* diff --git a/docs/user/pt-diskstats.rst b/docs/user/pt-diskstats.rst index 35b65063..96e8ae81 100644 --- a/docs/user/pt-diskstats.rst +++ b/docs/user/pt-diskstats.rst @@ -25,6 +25,29 @@ pt-diskstats reads \ */proc/diskstats*\ periodically, or files with the contents of \ */proc/diskstats*\ , aggregates the data, and prints it nicely. +***** +RISKS +***** + + +The following section is included to inform users about the potential risks, +whether known or unknown, of using this tool. The two main categories of risks +are those created by the nature of the tool (e.g. read-only tools vs. read-write +tools) and those created by bugs. + +pt-diskstats is a read-only tool. It should be very low-risk. + +At the time of this release, we know of no bugs that could cause serious harm +to users. + +The authoritative source for updated information is always the online issue +tracking system. Issues that affect this tool will be marked as such. You can +see a list of such issues at the following URL: +`http://www.percona.com/bugs/pt-diskstats `_. + +See also "BUGS" for more information on filing bugs and getting help. + + *********** DESCRIPTION *********** @@ -167,7 +190,7 @@ rd_mrg wr_s, wr_avgkb, and wr_mrg - These are analogous to their rd_\* cousins. + These are analogous to their \ ``rd_\*``\ cousins. diff --git a/docs/user/pt-duplicate-key-checker.rst b/docs/user/pt-duplicate-key-checker.rst index 3280a3ee..9b0e0ab0 100644 --- a/docs/user/pt-duplicate-key-checker.rst +++ b/docs/user/pt-duplicate-key-checker.rst @@ -418,36 +418,6 @@ comma-separated. See the percona-toolkit manpage for full details. -*********** -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:: perl - - 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:: perl - - wget percona.com/get/TOOL - - -Replace \ ``TOOL``\ with the name of any tool. - - *********** ENVIRONMENT *********** @@ -510,6 +480,36 @@ 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: + + +.. code-block:: perl + + 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:: perl + + wget percona.com/get/TOOL + + +Replace \ ``TOOL``\ with the name of any tool. + + ******* AUTHORS ******* diff --git a/docs/user/pt-fifo-split.rst b/docs/user/pt-fifo-split.rst index 3b69d30e..88dcad7b 100644 --- a/docs/user/pt-fifo-split.rst +++ b/docs/user/pt-fifo-split.rst @@ -160,36 +160,6 @@ This tool accepts additional command-line arguments. Refer to the -*********** -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:: perl - - 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:: perl - - wget percona.com/get/TOOL - - -Replace \ ``TOOL``\ with the name of any tool. - - *********** ENVIRONMENT *********** @@ -252,6 +222,36 @@ 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: + + +.. code-block:: perl + + 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:: perl + + wget percona.com/get/TOOL + + +Replace \ ``TOOL``\ with the name of any tool. + + ******* AUTHORS ******* diff --git a/docs/user/pt-find.rst b/docs/user/pt-find.rst index 52d5a43a..3b40cae8 100644 --- a/docs/user/pt-find.rst +++ b/docs/user/pt-find.rst @@ -832,36 +832,6 @@ comma-separated. See the percona-toolkit manpage for full details. -*********** -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:: perl - - 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:: perl - - wget percona.com/get/TOOL - - -Replace \ ``TOOL``\ with the name of any tool. - - *********** ENVIRONMENT *********** @@ -924,6 +894,36 @@ 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: + + +.. code-block:: perl + + 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:: perl + + wget percona.com/get/TOOL + + +Replace \ ``TOOL``\ with the name of any tool. + + ******* AUTHORS ******* diff --git a/docs/user/pt-fk-error-logger.rst b/docs/user/pt-fk-error-logger.rst index 0ae606c8..288f3ee0 100644 --- a/docs/user/pt-fk-error-logger.rst +++ b/docs/user/pt-fk-error-logger.rst @@ -348,36 +348,6 @@ comma-separated. See the percona-toolkit manpage for full details. -*********** -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:: perl - - 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:: perl - - wget percona.com/get/TOOL - - -Replace \ ``TOOL``\ with the name of any tool. - - *********** ENVIRONMENT *********** @@ -440,6 +410,36 @@ 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: + + +.. code-block:: perl + + 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:: perl + + wget percona.com/get/TOOL + + +Replace \ ``TOOL``\ with the name of any tool. + + ******* AUTHORS ******* diff --git a/docs/user/pt-heartbeat.rst b/docs/user/pt-heartbeat.rst index f1627147..cbf788b5 100644 --- a/docs/user/pt-heartbeat.rst +++ b/docs/user/pt-heartbeat.rst @@ -726,36 +726,6 @@ comma-separated. See the percona-toolkit manpage for full details. -*********** -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:: perl - - 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:: perl - - wget percona.com/get/TOOL - - -Replace \ ``TOOL``\ with the name of any tool. - - *********** ENVIRONMENT *********** @@ -818,6 +788,36 @@ 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: + + +.. code-block:: perl + + 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:: perl + + wget percona.com/get/TOOL + + +Replace \ ``TOOL``\ with the name of any tool. + + ******* AUTHORS ******* diff --git a/docs/user/pt-index-usage.rst b/docs/user/pt-index-usage.rst index 43c65adc..7c16c522 100644 --- a/docs/user/pt-index-usage.rst +++ b/docs/user/pt-index-usage.rst @@ -695,36 +695,6 @@ comma-separated. See the percona-toolkit manpage for full details. -*********** -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:: perl - - 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:: perl - - wget percona.com/get/TOOL - - -Replace \ ``TOOL``\ with the name of any tool. - - *********** ENVIRONMENT *********** @@ -787,6 +757,36 @@ 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: + + +.. code-block:: perl + + 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:: perl + + wget percona.com/get/TOOL + + +Replace \ ``TOOL``\ with the name of any tool. + + ******* AUTHORS ******* diff --git a/docs/user/pt-kill.rst b/docs/user/pt-kill.rst index 44b965e4..beb1450b 100644 --- a/docs/user/pt-kill.rst +++ b/docs/user/pt-kill.rst @@ -908,36 +908,6 @@ comma-separated. See the percona-toolkit manpage for full details. -*********** -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:: perl - - 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:: perl - - wget percona.com/get/TOOL - - -Replace \ ``TOOL``\ with the name of any tool. - - *********** ENVIRONMENT *********** @@ -1000,6 +970,36 @@ 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: + + +.. code-block:: perl + + 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:: perl + + wget percona.com/get/TOOL + + +Replace \ ``TOOL``\ with the name of any tool. + + ******* AUTHORS ******* diff --git a/docs/user/pt-log-player.rst b/docs/user/pt-log-player.rst index 5b835411..4c91e5f6 100644 --- a/docs/user/pt-log-player.rst +++ b/docs/user/pt-log-player.rst @@ -564,20 +564,6 @@ This tool accepts additional command-line arguments. Refer to the ---wait-between-sessions - - type: array; default: 0; group: Play - - Not implemented yet. - - The wait time is given in seconds with microsecond precision and can be either - a single value or a range. A single value causes an exact wait; example: - 0.010 = wait 10 milliseconds. A range causes a random wait between - the given value times; example: 0.001,1 = random wait from 1 millisecond to - 1 second. - - - --[no]warnings default: no; group: Play @@ -664,36 +650,6 @@ comma-separated. See the percona-toolkit manpage for full details. -*********** -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:: perl - - 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:: perl - - wget percona.com/get/TOOL - - -Replace \ ``TOOL``\ with the name of any tool. - - *********** ENVIRONMENT *********** @@ -756,6 +712,36 @@ 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: + + +.. code-block:: perl + + 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:: perl + + wget percona.com/get/TOOL + + +Replace \ ``TOOL``\ with the name of any tool. + + ******* AUTHORS ******* diff --git a/docs/user/pt-mext.rst b/docs/user/pt-mext.rst index cabd9ee7..ac27ce8a 100644 --- a/docs/user/pt-mext.rst +++ b/docs/user/pt-mext.rst @@ -28,7 +28,7 @@ Get output from \ ``mysqladmin``\ : .. code-block:: perl - mext -r -- mysqladmin ext -i10 -c3" + pt-mext -r -- mysqladmin ext -i10 -c3" Get output from a file: @@ -36,10 +36,33 @@ Get output from a file: .. code-block:: perl - mext -r -- cat mysqladmin-output.txt + pt-mext -r -- cat mysqladmin-output.txt +***** +RISKS +***** + + +The following section is included to inform users about the potential risks, +whether known or unknown, of using this tool. The two main categories of risks +are those created by the nature of the tool (e.g. read-only tools vs. read-write +tools) and those created by bugs. + +pt-mext is a read-only tool. It should be very low-risk. + +At the time of this release, we know of no bugs that could cause serious harm +to users. + +The authoritative source for updated information is always the online issue +tracking system. Issues that affect this tool will be marked as such. You can +see a list of such issues at the following URL: +`http://www.percona.com/bugs/pt-mext `_. + +See also "BUGS" for more information on filing bugs and getting help. + + *********** DESCRIPTION *********** @@ -80,7 +103,7 @@ SYSTEM REQUIREMENTS ******************* -This tool requires the Bourne shell (\ */bin/sh*\ ). +This tool requires the Bourne shell (\ */bin/sh*\ ) and the seq program. **** diff --git a/docs/user/pt-mysql-summary.rst b/docs/user/pt-mysql-summary.rst index a8b32bf0..4249f8c5 100644 --- a/docs/user/pt-mysql-summary.rst +++ b/docs/user/pt-mysql-summary.rst @@ -28,6 +28,29 @@ and can be pasted into emails without losing the formatting. It should work well on any modern UNIX systems. +***** +RISKS +***** + + +The following section is included to inform users about the potential risks, +whether known or unknown, of using this tool. The two main categories of risks +are those created by the nature of the tool (e.g. read-only tools vs. read-write +tools) and those created by bugs. + +pt-mysql-summary is a read-only tool. It should be very low-risk. + +At the time of this release, we know of no bugs that could cause serious harm +to users. + +The authoritative source for updated information is always the online issue +tracking system. Issues that affect this tool will be marked as such. You can +see a list of such issues at the following URL: +`http://www.percona.com/bugs/pt-mysql-summary `_. + +See also "BUGS" for more information on filing bugs and getting help. + + *********** DESCRIPTION *********** diff --git a/docs/user/pt-online-schema-change.rst b/docs/user/pt-online-schema-change.rst index b89cd881..fc423326 100644 --- a/docs/user/pt-online-schema-change.rst +++ b/docs/user/pt-online-schema-change.rst @@ -639,36 +639,6 @@ comma-separated. See the percona-toolkit manpage for full details. -*********** -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:: perl - - 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:: perl - - wget percona.com/get/TOOL - - -Replace \ ``TOOL``\ with the name of any tool. - - *********** ENVIRONMENT *********** @@ -731,6 +701,36 @@ 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: + + +.. code-block:: perl + + 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:: perl + + wget percona.com/get/TOOL + + +Replace \ ``TOOL``\ with the name of any tool. + + ******* AUTHORS ******* diff --git a/docs/user/pt-pmp.rst b/docs/user/pt-pmp.rst index f6b73b8d..b398143d 100644 --- a/docs/user/pt-pmp.rst +++ b/docs/user/pt-pmp.rst @@ -27,6 +27,29 @@ Summaries of stack traces can be an invaluable tool for diagnosing what a process is waiting for. +***** +RISKS +***** + + +The following section is included to inform users about the potential risks, +whether known or unknown, of using this tool. The two main categories of risks +are those created by the nature of the tool (e.g. read-only tools vs. read-write +tools) and those created by bugs. + +pt-pmp is a read-only tool. It should be very low-risk. + +At the time of this release, we know of no bugs that could cause serious harm +to users. + +The authoritative source for updated information is always the online issue +tracking system. Issues that affect this tool will be marked as such. You can +see a list of such issues at the following URL: +`http://www.percona.com/bugs/pt-pmp `_. + +See also "BUGS" for more information on filing bugs and getting help. + + *********** DESCRIPTION *********** diff --git a/docs/user/pt-profile-compact.rst b/docs/user/pt-profile-compact.rst index 17c4fa88..eca13f2e 100644 --- a/docs/user/pt-profile-compact.rst +++ b/docs/user/pt-profile-compact.rst @@ -142,36 +142,6 @@ This tool accepts additional command-line arguments. Refer to the -*********** -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:: perl - - 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:: perl - - wget percona.com/get/TOOL - - -Replace \ ``TOOL``\ with the name of any tool. - - *********** ENVIRONMENT *********** @@ -234,6 +204,36 @@ 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: + + +.. code-block:: perl + + 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:: perl + + wget percona.com/get/TOOL + + +Replace \ ``TOOL``\ with the name of any tool. + + ******* AUTHORS ******* diff --git a/docs/user/pt-query-advisor.rst b/docs/user/pt-query-advisor.rst index 69f99b66..e6f59451 100644 --- a/docs/user/pt-query-advisor.rst +++ b/docs/user/pt-query-advisor.rst @@ -24,19 +24,30 @@ Usage: pt-query-advisor [OPTION...] [FILE] pt-query-advisor analyzes queries and advises on possible problems. Queries are given either by specifying slowlog files, --query, or --review. +Analyze all queries in a slow log: + .. code-block:: perl - # Analyzer all queries in the given slowlog pt-query-advisor /path/to/slow-query.log - - # Get queries from tcpdump using pt-query-digest - pt-query-digest --type tcpdump.txt --print --no-report | pt-query-advisor - - # Get queries from a general log + + +Analyze all queires in a general log: + + +.. code-block:: perl + pt-query-advisor --type genlog mysql.log +Get queries from tcpdump using pt-query-digest: + + +.. code-block:: perl + + pt-query-digest --type tcpdump.txt --print --no-report | pt-query-advisor + + ***** RISKS @@ -692,36 +703,6 @@ comma-separated. See the percona-toolkit manpage for full details. -*********** -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:: perl - - 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:: perl - - wget percona.com/get/TOOL - - -Replace \ ``TOOL``\ with the name of any tool. - - *********** ENVIRONMENT *********** @@ -784,6 +765,36 @@ 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: + + +.. code-block:: perl + + 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:: perl + + wget percona.com/get/TOOL + + +Replace \ ``TOOL``\ with the name of any tool. + + ******* AUTHORS ******* diff --git a/docs/user/pt-query-digest.rst b/docs/user/pt-query-digest.rst index e33a2533..18bec991 100644 --- a/docs/user/pt-query-digest.rst +++ b/docs/user/pt-query-digest.rst @@ -193,7 +193,7 @@ OUTPUT The default output is a query analysis report. The "--[no]report" option controls whether or not this report is printed. Sometimes you may wish to parse all the queries but suppress the report, for example when using -"--print", "--review" or "--save-results". +"--print" or "--review". There is one paragraph for each class of query analyzed. A "class" of queries all have the same value for the "--group-by" attribute which is @@ -520,9 +520,9 @@ See "--group-by" for more. When parsing memcached input ("--type" memcached), the fingerprint is an abstracted version of the command and key, with placeholders removed. For -example, "get user_123_preferences" fingerprints to "get user_?_preferences". -There is also a "key_print" which a fingerprinted version of the key. This -example's key_print is "user_?_preferences". +example, \ ``get user_123_preferences``\ fingerprints to \ ``get user_?_preferences``\ . +There is also a \ ``key_print``\ which a fingerprinted version of the key. This +example's key_print is \ ``user_?_preferences``\ . Query fingerprinting accommodates a great many special cases, which have proven necessary in the real world. For example, an IN list with 5 literals is really @@ -1128,14 +1128,6 @@ This tool accepts additional command-line arguments. Refer to the ---[no]gzip - - default: yes - - Gzip "--save-results" files; requires IO::Compress::Gzip. - - - --help Show help and exit. @@ -1829,17 +1821,6 @@ This tool accepts additional command-line arguments. Refer to the ---save-results - - type: string - - Save results to the specified file. - - If "--[no]gzip" is true (by default it is) then .gz is appended to the - file name. - - - --select type: Array @@ -2435,36 +2416,6 @@ comma-separated. See the percona-toolkit manpage for full details. -*********** -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:: perl - - 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:: perl - - wget percona.com/get/TOOL - - -Replace \ ``TOOL``\ with the name of any tool. - - *********** ENVIRONMENT *********** @@ -2527,6 +2478,36 @@ 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: + + +.. code-block:: perl + + 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:: perl + + wget percona.com/get/TOOL + + +Replace \ ``TOOL``\ with the name of any tool. + + ******* AUTHORS ******* diff --git a/docs/user/pt-query-profiler.rst b/docs/user/pt-query-profiler.rst index ca3777f2..5bf4c5f5 100644 --- a/docs/user/pt-query-profiler.rst +++ b/docs/user/pt-query-profiler.rst @@ -235,7 +235,7 @@ from other connections in MySQL 5.0.7 and greater. It is not available before 5.0.1. The total number of questions is not protected, but the breakdown of -individual question types is, because it comes from the Com_ status variables. +individual question types is, because it comes from the \ ``Com_``\ status variables. Table and index accesses @@ -267,7 +267,7 @@ read the next entry in an index. Depending on your MySQL version, you'll either see one or two columns of information in this section. The one headed "Handler" is all from the -Handler_ variables, and those statistics are protected. If your MySQL version +\ ``Handler_``\ variables, and those statistics are protected. If your MySQL version supports it, you'll also see a column headed "InnoDB," which is unprotected. @@ -617,36 +617,6 @@ comma-separated. See the percona-toolkit manpage for full details. -*********** -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:: perl - - 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:: perl - - wget percona.com/get/TOOL - - -Replace \ ``TOOL``\ with the name of any tool. - - *********** ENVIRONMENT *********** @@ -709,6 +679,36 @@ 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: + + +.. code-block:: perl + + 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:: perl + + wget percona.com/get/TOOL + + +Replace \ ``TOOL``\ with the name of any tool. + + ******* AUTHORS ******* diff --git a/docs/user/pt-rel.rst b/docs/user/pt-rel.rst deleted file mode 100644 index 96e7934e..00000000 --- a/docs/user/pt-rel.rst +++ /dev/null @@ -1,210 +0,0 @@ - -###### -pt-rel -###### - -.. highlight:: perl - - -**** -NAME -**** - - -pt-rel - Relativize values to previous matching lines. - - -******** -SYNOPSIS -******** - - -Usage: pt-rel [FILES] - -pt-rel matches lines and subtracts the value of the previous line's values -from the current line's values. The lines must be text with numeric values -that repeat, varying only the values. - - -*********** -DESCRIPTION -*********** - - -For example, if the text is this: - - -.. code-block:: perl - - Mutex spin waits 0, rounds 99584819933, OS waits 437663963 - RW-shared spins 834337527, OS waits 20258150; RW-excl spins 1769749834 - Mutex spin waits 0, rounds 99591465498, OS waits 437698122 - RW-shared spins 834352175, OS waits 20259032; RW-excl spins 1769762980 - - -Then the output will be: - - -.. code-block:: perl - - Mutex spin waits 0, rounds 99584819933, OS waits 437663963 - RW-shared spins 834337527, OS waits 20258150; RW-excl spins 1769749834 - Mutex spin waits 0, rounds 6645565, OS waits 34159 - RW-shared spins 14648, OS waits 882; RW-excl spins 13146 - - -The first values (line 1) for "Mutex spin waits", "rounds", and "OS waits" -were subtracted from the second values (line 3); the same happened for values -from lines 2 and 4. - - -******* -OPTIONS -******* - - -This tool does not have any command-line options. - - -*********** -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: - - -.. code-block:: perl - - PTDEBUG=1 pt-rel ... > FILE 2>&1 - - -Be careful: debugging output is voluminous and can generate several megabytes -of output. - - -******************* -SYSTEM REQUIREMENTS -******************* - - -This tool requires Perl v5.8 or newer. - - -**** -BUGS -**** - - -For a list of known bugs, see `http://www.percona.com/bugs/pt-rel `_. - -Please report bugs at `https://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". - - -*********** -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:: perl - - 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:: perl - - 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 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. Visit -`http://www.percona.com/software/ `_ for more software developed by Percona. - - -******************************** -COPYRIGHT, LICENSE, AND WARRANTY -******************************** - - -This program is copyright 2010 Baron Schwartz, 2011 Percona Inc. -Feedback and improvements are welcome. - -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 -******* - - -Percona Toolkit v1.0.0 released 2011-08-01 - diff --git a/docs/user/pt-show-grants.rst b/docs/user/pt-show-grants.rst index eb530e9b..2ff29468 100644 --- a/docs/user/pt-show-grants.rst +++ b/docs/user/pt-show-grants.rst @@ -389,36 +389,6 @@ comma-separated. See the percona-toolkit manpage for full details. -*********** -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:: perl - - 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:: perl - - wget percona.com/get/TOOL - - -Replace \ ``TOOL``\ with the name of any tool. - - *********** ENVIRONMENT *********** @@ -481,6 +451,36 @@ 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: + + +.. code-block:: perl + + 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:: perl + + wget percona.com/get/TOOL + + +Replace \ ``TOOL``\ with the name of any tool. + + ******* AUTHORS ******* diff --git a/docs/user/pt-sift.rst b/docs/user/pt-sift.rst index f180dfb8..540e5e35 100644 --- a/docs/user/pt-sift.rst +++ b/docs/user/pt-sift.rst @@ -26,6 +26,29 @@ FILE or PREFIX, it browses only files with that prefix. If you specify a DIRECTORY, then it browses all files within that directory. +***** +RISKS +***** + + +The following section is included to inform users about the potential risks, +whether known or unknown, of using this tool. The two main categories of risks +are those created by the nature of the tool (e.g. read-only tools vs. read-write +tools) and those created by bugs. + +pt-sift is a read-only tool. It should be very low-risk. + +At the time of this release, we know of no bugs that could cause serious harm +to users. + +The authoritative source for updated information is always the online issue +tracking system. Issues that affect this tool will be marked as such. You can +see a list of such issues at the following URL: +`http://www.percona.com/bugs/pt-sift `_. + +See also "BUGS" for more information on filing bugs and getting help. + + *********** DESCRIPTION *********** diff --git a/docs/user/pt-slave-delay.rst b/docs/user/pt-slave-delay.rst index 4f3001ed..ae6659af 100644 --- a/docs/user/pt-slave-delay.rst +++ b/docs/user/pt-slave-delay.rst @@ -386,36 +386,6 @@ comma-separated. See the percona-toolkit manpage for full details. -*********** -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:: perl - - 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:: perl - - wget percona.com/get/TOOL - - -Replace \ ``TOOL``\ with the name of any tool. - - *********** ENVIRONMENT *********** @@ -478,6 +448,36 @@ 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: + + +.. code-block:: perl + + 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:: perl + + wget percona.com/get/TOOL + + +Replace \ ``TOOL``\ with the name of any tool. + + ******* AUTHORS ******* diff --git a/docs/user/pt-slave-find.rst b/docs/user/pt-slave-find.rst index 194ce521..0706003e 100644 --- a/docs/user/pt-slave-find.rst +++ b/docs/user/pt-slave-find.rst @@ -398,36 +398,6 @@ comma-separated. See the percona-toolkit manpage for full details. -*********** -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:: perl - - 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:: perl - - wget percona.com/get/TOOL - - -Replace \ ``TOOL``\ with the name of any tool. - - *********** ENVIRONMENT *********** @@ -490,6 +460,36 @@ 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: + + +.. code-block:: perl + + 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:: perl + + wget percona.com/get/TOOL + + +Replace \ ``TOOL``\ with the name of any tool. + + ******* AUTHORS ******* diff --git a/docs/user/pt-slave-restart.rst b/docs/user/pt-slave-restart.rst index cccef6a5..4612d6af 100644 --- a/docs/user/pt-slave-restart.rst +++ b/docs/user/pt-slave-restart.rst @@ -610,36 +610,6 @@ comma-separated. See the percona-toolkit manpage for full details. -*********** -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:: perl - - 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:: perl - - wget percona.com/get/TOOL - - -Replace \ ``TOOL``\ with the name of any tool. - - *********** ENVIRONMENT *********** @@ -702,6 +672,36 @@ 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: + + +.. code-block:: perl + + 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:: perl + + wget percona.com/get/TOOL + + +Replace \ ``TOOL``\ with the name of any tool. + + ******* AUTHORS ******* diff --git a/docs/user/pt-stalk.rst b/docs/user/pt-stalk.rst index dba94c68..7477149c 100644 --- a/docs/user/pt-stalk.rst +++ b/docs/user/pt-stalk.rst @@ -27,6 +27,29 @@ This tool is useful for gathering diagnostic data when an infrequent event occurs, so an expert person can review the data later. +***** +RISKS +***** + + +The following section is included to inform users about the potential risks, +whether known or unknown, of using this tool. The two main categories of risks +are those created by the nature of the tool (e.g. read-only tools vs. read-write +tools) and those created by bugs. + +pt-stalk is a read-only tool. It should be very low-risk. + +At the time of this release, we know of no bugs that could cause serious harm +to users. + +The authoritative source for updated information is always the online issue +tracking system. Issues that affect this tool will be marked as such. You can +see a list of such issues at the following URL: +`http://www.percona.com/bugs/pt-stalk `_. + +See also "BUGS" for more information on filing bugs and getting help. + + *********** DESCRIPTION *********** diff --git a/docs/user/pt-summary.rst b/docs/user/pt-summary.rst index 81a8883e..fb406fab 100644 --- a/docs/user/pt-summary.rst +++ b/docs/user/pt-summary.rst @@ -31,8 +31,8 @@ Download and run: .. code-block:: perl - wget http://aspersa.googlecode.com/svn/trunk/summary - bash ./summary + wget http://percona.com/get/pt-summary + bash ./pt-summary Download and run in a single step: @@ -40,10 +40,33 @@ Download and run in a single step: .. code-block:: perl - wget -O- http://aspersa.googlecode.com/svn/trunk/summary | bash + wget -O- http://percona.com/get/summary | bash +***** +RISKS +***** + + +The following section is included to inform users about the potential risks, +whether known or unknown, of using this tool. The two main categories of risks +are those created by the nature of the tool (e.g. read-only tools vs. read-write +tools) and those created by bugs. + +pt-summary is a read-only tool. It should be very low-risk. + +At the time of this release, we know of no bugs that could cause serious harm +to users. + +The authoritative source for updated information is always the online issue +tracking system. Issues that affect this tool will be marked as such. You can +see a list of such issues at the following URL: +`http://www.percona.com/bugs/pt-summary `_. + +See also "BUGS" for more information on filing bugs and getting help. + + *********** DESCRIPTION *********** diff --git a/docs/user/pt-table-checksum.rst b/docs/user/pt-table-checksum.rst index bbcebb73..05fe5626 100644 --- a/docs/user/pt-table-checksum.rst +++ b/docs/user/pt-table-checksum.rst @@ -26,32 +26,33 @@ Each host is specified as a DSN and missing values are inherited from the first host. If you specify multiple hosts, the first is assumed to be the master. -STOP! Are you checksumming a slave(s) against its master? Then be sure to learn +\ **STOP!**\ Are you checksumming slaves against a master? Then be sure to learn what "--replicate" does. It is probably the option you want to use. - -.. code-block:: perl - - pt-table-checksum --replicate=mydb.checksum master-host - ... time passses, replication catches up ... - pt-table-checksum --replicate=mydb.checksum --replicate-check 2 \ - master-host - - -Or, +Checksum all slaves against the master: .. code-block:: perl - pt-table-checksum h=host1,u=user,p=password h=host2 ... + pt-table-checksum \ + h=master-host \ + --replicate mydb.checksums + + # Wait for first command to complete and replication to catchup + # on all slaves, then... + + pt-table-checksum \ + h=master-host \ + --replicat mydb.checksums \ + --replicate-check 2 -Or, +Checksum all databases and tables on two servers and print the differences: .. code-block:: perl - pt-table-checksum host1 host2 ... hostN | pt-checksum-filter + pt-table-checksum h=host1,u=user h=host2 | pt-checksum-filter See "SPECIFYING HOSTS" for more on the syntax of the host arguments. @@ -130,55 +131,36 @@ SPECIFYING HOSTS **************** -pt-table-checksum connects to a theoretically unlimited number of MySQL -servers. You specify a list of one or more host definitions on the command -line, such as "host1 host2". Each host definition can be just a hostname, or it -can be a complex string that specifies connection options as well. You can -specify connection options two ways: +Each host is specified on the command line as a DSN. A DSN is a comma-separted +list of \ ``option=value``\ pairs. The most basic DSN is \ ``h=host``\ to specify +the hostname of the server and use default for everything else (port, etc.). +See "DSN OPTIONS" for more information. +DSN options that are listed as \ ``copy: yes``\ are copied from the first DSN +to subsequent DSNs that do not specify the DSN option. For example, +\ ``h=host1,P=12345 h=host2``\ is equivalent to \ ``h=host1,P=12345 h=host2,P=12345``\ . +This allows you to avoid repeating DSN options that have the same value +for all DSNs. -\* - - Format a host definition in a key=value,key=value form. If an argument on the - command line contains the letter '=', pt-table-checksum will parse it into - its component parts. Examine the "--help" output for details on the allowed - keys. - - Specifying a list of simple host definitions "host1 host2" is equivalent to the - more complicated "h=host1 h=host2" format. - +Connection-related command-line options like "--user" and "--password" +provide default DSN values for the corresponding DSN options indicated by +the short form of each option. For example, the short form of "--user" +is \ ``-u``\ which corresponds to the \ ``u``\ DSN option, so \ ``--user bob h=host``\ +is equivalent to \ ``h=host,u=bob``\ . These defaults apply to all DSNs that +do not specify the DSN option. - -\* - - With the command-line options such as "--user" and "--password". These - options, if given, apply globally to all host definitions. - - - -In addition to specifying connection options this way, pt-table-checksum -allows shortcuts. Any options specified for the first host definition on the -command line fill in missing values in subsequent ones. Any options that are -still missing after this are filled in from the command-line options if -possible. - -In other words, the places you specify connection options have precedence: -highest precedence is the option specified directly in the host definition, next -is the option specified in the first host definition, and lowest is the -command-line option. - -You can mix simple and complex host definitions and/or command-line arguments. -For example, if all your servers except one of your slaves uses a non-standard -port number: +The DSN option value precedence from higest to lowest is: .. code-block:: perl - pt-table-checksum --port 4500 master h=slave1,P=3306 slave2 slave3 + * explicit values in each DSN on the command-line + * copied values from the first DSN + * default values from connection-related command-line options If you are confused about how pt-table-checksum will connect to your servers, -give the "--explain-hosts" option and it will tell you. +use the "--explain-hosts" option and it will tell you. *************** @@ -987,10 +969,9 @@ This tool accepts additional command-line arguments. Refer to the group: Help - Print connection information and exit. - - Print out a list of hosts to which pt-table-checksum will connect, with all - the various connection options, and exit. See "SPECIFYING HOSTS". + Print full DSNs for each host and exit. This option allows you to see how + pt-table-checksum parses DSNs from the command-line and how it will connect + to those hosts. See "SPECIFYING HOSTS". @@ -1901,36 +1882,6 @@ comma-separated. See the percona-toolkit manpage for full details. -*********** -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:: perl - - 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:: perl - - wget percona.com/get/TOOL - - -Replace \ ``TOOL``\ with the name of any tool. - - *********** ENVIRONMENT *********** @@ -1993,6 +1944,36 @@ 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: + + +.. code-block:: perl + + 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:: perl + + wget percona.com/get/TOOL + + +Replace \ ``TOOL``\ with the name of any tool. + + ******* AUTHORS ******* diff --git a/docs/user/pt-table-sync.rst b/docs/user/pt-table-sync.rst index a9b30e51..6d8dd65e 100644 --- a/docs/user/pt-table-sync.rst +++ b/docs/user/pt-table-sync.rst @@ -1426,36 +1426,6 @@ comma-separated. See the percona-toolkit manpage for full details. -*********** -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:: perl - - 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:: perl - - wget percona.com/get/TOOL - - -Replace \ ``TOOL``\ with the name of any tool. - - *********** ENVIRONMENT *********** @@ -1518,6 +1488,36 @@ 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: + + +.. code-block:: perl + + 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:: perl + + wget percona.com/get/TOOL + + +Replace \ ``TOOL``\ with the name of any tool. + + ******* AUTHORS ******* diff --git a/docs/user/pt-tcp-model.rst b/docs/user/pt-tcp-model.rst index 3f26e9d2..4a92af56 100644 --- a/docs/user/pt-tcp-model.rst +++ b/docs/user/pt-tcp-model.rst @@ -386,36 +386,6 @@ This tool accepts additional command-line arguments. Refer to the -*********** -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:: perl - - 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:: perl - - wget percona.com/get/TOOL - - -Replace \ ``TOOL``\ with the name of any tool. - - *********** ENVIRONMENT *********** @@ -478,6 +448,36 @@ 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: + + +.. code-block:: perl + + 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:: perl + + wget percona.com/get/TOOL + + +Replace \ ``TOOL``\ with the name of any tool. + + ******* AUTHORS ******* diff --git a/docs/user/pt-trend.rst b/docs/user/pt-trend.rst index 1a674943..487be45e 100644 --- a/docs/user/pt-trend.rst +++ b/docs/user/pt-trend.rst @@ -106,14 +106,6 @@ This tool accepts additional command-line arguments. Refer to the ---quiet - - short form: -q - - Disables "--progress". - - - --version Show version and exit. @@ -121,36 +113,6 @@ This tool accepts additional command-line arguments. Refer to the -*********** -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:: perl - - 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:: perl - - wget percona.com/get/TOOL - - -Replace \ ``TOOL``\ with the name of any tool. - - *********** ENVIRONMENT *********** @@ -213,6 +175,36 @@ 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: + + +.. code-block:: perl + + 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:: perl + + wget percona.com/get/TOOL + + +Replace \ ``TOOL``\ with the name of any tool. + + ******* AUTHORS ******* diff --git a/docs/user/pt-upgrade.rst b/docs/user/pt-upgrade.rst index 0b5579b3..4888a0db 100644 --- a/docs/user/pt-upgrade.rst +++ b/docs/user/pt-upgrade.rst @@ -505,14 +505,6 @@ This tool accepts additional command-line arguments. Refer to the ---[no]report - - default: yes - - Print the "--reports". - - - --reports type: Hash; default: queries,differences,errors,statistics @@ -687,36 +679,6 @@ comma-separated. See the percona-toolkit manpage for full details. -*********** -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:: perl - - 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:: perl - - wget percona.com/get/TOOL - - -Replace \ ``TOOL``\ with the name of any tool. - - *********** ENVIRONMENT *********** @@ -779,6 +741,36 @@ 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: + + +.. code-block:: perl + + 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:: perl + + wget percona.com/get/TOOL + + +Replace \ ``TOOL``\ with the name of any tool. + + ******* AUTHORS ******* diff --git a/docs/user/pt-variable-advisor.rst b/docs/user/pt-variable-advisor.rst index b92225d4..fedb1955 100644 --- a/docs/user/pt-variable-advisor.rst +++ b/docs/user/pt-variable-advisor.rst @@ -757,14 +757,6 @@ This tool accepts additional command-line arguments. Refer to the ---[no]continue-on-error - - default: yes - - Continue working even if there is an error. - - - --daemonize Fork to the background and detach from the shell. POSIX @@ -963,36 +955,6 @@ comma-separated. See the percona-toolkit manpage for full details. -*********** -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:: perl - - 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:: perl - - wget percona.com/get/TOOL - - -Replace \ ``TOOL``\ with the name of any tool. - - *********** ENVIRONMENT *********** @@ -1055,6 +1017,36 @@ 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: + + +.. code-block:: perl + + 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:: perl + + wget percona.com/get/TOOL + + +Replace \ ``TOOL``\ with the name of any tool. + + ******* AUTHORS ******* diff --git a/docs/user/pt-visual-explain.rst b/docs/user/pt-visual-explain.rst index 6a1c20c5..bbb23055 100644 --- a/docs/user/pt-visual-explain.rst +++ b/docs/user/pt-visual-explain.rst @@ -818,36 +818,6 @@ comma-separated. See the percona-toolkit manpage for full details. -*********** -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:: perl - - 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:: perl - - wget percona.com/get/TOOL - - -Replace \ ``TOOL``\ with the name of any tool. - - *********** ENVIRONMENT *********** @@ -910,6 +880,36 @@ 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: + + +.. code-block:: perl + + 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:: perl + + wget percona.com/get/TOOL + + +Replace \ ``TOOL``\ with the name of any tool. + + ******* AUTHORS ******* diff --git a/docs/user/system_requirements.rst b/docs/user/system_requirements.rst new file mode 100644 index 00000000..63031c89 --- /dev/null +++ b/docs/user/system_requirements.rst @@ -0,0 +1,40 @@ +.. highlight:: perl + + +******************* +SYSTEM REQUIREMENTS +******************* + + +Most tools require: + + +\* Perl v5.8 or newer + + + +\* Bash v3 or newer + + + +\* Core Perl modules like Time::HiRes + + + +Tools that connect to MySQL require: + + +\* Perl modules DBI and DBD::mysql + + + +\* MySQL 5.0 or newer + + + +Percona Toolkit is only tested on UNIX systems, primarily Debian and +Red Hat derivatives; other operating systems are not supported. + +Tools that connect to MySQL may work with MySQL v4.1, but this is not +test or supported. + diff --git a/docs/user/tools.rst b/docs/user/tools.rst index 06ffa341..116aeb09 100644 --- a/docs/user/tools.rst +++ b/docs/user/tools.rst @@ -1,12 +1,236 @@ -Tools -===== +.. highlight:: perl -Contents: + +***** +TOOLS +***** + + +This release of Percona Toolkit includes the following tools: + + +:doc:`pt-archiver` + + Archive rows from a MySQL table into another table or a file. + + + +:doc:`pt-checksum-filter` + + Filter checksums from pt-table-checksum. + + + +:doc:`pt-collect` + + Collect information from a server for some period of time. + + + +:doc:`pt-config-diff` + + Diff MySQL configuration files and server variables. + + + +:doc:`pt-deadlock-logger` + + Extract and log MySQL deadlock information. + + + +:doc:`pt-diskstats` + + Read a file generated from /proc/diskstats and summarize it. + + + +:doc:`pt-duplicate-key-checker` + + Find duplicate indexes and foreign keys on MySQL tables. + + + +:doc:`pt-fifo-split` + + Split files and pipe lines to a fifo without really splitting. + + + +:doc:`pt-find` + + Find MySQL tables and execute actions, like GNU find. + + + +:doc:`pt-fk-error-logger` + + Extract and log MySQL foreign key errors. + + + +:doc:`pt-heartbeat` + + Monitor MySQL replication delay. + + + +:doc:`pt-index-usage` + + Read queries from a log and analyze how they use indexes. + + + +:doc:`pt-kill` + + Kill MySQL queries that match certain criteria. + + + +:doc:`pt-log-player` + + Replay MySQL query logs. + + + +:doc:`pt-mext` + + Aggregate and summarize mysqladmin extended output. + + + +:doc:`pt-mysql-summary` + + Summarize MySQL information in a nice way. + + + +:doc:`pt-online-schema-change` + + Perform online, non-blocking table schema changes. + + + +:doc:`pt-pmp` + + Aggregate GDB stack traces for a selected program. + + + +:doc:`pt-profile-compact` + + Compact the output from pt-query-profiler. + + + +:doc:`pt-query-advisor` + + Analyze queries and advise on possible problems. + + + +:doc:`pt-query-digest` + + Analyze query execution logs and generate a query report, filter, replay, or transform queries for MySQL, PostgreSQL, memcached, and more. + + + +:doc:`pt-query-profiler` + + Execute SQL statements and print statistics, or measure activity caused by other processes. + + + +:doc:`pt-show-grants` + + Canonicalize and print MySQL grants so you can effectively replicate, compare and version-control them. + + + +:doc:`pt-sift` + + Browses the files created by the collect tool. + + + +:doc:`pt-slave-delay` + + Make a MySQL slave server lag behind its master. + + + +:doc:`pt-slave-find` + + Find and print replication hierarchy tree of MySQL slaves. + + + +:doc:`pt-slave-restart` + + Watch and restart MySQL replication after errors. + + + +:doc:`pt-stalk` + + Watch MySQL and run the 'collect' program when some condition becomes true. + + + +:doc:`pt-summary` + + Summarize system information in a nice way. + + + +:doc:`pt-table-checksum` + + Perform an online replication consistency check, or checksum MySQL tables efficiently on one or many servers. + + + +:doc:`pt-table-sync` + + Synchronize MySQL table data efficiently. + + + +:doc:`pt-tcp-model` + + Transform tcpdump into metrics that permit performance and scalability modeling. + + + +:doc:`pt-trend` + + Compute statistics over a set of time-series data points. + + + +:doc:`pt-upgrade` + + Execute queries on multiple servers and check for differences. + + + +:doc:`pt-variable-advisor` + + Analyze MySQL variables and advise on possible problems. + + + +:doc:`pt-visual-explain` + + Format EXPLAIN output as a tree. + + + +For more free, open-source software developed Percona, visit +`http://www.percona.com/software/ `_. .. toctree:: - :maxdepth: 1 + :hidden: - pt-align pt-archiver pt-checksum-filter pt-collect @@ -29,7 +253,6 @@ Contents: pt-query-advisor pt-query-digest pt-query-profiler - pt-rel pt-show-grants pt-sift pt-slave-delay diff --git a/docs/user/version.rst b/docs/user/version.rst new file mode 100644 index 00000000..e4f445b1 --- /dev/null +++ b/docs/user/version.rst @@ -0,0 +1,10 @@ +.. highlight:: perl + + +******* +VERSION +******* + + +Percona Toolkit v1.0.0 released 2008-08-01 + diff --git a/util/extract-text b/util/extract-text new file mode 100755 index 00000000..6b08427e --- /dev/null +++ b/util/extract-text @@ -0,0 +1,19 @@ +#!/usr/bin/env bash + +die() { + echo "$1" >&2 + exit 1 +} + +file=$1 +from=$2 +to=$3 + +start_line=$(grep --line-number "$from" $file | cut -d':' -f1) +if [ -z "$start_line" ]; then + die "Cannot find $from in $file" +fi + +tail -n +$start_line $file | awk "BEGIN { getline; print \$0 } /$to/ { exit } { print }" + +exit $? diff --git a/util/write-user-docs b/util/write-user-docs index 35cba6d4..fae7c70e 100755 --- a/util/write-user-docs +++ b/util/write-user-docs @@ -1,20 +1,24 @@ #!/usr/bin/env bash -# Usage: write-user-docs [TOOL...] +# Usage: write-user-docs [FILES] # # This script writes/updates a tool's user documentation. First, pod2rst -# is called to convert the tool's POD to RST. Then sphinx-build is called +# is called to convert the file's POD to RST. Then sphinx-build is called # to convert the RST to HTML. # # RST files are written to docs/user/.rst, and HTML files are written # to docs/user/html/.html. # -# If no tools are specified on the command line, then user docs for all Perl -# tools in bin/ are written. +# If no file are specified on the command line, then only the sections from +# docs/percona-toolkit.pod are written. # # If the env variable PERCONA_TOOLKIT_BRANCH is not set, then this script # must be called from a directory in a branch. # +# To rewrite all user docs from scratch: +# rm -rf docs/user/* +# util/write-user-docs bin/* +# # Exits 0 on success, else 1 on warnings and errors. # ############################################################################ @@ -33,6 +37,7 @@ warn() { exit_status=1 } +cwd=$PWD if [ -n "$PERCONA_TOOLKIT_BRANCH" ]; then BRANCH=$PERCONA_TOOLKIT_BRANCH cd $BRANCH @@ -46,13 +51,15 @@ else fi BRANCH=`pwd` fi +cd $cwd # ############################################################################ # Paths # ############################################################################ -RST=$BRANCH/docs/user -HTML=$BRANCH/docs/user/html +DOCS=$BRANCH/docs +RST=$DOCS/user +HTML=$RST/html CONFIG=$BRANCH/config/sphinx-build # ############################################################################ @@ -60,34 +67,78 @@ CONFIG=$BRANCH/config/sphinx-build # ############################################################################ write_rst() { - tool="$1" - if [ ! -f $tool ]; then - warn "Tool $tool does not exist" + local file="$1" + if [ ! -f $file ]; then + warn "$file does not exist" return fi + local tool=$(basename $file) - cat $tool | pod2rst --title=$tool > $RST/$tool.rst + cat $file | pod2rst --title=$tool > $RST/$tool.rst exit_status=$(( exit_status | $? )) echo "Wrote $RST/$tool.rst" } +write_index() { + declare -a section_filenames + local i=0 + + sections=$(grep '^=head1' $DOCS/percona-toolkit.pod | grep -v "NAME" | sed -e 's/=head1 //' -e 's/ /_/g') + for section in $sections; do + header=$(echo $section | sed -e 's/_/ /g') + + if [ $section = "DESCRIPTION" ]; then + filename="index" + else + filename=$(echo $section | sed -e 's/,//g' | tr "[:upper:]" "[:lower:]"); + section_filenames[$i]=$filename + i=$(($i + 1)) + fi + + $BRANCH/util/extract-text $DOCS/percona-toolkit.pod "^=head1 $header" "^=head1|=cut" > /tmp/$filename.pod + cat /tmp/$filename.pod | pod2rst > $RST/$filename.rst + rm /tmp/$filename.pod + echo "Wrote $RST/$filename.rst" + done + + echo ".. toctree::" >> $RST/index.rst + echo " :maxdepth: 2" >> $RST/index.rst + echo >> $RST/index.rst + for section_filename in "${section_filenames[@]}"; do + echo " $section_filename" >> $RST/index.rst + done + + echo ".. toctree::" >> $RST/tools.rst + echo " :hidden:" >> $RST/tools.rst + echo >> $RST/tools.rst + local tools=$(grep '^pt-' $RST/tools.rst) + for tool in $tools; do + echo " $tool" >> $RST/tools.rst + done + + sed -e 's/^\(pt-.*\)/:doc:`\1`/g' -i.bak $RST/tools.rst + rm $RST/*.bak +} + # ############################################################################ # Script starts here # ############################################################################ -cd $BRANCH/bin -if [ -z $@ ]; then - for tool in *; do - write_rst $tool - done -else +if [ $# -gt 0 ]; then for tool; do write_rst $tool done fi -# -W treats warnings as errors; remove it to ignore warnings if you must. -sphinx-build -W -c $CONFIG -b html $RST $HTML -exit_status=$(( exit_status | $? )) +if [ "$DOCS/percona-toolkit.pod" -nt "$RST/index.rst" ]; then + write_index +fi + +BUILD=${BUILD:-1} +if [ $BUILD -eq 1 ]; then + # -W treats warnings as errors; remove it to ignore warnings if you must. + sphinx-build -W -c $CONFIG -b html $RST $HTML + exit_status=$(( exit_status | $? )) +fi exit $exit_status