diff --git a/.bzrignore b/.bzrignore index 94c66994..f50bec1a 100644 --- a/.bzrignore +++ b/.bzrignore @@ -5,3 +5,4 @@ docs/test-coverage/db docs/test-coverage/html release .DS_Store +build diff --git a/docs/user/Makefile b/docs/user/Makefile new file mode 100644 index 00000000..0c2373ac --- /dev/null +++ b/docs/user/Makefile @@ -0,0 +1,130 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = build + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + -rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/PerconaXtraBackup.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/PerconaXtraBackup.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/PerconaXtraBackup" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/PerconaXtraBackup" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + make -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." diff --git a/docs/user/make.bat b/docs/user/make.bat new file mode 100644 index 00000000..4bc6b71e --- /dev/null +++ b/docs/user/make.bat @@ -0,0 +1,170 @@ +@ECHO OFF + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set BUILDDIR=build +set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% source +if NOT "%PAPER%" == "" ( + set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% +) + +if "%1" == "" goto help + +if "%1" == "help" ( + :help + echo.Please use `make ^` where ^ is one of + echo. html to make standalone HTML files + echo. dirhtml to make HTML files named index.html in directories + echo. singlehtml to make a single large HTML file + echo. pickle to make pickle files + echo. json to make JSON files + echo. htmlhelp to make HTML files and a HTML help project + echo. qthelp to make HTML files and a qthelp project + echo. devhelp to make HTML files and a Devhelp project + echo. epub to make an epub + echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter + echo. text to make text files + echo. man to make manual pages + echo. changes to make an overview over all changed/added/deprecated items + echo. linkcheck to check all external links for integrity + echo. doctest to run all doctests embedded in the documentation if enabled + goto end +) + +if "%1" == "clean" ( + for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i + del /q /s %BUILDDIR%\* + goto end +) + +if "%1" == "html" ( + %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/html. + goto end +) + +if "%1" == "dirhtml" ( + %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. + goto end +) + +if "%1" == "singlehtml" ( + %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. + goto end +) + +if "%1" == "pickle" ( + %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the pickle files. + goto end +) + +if "%1" == "json" ( + %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the JSON files. + goto end +) + +if "%1" == "htmlhelp" ( + %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run HTML Help Workshop with the ^ +.hhp project file in %BUILDDIR%/htmlhelp. + goto end +) + +if "%1" == "qthelp" ( + %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run "qcollectiongenerator" with the ^ +.qhcp project file in %BUILDDIR%/qthelp, like this: + echo.^> qcollectiongenerator %BUILDDIR%\qthelp\PerconaXtraBackup.qhcp + echo.To view the help file: + echo.^> assistant -collectionFile %BUILDDIR%\qthelp\PerconaXtraBackup.ghc + goto end +) + +if "%1" == "devhelp" ( + %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. + goto end +) + +if "%1" == "epub" ( + %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The epub file is in %BUILDDIR%/epub. + goto end +) + +if "%1" == "latex" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "text" ( + %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The text files are in %BUILDDIR%/text. + goto end +) + +if "%1" == "man" ( + %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The manual pages are in %BUILDDIR%/man. + goto end +) + +if "%1" == "changes" ( + %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes + if errorlevel 1 exit /b 1 + echo. + echo.The overview file is in %BUILDDIR%/changes. + goto end +) + +if "%1" == "linkcheck" ( + %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck + if errorlevel 1 exit /b 1 + echo. + echo.Link check complete; look for any errors in the above output ^ +or in %BUILDDIR%/linkcheck/output.txt. + goto end +) + +if "%1" == "doctest" ( + %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest + if errorlevel 1 exit /b 1 + echo. + echo.Testing of doctests in the sources finished, look at the ^ +results in %BUILDDIR%/doctest/output.txt. + goto end +) + +:end diff --git a/docs/user/pt-collect.rst b/docs/user/pt-collect.rst deleted file mode 100644 index 342495e7..00000000 --- a/docs/user/pt-collect.rst +++ /dev/null @@ -1,264 +0,0 @@ - -########## -pt-collect -########## - -.. highlight:: perl - - -**** -NAME -**** - - -pt-collect - Collect information from a server for some period of time. - - -******** -SYNOPSIS -******** - - -Usage: pt-collect -d -g -i -o -s [OPTIONS] [-- MYSQL-OPTIONS] - -pt-collect tool gathers a variety of information about a system for a period -of time. It is typically executed when the stalk tool detects a condition -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 -*********** - - -pt-collect creates a lock to ensure that only one instance runs at a time, -and then saves a variety of performance and status data into files in the -configured directory. Files are named with a timestamp so they can be -grouped together. The tool is MySQL-centric by default, and gathers quite -a bit of diagnostic data that's useful for understanding the behavior of -a MySQL database server. - -Options after \ ``--``\ are passed to \ ``mysql``\ and \ ``mysqladmin``\ . - - -******* -OPTIONS -******* - - - --d (required) - - DESTINATION Where to store the resulting data; must already exist. - - - --g (required) - - Collect GDB stack traces. - - - --i INTERVAL (required) - - How many seconds to collect data. - - - --o (required) - - Collect oprofile data; disables -s. - - - --s (required) - - Collect strace data. - - - --f PERCENT - - Exit if the disk is more than this percent full (default 100). - - - --m MEGABYTES - - Exit if there are less than this many megabytes free disk space (default 0). - - - --p PREFIX - - Store the data into files with this prefix (optional). - - - --t - - Collect tcpdump data. - - - - -*********** -ENVIRONMENT -*********** - - -This tool does not use any environment variables. - - -******************* -SYSTEM REQUIREMENTS -******************* - - -This tool requires Bash v3 or newer and assumes that these programs -are installed, in the PATH, and executable: sysctl, top, vmstat, iostat, -mpstat, lsof, mysql, mysqladmin, df, netstat, pidof, flock, and others -depending on what command-line options are specified. If some of those -programs are not available, the tool will still run but may print warnings. - - -**** -BUGS -**** - - -For a list of known bugs, see `http://www.percona.com/bugs/pt-collect `_. - -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-2011 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 -******* - - -pt-collect 1.0.1 - diff --git a/docs/user/pt-mext.rst b/docs/user/pt-mext.rst deleted file mode 100644 index bfc69bf9..00000000 --- a/docs/user/pt-mext.rst +++ /dev/null @@ -1,224 +0,0 @@ - -####### -pt-mext -####### - -.. highlight:: perl - - -**** -NAME -**** - - -pt-mext - Look at many samples of MySQL \ ``SHOW GLOBAL STATUS``\ side-by-side. - - -******** -SYNOPSIS -******** - - -Usage: pt-mext [OPTIONS] -- COMMAND - -pt-mext columnizes repeated output from a program like mysqladmin extended. - -Get output from \ ``mysqladmin``\ : - - -.. code-block:: perl - - pt-mext -r -- mysqladmin ext -i10 -c3" - - -Get output from a file: - - -.. code-block:: perl - - 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 -*********** - - -pt-mext executes the \ ``COMMAND``\ you specify, and reads through the result one -line at a time. It places each line into a temporary file. When it finds a -blank line, it assumes that a new sample of SHOW GLOBAL STATUS is starting, -and it creates a new temporary file. At the end of this process, it has a -number of temporary files. It joins the temporary files together side-by-side -and prints the result. If the "-r" option is given, it first subtracts -each sample from the one after it before printing results. - - -******* -OPTIONS -******* - - - --r - - Relative: subtract each column from the previous column. - - - - -*********** -ENVIRONMENT -*********** - - -This tool does not use any environment variables. - - -******************* -SYSTEM REQUIREMENTS -******************* - - -This tool requires the Bourne shell (\ */bin/sh*\ ) and the seq program. - - -**** -BUGS -**** - - -For a list of known bugs, see `http://www.percona.com/bugs/pt-mext `_. - -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 -******* - - -pt-mext 1.0.1 - diff --git a/docs/user/pt-mysql-summary.rst b/docs/user/pt-mysql-summary.rst deleted file mode 100644 index 4c0e8696..00000000 --- a/docs/user/pt-mysql-summary.rst +++ /dev/null @@ -1,233 +0,0 @@ - -################ -pt-mysql-summary -################ - -.. highlight:: perl - - -**** -NAME -**** - - -pt-mysql-summary - Summarize MySQL information in a nice way. - - -******** -SYNOPSIS -******** - - -Usage: pt-mysql-summary [MYSQL-OPTIONS] - -pt-mysql-summary conveniently summarizes the status and configuration of a -MySQL database server so that you can learn about it at a glance. It is not -a tuning tool or diagnosis tool. It produces a report that is easy to diff -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 -*********** - - -pt-mysql-summary works by connecting to a MySQL database server and querying -it for status and configuration information. It saves these bits of data -into files in /tmp, and then formats them neatly with awk and other scripting -languages. - -To use, simply execute it. Optionally add the same command-line options -you would use to connect to MySQL, like \ ``pt-mysql-summary --user=foo``\ . - -The tool interacts minimally with the server upon which it runs. It assumes -that you'll run it on the same server you're inspecting, and therefore it -assumes that it will be able to find the my.cnf configuration file, for -example. However, it should degrade gracefully if this is not the case. -Note, however, that its output does not indicate which information comes from -the MySQL database and which comes from the host operating system, so it is -possible for confusing output to be generated if you run the tool on one -server and direct it to connect to a MySQL database server running on another -server. - - -************** -Fuzzy-Rounding -************** - - -Many of the outputs from this tool are deliberately rounded to show their -magnitude but not the exact detail. This is called fuzzy-rounding. The idea -is that it doesn't matter whether a server is running 918 queries per second -or 921 queries per second; such a small variation is insignificant, and only -makes the output hard to compare to other servers. Fuzzy-rounding rounds in -larger increments as the input grows. It begins by rounding to the nearest 5, -then the nearest 10, nearest 25, and then repeats by a factor of 10 larger -(50, 100, 250), and so on, as the input grows. - - -******* -OPTIONS -******* - - -This tool does not have any command-line options of its own. All options -are passed to \ ``mysql``\ . - - -*********** -ENVIRONMENT -*********** - - -This tool does not use any environment variables. - - -******************* -SYSTEM REQUIREMENTS -******************* - - -This tool requires Bash v3 or newer. - - -**** -BUGS -**** - - -For a list of known bugs, see `http://www.percona.com/bugs/pt-mysql-summary `_. - -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-2011 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 -******* - - -pt-mysql-summary 1.0.1 - diff --git a/docs/user/pt-pmp.rst b/docs/user/pt-pmp.rst deleted file mode 100644 index 0f427d54..00000000 --- a/docs/user/pt-pmp.rst +++ /dev/null @@ -1,244 +0,0 @@ - -###### -pt-pmp -###### - -.. highlight:: perl - - -**** -NAME -**** - - -pt-pmp - Aggregate GDB stack traces for a selected program. - - -******** -SYNOPSIS -******** - - -Usage: pt-pmp [OPTIONS] [FILES] - -pt-pmp is a poor man's profiler, inspired by `http://poormansprofiler.org `_. -It can create and summarize full stack traces of processes on Linux. -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 -*********** - - -pt-pmp performs two tasks: it gets a stack trace, and it summarizes the stack -trace. If a file is given on the command line, the tool skips the first step -and just aggregates the file. - -To summarize the stack trace, the tool extracts the function name (symbol) -from each level of the stack, and combines them with commas. It does this -for each thread in the output. Afterwards, it sorts similar threads together -and counts how many of each one there are, then sorts them most-frequent first. - - -******* -OPTIONS -******* - - -Options must precede files on the command line. - - --b BINARY - - Which binary to trace (default mysqld) - - - --i ITERATIONS - - How many traces to gather and aggregate (default 1) - - - --k KEEPFILE - - Keep the raw traces in this file after aggregation - - - --l NUMBER - - Aggregate only first NUMBER functions; 0=infinity (default 0) - - - --p PID - - Process ID of the process to trace; overrides -b - - - --s SLEEPTIME - - Number of seconds to sleep between iterations (default 0) - - - - -*********** -ENVIRONMENT -*********** - - -This tool does not use any environment variables. - - -******************* -SYSTEM REQUIREMENTS -******************* - - -This tool requires Bash v3 or newer. - - -**** -BUGS -**** - - -For a list of known bugs, see `http://www.percona.com/bugs/pt-pmp `_. - -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, based on a script by Domas Mituzas (`http://poormansprofiler.org/ `_) - - -********************* -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-2011 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 -******* - - -pt-pmp 1.0.1 - diff --git a/docs/user/pt-sift.rst b/docs/user/pt-sift.rst deleted file mode 100644 index cc9bdf32..00000000 --- a/docs/user/pt-sift.rst +++ /dev/null @@ -1,273 +0,0 @@ - -####### -pt-sift -####### - -.. highlight:: perl - - -**** -NAME -**** - - -pt-sift - Browses files created by pt-collect. - - -******** -SYNOPSIS -******** - - -Usage: pt-sift FILE|PREFIX|DIRECTORY - -pt-sift browses the files created by pt-collect. If you specify a -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 -*********** - - -pt-sift downloads other tools that it might need, such as pt-diskstats, -and then makes a list of the unique timestamp prefixes of all the files in -the directory, as written by the pt-collect tool. If the user specified -a timestamp on the command line, then it begins with that sample of data; -otherwise it begins by showing a list of the timestamps and prompting for -a selection. Thereafter, it displays a summary of the selected sample, and -the user can navigate and inspect with keystrokes. The keystroke commands -you can use are as follows: - - -d - - Sets the action to start the pt-diskstats tool on the sample's disk - performance statistics. - - - -i - - Sets the action to view the first INNODB STATUS sample in less. - - - -m - - Displays the first 4 samples of SHOW STATUS counters side by side with the - pt-mext tool. - - - -n - - Summarizes the first sample of netstat data in two ways: by originating host, - and by connection state. - - - -j - - Select the next timestamp as the active sample. - - - -k - - Select the previous timestamp as the active sample. - - - -q - - Quit the program. - - - -1 - - Sets the action for each sample to the default, which is to view a summary - of the sample. - - - -0 - - Sets the action to just list the files in the sample. - - - -\* - - Sets the action to view all of the samples's files in the less program. - - - - -******* -OPTIONS -******* - - -This tool does not have any command-line options. - - -*********** -ENVIRONMENT -*********** - - -This tool does not use any environment variables. - - -******************* -SYSTEM REQUIREMENTS -******************* - - -This tool requires Bash v3 and the following programs: pt-diskstats, pt-pmp, -pt-mext, and align (from Aspersa). If these programs are not in your PATH, -they will be fetched from the Internet if curl is available. - - -**** -BUGS -**** - - -For a list of known bugs, see `http://www.percona.com/bugs/pt-sift `_. - -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-2011 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 -******* - - -pt-sift 1.0.1 - diff --git a/docs/user/pt-stalk.rst b/docs/user/pt-stalk.rst deleted file mode 100644 index 3d32b0cd..00000000 --- a/docs/user/pt-stalk.rst +++ /dev/null @@ -1,367 +0,0 @@ - -######## -pt-stalk -######## - -.. highlight:: perl - - -**** -NAME -**** - - -pt-stalk - Wait for a condition to occur then begin collecting data. - - -******** -SYNOPSIS -******** - - -Usage: pt-stalk - -pt-stalk watches for a condition to become true, and when it does, executes -a script. By default it executes pt-collect, but that can be customized. -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 -*********** - - -Although pt-stalk comes pre-configured to do a specific thing, in general -this tool is just a skeleton script for the following flow of actions: - - -1. - - Loop infinitely, sleeping between iterations. - - - -2. - - In each iteration, run some command and get the output. - - - -3. - - If the command fails or the output is larger than the threshold, - execute the collection script; but do not execute if the destination disk - is too full. - - - -By default, the tool is configured to execute mysqladmin extended-status and -extract the value of the Threads_connected variable; if this is greater than -100, it runs the collection script. This is really just placeholder code, -and almost certainly needs to be customized! - -If the tool does execute the collection script, it will wait for a while -before checking and executing again. This is to prevent a continuous -condition from causing a huge number of executions to fire off. - -The name 'stalk' is because 'watch' is already taken, and 'stalk' is fun. - - -*********** -CONFIGURING -*********** - - -If the file \ *pt-stalk.conf*\ exists in the current working directory, then -"ENVIRONMENT" variables are imported from it. For example, the config -file has the format: - - -.. code-block:: perl - - INTERVAL=10 - GDB=yes - - -See "ENVIRONMENT". - - -******* -OPTIONS -******* - - -This tool does not have any command-line options, but see -"ENVIRONMENT" and "CONFIGURING". - - -*********** -ENVIRONMENT -*********** - - -The following environment variables configure how, what, and when the tool -runs. They are all optional and can be specified either on the command line -or in the \ *pt-stalk.conf*\ config file (see "CONFIGURING"). - - -THRESHOLD (default 100) - - This is the max number of we want to tolerate. - - - -VARIABLE (default Threads_connected} - - This is the thing to check for. - - - -CYCLES (default 1) - - How many times must the condition be met before the script will fire? - - - -GDB (default no) - - Collect GDB stacktraces? - - - -OPROFILE (default yes) - - Collect oprofile data? - - - -STRACE (default no) - - Collect strace data? - - - -TCPDUMP (default yes) - - Collect tcpdump data? - - - -EMAIL - - Send mail to this list of addresses when the script triggers. - - - -MYSQLOPTIONS - - Any options to pass to mysql/mysqladmin, such as -u, -p, etc - - - -INTERVAL (default 30) - - This is the interval between checks. - - - -MAYBE_EMPTY (default no) - - If the command you're running to detect the condition is allowed to return - nothing (e.g. a grep line that might not even exist if there's no problem), - then set this to "yes". - - - -COLLECT (default ${HOME}/bin/pt-collect) - - This is the location of the 'collect' script. - - - -DEST (default ${HOME}/collected/) - - This is where to store the collected data. - - - -DURATION (default 30) - - How long to collect statistics data for? Make sure that this isn't longer - than SLEEP. - - - -SLEEP (default DURATION \* 10) - - How long to sleep after collecting? - - - -PCT_THRESHOLD (default 95) - - Bail out if the disk is more than this %full. - - - -MB_THRESHOLD (default 100) - - Bail out if the disk has less than this many MB free. - - - -PURGE (default 30) - - Remove samples after this many days. - - - - -******************* -SYSTEM REQUIREMENTS -******************* - - -This tool requires Bash v3 or newer. - - -**** -BUGS -**** - - -For a list of known bugs, see `http://www.percona.com/bugs/pt-stalk `_. - -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, Justin Swanhart, and Fernando Ipar - - -********************* -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-2011 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 -******* - - -pt-stalk 1.0.1 - diff --git a/docs/user/pt-summary.rst b/docs/user/pt-summary.rst deleted file mode 100644 index 1f432587..00000000 --- a/docs/user/pt-summary.rst +++ /dev/null @@ -1,230 +0,0 @@ - -########## -pt-summary -########## - -.. highlight:: perl - - -**** -NAME -**** - - -pt-summary - Summarize system information in a nice way. - - -******** -SYNOPSIS -******** - - -Usage: pt-summary - -pt-summary conveniently summarizes the status and configuration of a server. -It is not a tuning tool or diagnosis tool. It produces a report that is easy -to diff and can be pasted into emails without losing the formatting. This -tool works well on Linux systems. - -Download and run: - - -.. code-block:: perl - - wget http://percona.com/get/pt-summary - bash ./pt-summary - - -Download and run in a single step: - - -.. code-block:: perl - - 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 -*********** - - -pt-summary runs a large variety of commands to inspect system status and -configuration, saves the output into files in /tmp, and then runs Unix -commands on these results to format them nicely. It works best when -executed as a privileged user, but will also work without privileges, -although some output might not be possible to generate without root. - - -******* -OPTIONS -******* - - -This tool does not have any command-line options. - - -*********** -ENVIRONMENT -*********** - - -The PT_SUMMARY_SKIP environment variable specifies a comma-separated list -of things to skip: - - -.. code-block:: perl - - MOUNT: Don't print out mounted filesystems and disk fullness. - NETWORK: Don't print out information on network controllers & config. - PROCESS: Don't print out top processes and vmstat information. - - - -******************* -SYSTEM REQUIREMENTS -******************* - - -This tool requires the Bourne shell (\ */bin/sh*\ ). - - -**** -BUGS -**** - - -For a list of known bugs, see `http://www.percona.com/bugs/pt-summary `_. - -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 and Kevin van Zonneveld (http://kevin.vanzonneveld.net) - - -********************* -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-2011 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 -******* - - -pt-summary 1.0.1 - diff --git a/docs/user/pt-trend.rst b/docs/user/pt-trend.rst deleted file mode 100644 index acdc9803..00000000 --- a/docs/user/pt-trend.rst +++ /dev/null @@ -1,258 +0,0 @@ - -######## -pt-trend -######## - -.. highlight:: perl - - -**** -NAME -**** - - -pt-trend - Compute statistics over a set of time-series data points. - - -******** -SYNOPSIS -******** - - -Usage: pt-trend [OPTION...] [FILE ...] - -pt-trend reads a slow query log and outputs statistics on it. - - -***** -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-trend simply reads files give on the command-line. 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-trend `_. - -See also "BUGS" for more information on filing bugs and getting help. - - -*********** -DESCRIPTION -*********** - - -You can specify multiple files on the command line. If you don't specify any, -or if you use the special filename \ ``-``\ , lines are read from standard input. - - -******* -OPTIONS -******* - - -This tool accepts additional command-line arguments. Refer to the -"SYNOPSIS" and usage information for details. - - ---config - - type: Array - - Read this comma-separated list of config files; if specified, this must be the - first option on the command line. - - - ---help - - Show help and exit. - - - ---pid - - type: string - - Create the given PID file. The file contains the process ID of the script. - The PID file is removed when the script exits. Before starting, the script - checks if the PID file already exists. If it does not, then the script creates - and writes its own PID to it. If it does, then the script checks the following: - if the file contains a PID and a process is running with that PID, then - the script dies; or, if there is no process running with that PID, then the - script overwrites the file with its own PID and starts; else, if the file - contains no PID, then the script dies. - - - ---progress - - type: array; default: time,15 - - Print progress reports to STDERR. The value is a comma-separated list with two - parts. The first part can be percentage, time, or iterations; the second part - specifies how often an update should be printed, in percentage, seconds, or - number of iterations. - - - ---version - - Show version and exit. - - - - -*********** -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-trend ... > FILE 2>&1 - - -Be careful: debugging output is voluminous and can generate several megabytes -of output. - - -******************* -SYSTEM REQUIREMENTS -******************* - - -You need Perl, DBI, DBD::mysql, and some core packages that ought to be -installed in any reasonably new version of Perl. - - -**** -BUGS -**** - - -For a list of known bugs, see `http://www.percona.com/bugs/pt-trend `_. - -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-2011 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 -******* - - -pt-trend 1.0.1 - diff --git a/docs/user/source/_static/percona-xtrabackup-logo.jpg b/docs/user/source/_static/percona-xtrabackup-logo.jpg new file mode 100644 index 00000000..6c9f9d66 Binary files /dev/null and b/docs/user/source/_static/percona-xtrabackup-logo.jpg differ diff --git a/docs/user/source/_static/percona_favicon.ico b/docs/user/source/_static/percona_favicon.ico new file mode 100644 index 00000000..f426064d Binary files /dev/null and b/docs/user/source/_static/percona_favicon.ico differ diff --git a/docs/user/authors.rst b/docs/user/source/authors.rst similarity index 100% rename from docs/user/authors.rst rename to docs/user/source/authors.rst diff --git a/docs/user/bugs.rst b/docs/user/source/bugs.rst similarity index 54% rename from docs/user/bugs.rst rename to docs/user/source/bugs.rst index 6fca5644..dd820507 100644 --- a/docs/user/bugs.rst +++ b/docs/user/source/bugs.rst @@ -1,20 +1,21 @@ +.. _bugs: -**** -BUGS -**** +====== + 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 + * Complete command-line used to run the tool -\* Tool \ ``--version``\ + * Tool ``--version`` -\* MySQL version of all servers involved + * |MySQL| version of all servers involved -\* Output from the tool including STDERR + * Output from the tool including STDERR -\* Input files (log/dump/config files, etc.) + * 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/source/conf.py b/docs/user/source/conf.py new file mode 100644 index 00000000..504897c0 --- /dev/null +++ b/docs/user/source/conf.py @@ -0,0 +1,253 @@ +# -*- coding: utf-8 -*- +# +# Percona XtraBackup documentation build configuration file, created by +# sphinx-quickstart on Mon Jun 27 22:27:15 2011. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ----------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.viewcode', 'sphinx.ext.ifconfig'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'Percona Toolkit' +copyright = u'2011, Percona Inc' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '1.0' +# The full version, including alpha/beta/rc tags. +release = '1' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = [] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + + +rst_prolog = ''' +.. |check| replace:: ``|[[---CHECK---]]|`` + +.. |xtrabackup| replace:: :program:`xtrabackup` + +.. |innobackupex| replace:: :program:`innobackupex` + +.. |XtraDB| replace:: :term:`XtraDB` + +.. |InnoDB| replace:: :term:`InnoDB` + +.. |MyISAM| replace:: :term:`MyISAM` + +.. |LSN| replace:: :term:`LSN` + +.. |XtraBackup| replace:: *XtraBackup* + +.. |Percona Server| replace:: *Percona Server* + +.. |Percona Toolkit| replace:: *Percona Toolkit* + +.. |Percona| replace:: *Percona* + +.. |MySQL| replace:: *MySQL* + +.. |Drizzle| replace:: *Drizzle* + +.. |MariaDB| replace:: *MariaDB* + +.. |tar4ibd| replace:: :program:`tar4ibd` + +.. |tar| replace:: :program:`tar` + +''' + + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'percona-theme' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +html_theme_path = ['.', './percona-theme'] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +html_title = 'Percona Toolkit Documentation' + +# A shorter title for the navigation bar. Default is the same as html_title. +html_short_title = 'Percona Toolkit' + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +html_logo = '' + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +html_favicon = 'percona_favicon.ico' + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'PerconaToolkitDoc' + + +# -- Options for LaTeX output -------------------------------------------------- + +# The paper size ('letter' or 'a4'). +#latex_paper_size = 'letter' + +# The font size ('10pt', '11pt' or '12pt'). +#latex_font_size = '10pt' + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'PerconaToolkit.tex', u'Percona Toolkit Documentation', + u'Percona Inc', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Additional stuff for the LaTeX preamble. +#latex_preamble = '' + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output -------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'perconatoolkit', u'Percona Toolkit Documentation', + [u'Percona Inc'], 1) +] diff --git a/docs/user/configuration_files.rst b/docs/user/source/configuration_files.rst similarity index 100% rename from docs/user/configuration_files.rst rename to docs/user/source/configuration_files.rst diff --git a/docs/user/copyright_license_and_warranty.rst b/docs/user/source/copyright_license_and_warranty.rst similarity index 100% rename from docs/user/copyright_license_and_warranty.rst rename to docs/user/source/copyright_license_and_warranty.rst diff --git a/docs/user/environment.rst b/docs/user/source/environment.rst similarity index 100% rename from docs/user/environment.rst rename to docs/user/source/environment.rst diff --git a/docs/user/source/glossary.rst b/docs/user/source/glossary.rst new file mode 100644 index 00000000..1d0b0589 --- /dev/null +++ b/docs/user/source/glossary.rst @@ -0,0 +1,31 @@ +========== + Glossary +========== + +.. glossary:: + + lsn + -- + + LSN + -- + + InnoDB + Storage engine which provides ACID-compilant transactions and foreing key support, among others improvements over :term:`MyISAM`. It is the default engine for |MySQL| as of the 5.5 series. + + MyISAM + Previous default storage engine for |MySQL| for versions prior to 5.5. It doesn't fully support transactions but in some scenarios may be faster than :term:`InnoDB`. + + XtraDB + *Percona XtraDB* is an enhanced version of the InnoDB storage engine, designed to better scale on modern hardware, and including a variety of other features useful in high performance environments. It is fully backwards compatible, and so can be used as a drop-in replacement for standard InnoDB. More information `here `_ . + + my.cnf + This file refers to the database server's main configuration file. Most linux distributions place it as :file:`/etc/mysql/my.cnf`, but the location and name depends on the particular installation. Note that this is not the only way of configuring the server, some systems does not have one even and rely on the command options to start the server and its defaults values. + + datadir + The directory in which the database server stores its databases. Most Linux distribution use :file:`/var/lib/mysql` by default. + + ibdata + Default prefix for tablespace files, e.g. :file:`ibdata1` is a 10MB autoextensible file that |MySQL| creates for the shared tablespace by default. + + diff --git a/docs/user/index.rst b/docs/user/source/index.rst similarity index 73% rename from docs/user/index.rst rename to docs/user/source/index.rst index 77788587..ca34bc70 100644 --- a/docs/user/index.rst +++ b/docs/user/source/index.rst @@ -1,7 +1,7 @@ -***************************** -Percona Toolkit Documentation -***************************** +=============================== + Percona Toolkit Documentation +=============================== Percona Toolkit is a collection of advanced command-line tools used by Percona (`http://www.percona.com/ `_) support staff to perform a variety of @@ -17,13 +17,41 @@ 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 +Getting Percona Toolkit +======================= + +.. toctree:: + :maxdepth: 1 + :glob: + + installation + +Tools +===== + +.. toctree:: + :maxdepth: 1 + :glob: + + pt-* + +Configuration +============= + +.. toctree:: + :maxdepth: 1 - tools configuration_files environment system_requirements + glossary + +Miscellaneous +============= + +.. toctree:: + :maxdepth: 2 + bugs authors copyright_license_and_warranty diff --git a/docs/user/source/installation.rst b/docs/user/source/installation.rst new file mode 100644 index 00000000..36091979 --- /dev/null +++ b/docs/user/source/installation.rst @@ -0,0 +1,25 @@ +======================================= + Installation +======================================= + +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. + diff --git a/docs/user/source/percona-theme/layout.html b/docs/user/source/percona-theme/layout.html new file mode 100644 index 00000000..31a64147 --- /dev/null +++ b/docs/user/source/percona-theme/layout.html @@ -0,0 +1,312 @@ +{# + basic/layout.html + ~~~~~~~~~~~~~~~~~ + + Master layout template for Sphinx themes. + + :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +#} +{%- block doctype -%} + +{%- endblock %} +{%- set reldelim1 = reldelim1 is not defined and ' »' or reldelim1 %} +{%- set reldelim2 = reldelim2 is not defined and ' |' or reldelim2 %} +{%- set render_sidebar = (not embedded) and (not theme_nosidebar|tobool) and + (sidebars != []) %} +{%- set url_root = pathto('', 1) %} +{# XXX necessary? #} +{%- if url_root == '#' %}{% set url_root = '' %}{% endif %} +{%- if not embedded and docstitle %} + {%- set titlesuffix = " — "|safe + docstitle|e %} +{%- else %} + {%- set titlesuffix = "" %} +{%- endif %} + +{%- macro relbar() %} +
+

{{ _('Navigation') }}

+
    + {%- for rellink in rellinks %} +
  • + {{ rellink[3] }} + {%- if not loop.first %}{{ reldelim2 }}{% endif %}
    • + {%- endfor %} + {%- block rootrellink %} +
  • {{ shorttitle|e }}{{ reldelim1 }}
    • + {%- endblock %} + {%- for parent in parents %} +
  • {{ parent.title }}{{ reldelim1 }}
    • + {%- endfor %} + {%- block relbaritems %} {% endblock %} +
+
+{%- endmacro %} + +{%- macro sidebar() %} + {%- if render_sidebar %} +
+
+ {%- block sidebarlogo %} + {%- if logo %} + + {%- endif %} + +
+ +
+
Call Us
+
+
+ +1-888-316-9775 (USA - Sales)
+ +1-208-473-2904 (USA - Sales) +
+
+ +44-208-133-0309 (UK - Sales) +
+
+ +1-888-488-8556 (Emergency) +
+
+
+ +
+ +
+
+
+ + {%- endblock %} + {%- if sidebars != None %} + {#- new style sidebar: explicitly include/exclude templates #} + {%- for sidebartemplate in sidebars %} + {%- include sidebartemplate %} + {%- endfor %} + {%- else %} + {#- old style sidebars: using blocks -- should be deprecated #} + {%- block sidebartoc %} + {%- include "localtoc.html" %} + {%- endblock %} + {%- block sidebarrel %} + {%- include "relations.html" %} + {%- endblock %} + {%- block sidebarsourcelink %} + {%- include "sourcelink.html" %} + {%- endblock %} + {%- if customsidebar %} + {%- include customsidebar %} + {%- endif %} + {%- block sidebarsearch %} + {%- include "searchbox.html" %} + {%- endblock %} + {%- endif %} + +
+
+ {%- endif %} +{%- endmacro %} + +{%- macro script() %} + + {%- for scriptfile in script_files %} + + {%- endfor %} +{%- endmacro %} + +{%- macro css() %} + + + + {%- for cssfile in css_files %} + + {%- endfor %} +{%- endmacro %} + + + + + {{ metatags }} + {%- block htmltitle %} + {{ title|striptags|e }}{{ titlesuffix }} + {%- endblock %} + + {{ css() }} + {%- if not embedded %} + {{ script() }} + {%- if use_opensearch %} + + {%- endif %} + + + + + + {%- if favicon %} + + {%- endif %} + {%- endif %} +{%- block linktags %} + {%- if hasdoc('about') %} + + {%- endif %} + {%- if hasdoc('genindex') %} + + {%- endif %} + {%- if hasdoc('search') %} + + {%- endif %} + {%- if hasdoc('copyright') %} + + {%- endif %} + + {%- if parents %} + + {%- endif %} + {%- if next %} + + {%- endif %} + {%- if prev %} + + {%- endif %} +{%- endblock %} +{%- block extrahead %} {% endblock %} + + + + + +{%- block header %}{% endblock %} + +
+ +{%- block content %} + + + + {%- block sidebar1 %} {# possible location for sidebar #} {% endblock %} + +
+ + + + {%- block document %} +
+ {%- if render_sidebar %} +
+ {%- endif %} + + {%- block relbar1 %}{{ relbar() }}{% endblock %} + +
+ {% block body %} {% endblock %} +
+ + {%- block relbar2 %}{{ relbar() }} + + {%- if render_sidebar %} +
+ {%- endif %} + + + +
+ + {%- endblock %} + + {%- block sidebar2 %}{{ sidebar() }}{% endblock %} + +
+ + {%- if last_updated %} + {% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %} + {%- endif %} + +
+ + {%- if show_copyright %} + {%- if hasdoc('copyright') %} + {% trans path=pathto('copyright'), copyright=copyright|e %}© Copyright {{ copyright }}.{% endtrans %} + {%- else %} + {% trans copyright=copyright|e %}© Copyright {{ copyright }}.{% endtrans %} + {%- endif %} + {%- endif %} + +
+ Except where otherwise noted, this documentation is licensed under the following license: +
+ + CC Attribution-ShareAlike 2.0 Generic
+ + {%- if show_sphinx %} + {% trans sphinx_version=sphinx_version|e %}Created using Sphinx {{ sphinx_version }}.{% endtrans %} + {%- endif %} + +
+ +
+ {%- endblock %} + + {% endblock %} + +{%- block footer %} + +
+ This documentation is developed in Launchpad as part of the XtraBackup source code.
+If you spotted innacuracies, errors, don't understood it or you think something is missing or should be improved, please file a bug. +
+ +
+ +
+ + +
+ ]]> + Call us: 1-888-316-9775 • Contact Us
+ MySQL and InnoDB are trademarks of Oracle Corp.
+ Proudly running Percona Server
+ Copyright © 2006-2011 Percona Inc.
+ Copyright, Trademark, and Privacy Policy • Sitemap + ]]> +
+
+ +
+{%- endblock %} + + + + + +{% if theme_collapsiblesidebar|tobool %} +{% set script_files = script_files + ['_static/sidebar.js'] %} +{% endif %} diff --git a/docs/user/source/percona-theme/searchbox.html b/docs/user/source/percona-theme/searchbox.html new file mode 100644 index 00000000..243e310b --- /dev/null +++ b/docs/user/source/percona-theme/searchbox.html @@ -0,0 +1,22 @@ +{# + basic/searchbox.html + ~~~~~~~~~~~~~~~~~~~~ + + Sphinx sidebar template: quick search box. + + :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +#} +{%- if pagename != "search" %} + + +{%- endif %} diff --git a/docs/user/source/percona-theme/static/default.css_t b/docs/user/source/percona-theme/static/default.css_t new file mode 100644 index 00000000..76568b9c --- /dev/null +++ b/docs/user/source/percona-theme/static/default.css_t @@ -0,0 +1,469 @@ +/* + * default.css_t + * ~~~~~~~~~~~~~ + * + * Sphinx stylesheet -- default theme. + * + * :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +@import url("basic.css"); + +/* -- page layout ----------------------------------------------------------- */ + +body { + font-family: Arial,Helvetica,sans-serif; + font-size: 14px; + background-color: #fff; + color: #333333; + line-height: 20px; + margin: 0; + padding: 0; + +} + +div.document { + background-color: #fff; + margin: 0 auto; + overflow: hidden; + padding: 30px 0; + width: 960px; +} + +div.documentwrapper { + /* float: left; */ + /* width: 100%; */ + +} + +div.bodywrapper { + margin: 10 0 0 0px; + width: 660px; + float:right; +} + +div.body { + background-color: #fff; + color: #333333; + padding: 0 0 20px; +} + +{%- if theme_rightsidebar|tobool %} +div.bodywrapper { + margin: 0 {{ theme_sidebarwidth }}px 0 0; +} +{%- endif %} + +div.footer { + /* color: {{ theme_footertextcolor }}; */ + /* width: 100%; */ + /* padding: 9px 0 9px 0; */ + /* text-align: center; */ + /* font-size: 75%; */ + font: 80% "Lucida Grande",Verdana,Lucida,Helvetica,Arial,sans-serif; + background: none repeat scroll 0 0 #333333; + border-top: 2px solid #D95200; + overflow: hidden; +} + +div.footer a { + color: {{ theme_footertextcolor }}; + text-decoration: underline; +} + +div.related { + background-color: #ccc; + line-height: 30px; + color: #333; + background: none repeat scroll 0 0 #F8F8F8; + border: 1px solid #E0E0E0; + clear: both; + padding: 10px; + width: 635px; + margin-bottom: 5px; +} + +div.related a { + color: #999; +} + +div.sphinxsidebar { + margin-left: 0px; + margin-right: 30px; + color: #eee; + font-family: Arial,Helvetica,sans-serif; + width: 260px; + {%- if theme_stickysidebar|tobool %} + top: 30px; + bottom: 0; + margin: 0; + position: fixed; + overflow: auto; + height: auto; + {%- endif %} + {%- if theme_rightsidebar|tobool %} + float: right; + {%- if theme_stickysidebar|tobool %} + right: 0; + {%- endif %} + {%- endif %} +} + +{%- if theme_stickysidebar|tobool %} +/* this is nice, but it it leads to hidden headings when jumping + to an anchor */ +/* +div.related { + position: fixed; +} + +div.documentwrapper { + margin-top: 30px; +} +*/ +{%- endif %} + +div.sphinxsidebar h3 { + /* font-family: {{ theme_headfont }}; */ + color: #999; + font-size: 18px; + line-height: 15px; + font-weight: 400; + margin-left: 5px; + padding: 0; +} + +div.sphinxsidebar h3 a { + color: #333; +} + +div.sphinxsidebar a:hover { + /* color: #333; */ +} + +div.sphinxsidebar h4 { + /* font-family: {{ theme_headfont }}; */ + color: #666; + font-size: 18px; + font-weight: normal; + margin: 5px 0 0 5px; + padding: 0; +} + +div.sphinxsidebar p { + color: #333; + margin-bottom: 5px; + margin-left: 5px; +} + +div.sphinxsidebar p.topless { + margin: 5px 10px 10px 10px; +} + +div.sphinxsidebar ul { + margin: 10px; + padding-left: 5px; + color: #333; +} + +div.sphinxsidebar a { + color: #D12907; +} + +div.sphinxsidebar input { + border: 1px solid #999; + font-family: sans-serif; + font-size: 1em; +} + +{% if theme_collapsiblesidebar|tobool %} +/* for collapsible sidebar */ +div#sidebarbutton { + background-color: {{ theme_sidebarbtncolor }}; +} +{% endif %} + +/* -- hyperlink styles ------------------------------------------------------ */ + +a { + color: #D12907; + text-decoration: underline; + border: medium none; + cursor: pointer; +} + +a:visited { + color: #D12907; + text-decoration: underline; +} + +a:hover { + color: #D12907; + text-decoration: underline; +} + +{% if theme_externalrefs|tobool %} +a.external { + text-decoration: none; + border-bottom: 1px dashed {{ theme_linkcolor }}; +} + +a.external:hover { + text-decoration: none; + border-bottom: none; +} + +a.external:visited { + text-decoration: none; + border-bottom: 1px dashed {{ theme_visitedlinkcolor }}; +} +{% endif %} + +/* -- body styles ----------------------------------------------------------- */ + +div.body h1, +div.body h2, +div.body h3, +div.body h4, +div.body h5, +div.body h6 { + font-family: Arial,Helvetica,sans-serif; + background-color: #fff; + font-weight: 400; + + /* border-bottom: 1px solid #ccc; */ + /* margin: 20px -20px 10px -20px; */ + /* padding: 0; */ + /* padding: 3px 0 3px 10px; */ + text-decoration: none !important; + + border-bottom: 1px solid #E0E0E0; + font-size: 20px; + line-height: 20px; + margin: 30px 0 15px; + padding: 0 0 3px; + color: #000; +} + +div.body h1 { + font-size: 32px; + color: #D12907; + line-height: 40px; + margin: 10px 0 20px 0; + text-decoration: none !important; + border-bottom: none; + margin-top: 35px; +} + +div.body h2 { font-size: 150%; } +div.body h3 { font-size: 140%; } +div.body h4 { font-size: 120%; } +div.body h5 { font-size: 110%; } +div.body h6 { font-size: 100%; } + +a.headerlink { + color: {{ theme_headlinkcolor }}; + font-size: 0.8em; + padding: 0 4px 0 4px; + text-decoration: none; +} + +a.headerlink:hover { + background-color: {{ theme_headlinkcolor }}; + color: white; +} + +div.body dd, div.body li { + text-align: justify; +} + +div.body dt { + list-style-type: square; + /* margin: 8px 0 8px 30px; */ + padding: 0 4px 0 5px; + +} + +div.body p { + text-align: justify; +/* line-height: 130%;*/ + margin: 10px 0; +} + +/* div.body ul, */ +div.body li { + list-style-type: square; + margin: 8px 0 8px 30px; + padding: 0 4px 0 5px; +} + +.reference em { + font-style: normal; +} + +.std-term { + font-style: normal; + font-weight: 400; + color: #FF7400 +} + +div.admonition p.admonition-title + p { + display: inline; +} + +div.admonition p { + margin-bottom: 5px; +} + +div.admonition pre { + margin-bottom: 5px; +} + +div.admonition ul, div.admonition ol { + margin-bottom: 5px; +} + +div.note { + background-color: #eee; + border: 1px solid #ccc; +} + +div.seealso { + background-color: #ffc; + border: 1px solid #ff6; +} + +div.topic { + background-color: #eee; +} + +div.warning { + background-color: #ffe4e4; + border: 1px solid #f66; +} + +p.admonition-title { + display: inline; +} + +p.admonition-title:after { + content: ":"; +} + +pre { + padding: 10px; + background-color: #F0E6D9/* {{ theme_codebgcolor }} */; + color: {{ theme_codetextcolor }}; + line-height: 120%; + border: 1px dashed #ED9821; + font-size: 80%; + overflow: auto; + /* border-left: none; */ + /* border-right: none; */ +} + +tt { +/* background-color: #ecf0f3; + padding: 0 1px 0 1px; + font-size: 0.95em;*/ + font-weight: 400; +} + +div.body td { + text-align: none; +} + +table.docutils th { + background-color: #DEE7EC; + border: 1px solid #8CACBB; + padding: 3px; + text-align: center; + font-style: normal; + font-weight: 400; +} + +table.docutils td { + border: 1px solid #8CACBB; + padding: 3px; + line-height: 16px; + vertical-align: middle; +} + +.warning tt { + background: #efc2c2; +} + +.note tt { + background: #d6d6d6; +} + +.viewcode-back { + font-family: {{ theme_bodyfont }}; +} + +div.viewcode-block:target { + background-color: #f4debf; + border-top: 1px solid #ac9; + border-bottom: 1px solid #ac9; +} + +.file-bugs { + background: none repeat scroll 0 0 #E8E8E8; + border: 1px solid #E0E0E0; + clear: both; + color: #333333; + padding: 10px; + text-align: center; + font-size: 90%; +} + +div.footer .footer { + margin: 0 auto; + overflow: hidden; + padding: 10px 0; + width: 960px; + border-top: none; +} + +div.footer .footer .logo { + float: left; + overflow: hidden; + padding: 17px 0 0; +} + +div.footer .footer .text { + color: #E0E0E0; + float: right; + font-family: Arial,Helvetica,sans-serif; + font-size: 11px; + line-height: 15px; + overflow: hidden; + text-align: right; +} + +div.license { + font-size: 80%; + /* padding: 0.5em; */ + text-align: center; + margin: 13px 0 -15px; +} + +#sidenavi.noborder { + border-right: medium none; + border-top: medium none; + margin: 0; +} + +#sidenavi { + color: #333333; + /* float: left; */ + font-family: Arial,Helvetica,sans-serif; + font-size: 18px; + line-height: 25px; + overflow: hidden; + padding: 10px 0 8px 0px; + width: 255px; +} + diff --git a/docs/user/source/percona-theme/static/email-small.png b/docs/user/source/percona-theme/static/email-small.png new file mode 100644 index 00000000..30d7f75a Binary files /dev/null and b/docs/user/source/percona-theme/static/email-small.png differ diff --git a/docs/user/source/percona-theme/static/jquery.min.js b/docs/user/source/percona-theme/static/jquery.min.js new file mode 100644 index 00000000..7c243080 --- /dev/null +++ b/docs/user/source/percona-theme/static/jquery.min.js @@ -0,0 +1,154 @@ +/*! + * jQuery JavaScript Library v1.4.2 + * http://jquery.com/ + * + * Copyright 2010, John Resig + * Dual licensed under the MIT or GPL Version 2 licenses. + * http://jquery.org/license + * + * Includes Sizzle.js + * http://sizzlejs.com/ + * Copyright 2010, The Dojo Foundation + * Released under the MIT, BSD, and GPL Licenses. + * + * Date: Sat Feb 13 22:33:48 2010 -0500 + */ +(function(A,w){function ma(){if(!c.isReady){try{s.documentElement.doScroll("left")}catch(a){setTimeout(ma,1);return}c.ready()}}function Qa(a,b){b.src?c.ajax({url:b.src,async:false,dataType:"script"}):c.globalEval(b.text||b.textContent||b.innerHTML||"");b.parentNode&&b.parentNode.removeChild(b)}function X(a,b,d,f,e,j){var i=a.length;if(typeof b==="object"){for(var o in b)X(a,o,b[o],f,e,d);return a}if(d!==w){f=!j&&f&&c.isFunction(d);for(o=0;o)[^>]*$|^#([\w-]+)$/,Ua=/^.[^:#\[\.,]*$/,Va=/\S/, +Wa=/^(\s|\u00A0)+|(\s|\u00A0)+$/g,Xa=/^<(\w+)\s*\/?>(?:<\/\1>)?$/,P=navigator.userAgent,xa=false,Q=[],L,$=Object.prototype.toString,aa=Object.prototype.hasOwnProperty,ba=Array.prototype.push,R=Array.prototype.slice,ya=Array.prototype.indexOf;c.fn=c.prototype={init:function(a,b){var d,f;if(!a)return this;if(a.nodeType){this.context=this[0]=a;this.length=1;return this}if(a==="body"&&!b){this.context=s;this[0]=s.body;this.selector="body";this.length=1;return this}if(typeof a==="string")if((d=Ta.exec(a))&& +(d[1]||!b))if(d[1]){f=b?b.ownerDocument||b:s;if(a=Xa.exec(a))if(c.isPlainObject(b)){a=[s.createElement(a[1])];c.fn.attr.call(a,b,true)}else a=[f.createElement(a[1])];else{a=sa([d[1]],[f]);a=(a.cacheable?a.fragment.cloneNode(true):a.fragment).childNodes}return c.merge(this,a)}else{if(b=s.getElementById(d[2])){if(b.id!==d[2])return T.find(a);this.length=1;this[0]=b}this.context=s;this.selector=a;return this}else if(!b&&/^\w+$/.test(a)){this.selector=a;this.context=s;a=s.getElementsByTagName(a);return c.merge(this, +a)}else return!b||b.jquery?(b||T).find(a):c(b).find(a);else if(c.isFunction(a))return T.ready(a);if(a.selector!==w){this.selector=a.selector;this.context=a.context}return c.makeArray(a,this)},selector:"",jquery:"1.4.2",length:0,size:function(){return this.length},toArray:function(){return R.call(this,0)},get:function(a){return a==null?this.toArray():a<0?this.slice(a)[0]:this[a]},pushStack:function(a,b,d){var f=c();c.isArray(a)?ba.apply(f,a):c.merge(f,a);f.prevObject=this;f.context=this.context;if(b=== +"find")f.selector=this.selector+(this.selector?" ":"")+d;else if(b)f.selector=this.selector+"."+b+"("+d+")";return f},each:function(a,b){return c.each(this,a,b)},ready:function(a){c.bindReady();if(c.isReady)a.call(s,c);else Q&&Q.push(a);return this},eq:function(a){return a===-1?this.slice(a):this.slice(a,+a+1)},first:function(){return this.eq(0)},last:function(){return this.eq(-1)},slice:function(){return this.pushStack(R.apply(this,arguments),"slice",R.call(arguments).join(","))},map:function(a){return this.pushStack(c.map(this, +function(b,d){return a.call(b,d,b)}))},end:function(){return this.prevObject||c(null)},push:ba,sort:[].sort,splice:[].splice};c.fn.init.prototype=c.fn;c.extend=c.fn.extend=function(){var a=arguments[0]||{},b=1,d=arguments.length,f=false,e,j,i,o;if(typeof a==="boolean"){f=a;a=arguments[1]||{};b=2}if(typeof a!=="object"&&!c.isFunction(a))a={};if(d===b){a=this;--b}for(;b
a"; +var e=d.getElementsByTagName("*"),j=d.getElementsByTagName("a")[0];if(!(!e||!e.length||!j)){c.support={leadingWhitespace:d.firstChild.nodeType===3,tbody:!d.getElementsByTagName("tbody").length,htmlSerialize:!!d.getElementsByTagName("link").length,style:/red/.test(j.getAttribute("style")),hrefNormalized:j.getAttribute("href")==="/a",opacity:/^0.55$/.test(j.style.opacity),cssFloat:!!j.style.cssFloat,checkOn:d.getElementsByTagName("input")[0].value==="on",optSelected:s.createElement("select").appendChild(s.createElement("option")).selected, +parentNode:d.removeChild(d.appendChild(s.createElement("div"))).parentNode===null,deleteExpando:true,checkClone:false,scriptEval:false,noCloneEvent:true,boxModel:null};b.type="text/javascript";try{b.appendChild(s.createTextNode("window."+f+"=1;"))}catch(i){}a.insertBefore(b,a.firstChild);if(A[f]){c.support.scriptEval=true;delete A[f]}try{delete b.test}catch(o){c.support.deleteExpando=false}a.removeChild(b);if(d.attachEvent&&d.fireEvent){d.attachEvent("onclick",function k(){c.support.noCloneEvent= +false;d.detachEvent("onclick",k)});d.cloneNode(true).fireEvent("onclick")}d=s.createElement("div");d.innerHTML="";a=s.createDocumentFragment();a.appendChild(d.firstChild);c.support.checkClone=a.cloneNode(true).cloneNode(true).lastChild.checked;c(function(){var k=s.createElement("div");k.style.width=k.style.paddingLeft="1px";s.body.appendChild(k);c.boxModel=c.support.boxModel=k.offsetWidth===2;s.body.removeChild(k).style.display="none"});a=function(k){var n= +s.createElement("div");k="on"+k;var r=k in n;if(!r){n.setAttribute(k,"return;");r=typeof n[k]==="function"}return r};c.support.submitBubbles=a("submit");c.support.changeBubbles=a("change");a=b=d=e=j=null}})();c.props={"for":"htmlFor","class":"className",readonly:"readOnly",maxlength:"maxLength",cellspacing:"cellSpacing",rowspan:"rowSpan",colspan:"colSpan",tabindex:"tabIndex",usemap:"useMap",frameborder:"frameBorder"};var G="jQuery"+J(),Ya=0,za={};c.extend({cache:{},expando:G,noData:{embed:true,object:true, +applet:true},data:function(a,b,d){if(!(a.nodeName&&c.noData[a.nodeName.toLowerCase()])){a=a==A?za:a;var f=a[G],e=c.cache;if(!f&&typeof b==="string"&&d===w)return null;f||(f=++Ya);if(typeof b==="object"){a[G]=f;e[f]=c.extend(true,{},b)}else if(!e[f]){a[G]=f;e[f]={}}a=e[f];if(d!==w)a[b]=d;return typeof b==="string"?a[b]:a}},removeData:function(a,b){if(!(a.nodeName&&c.noData[a.nodeName.toLowerCase()])){a=a==A?za:a;var d=a[G],f=c.cache,e=f[d];if(b){if(e){delete e[b];c.isEmptyObject(e)&&c.removeData(a)}}else{if(c.support.deleteExpando)delete a[c.expando]; +else a.removeAttribute&&a.removeAttribute(c.expando);delete f[d]}}}});c.fn.extend({data:function(a,b){if(typeof a==="undefined"&&this.length)return c.data(this[0]);else if(typeof a==="object")return this.each(function(){c.data(this,a)});var d=a.split(".");d[1]=d[1]?"."+d[1]:"";if(b===w){var f=this.triggerHandler("getData"+d[1]+"!",[d[0]]);if(f===w&&this.length)f=c.data(this[0],a);return f===w&&d[1]?this.data(d[0]):f}else return this.trigger("setData"+d[1]+"!",[d[0],b]).each(function(){c.data(this, +a,b)})},removeData:function(a){return this.each(function(){c.removeData(this,a)})}});c.extend({queue:function(a,b,d){if(a){b=(b||"fx")+"queue";var f=c.data(a,b);if(!d)return f||[];if(!f||c.isArray(d))f=c.data(a,b,c.makeArray(d));else f.push(d);return f}},dequeue:function(a,b){b=b||"fx";var d=c.queue(a,b),f=d.shift();if(f==="inprogress")f=d.shift();if(f){b==="fx"&&d.unshift("inprogress");f.call(a,function(){c.dequeue(a,b)})}}});c.fn.extend({queue:function(a,b){if(typeof a!=="string"){b=a;a="fx"}if(b=== +w)return c.queue(this[0],a);return this.each(function(){var d=c.queue(this,a,b);a==="fx"&&d[0]!=="inprogress"&&c.dequeue(this,a)})},dequeue:function(a){return this.each(function(){c.dequeue(this,a)})},delay:function(a,b){a=c.fx?c.fx.speeds[a]||a:a;b=b||"fx";return this.queue(b,function(){var d=this;setTimeout(function(){c.dequeue(d,b)},a)})},clearQueue:function(a){return this.queue(a||"fx",[])}});var Aa=/[\n\t]/g,ca=/\s+/,Za=/\r/g,$a=/href|src|style/,ab=/(button|input)/i,bb=/(button|input|object|select|textarea)/i, +cb=/^(a|area)$/i,Ba=/radio|checkbox/;c.fn.extend({attr:function(a,b){return X(this,a,b,true,c.attr)},removeAttr:function(a){return this.each(function(){c.attr(this,a,"");this.nodeType===1&&this.removeAttribute(a)})},addClass:function(a){if(c.isFunction(a))return this.each(function(n){var r=c(this);r.addClass(a.call(this,n,r.attr("class")))});if(a&&typeof a==="string")for(var b=(a||"").split(ca),d=0,f=this.length;d-1)return true;return false},val:function(a){if(a===w){var b=this[0];if(b){if(c.nodeName(b,"option"))return(b.attributes.value||{}).specified?b.value:b.text;if(c.nodeName(b,"select")){var d=b.selectedIndex,f=[],e=b.options;b=b.type==="select-one";if(d<0)return null;var j=b?d:0;for(d=b?d+1:e.length;j=0;else if(c.nodeName(this,"select")){var u=c.makeArray(r);c("option",this).each(function(){this.selected= +c.inArray(c(this).val(),u)>=0});if(!u.length)this.selectedIndex=-1}else this.value=r}})}});c.extend({attrFn:{val:true,css:true,html:true,text:true,data:true,width:true,height:true,offset:true},attr:function(a,b,d,f){if(!a||a.nodeType===3||a.nodeType===8)return w;if(f&&b in c.attrFn)return c(a)[b](d);f=a.nodeType!==1||!c.isXMLDoc(a);var e=d!==w;b=f&&c.props[b]||b;if(a.nodeType===1){var j=$a.test(b);if(b in a&&f&&!j){if(e){b==="type"&&ab.test(a.nodeName)&&a.parentNode&&c.error("type property can't be changed"); +a[b]=d}if(c.nodeName(a,"form")&&a.getAttributeNode(b))return a.getAttributeNode(b).nodeValue;if(b==="tabIndex")return(b=a.getAttributeNode("tabIndex"))&&b.specified?b.value:bb.test(a.nodeName)||cb.test(a.nodeName)&&a.href?0:w;return a[b]}if(!c.support.style&&f&&b==="style"){if(e)a.style.cssText=""+d;return a.style.cssText}e&&a.setAttribute(b,""+d);a=!c.support.hrefNormalized&&f&&j?a.getAttribute(b,2):a.getAttribute(b);return a===null?w:a}return c.style(a,b,d)}});var O=/\.(.*)$/,db=function(a){return a.replace(/[^\w\s\.\|`]/g, +function(b){return"\\"+b})};c.event={add:function(a,b,d,f){if(!(a.nodeType===3||a.nodeType===8)){if(a.setInterval&&a!==A&&!a.frameElement)a=A;var e,j;if(d.handler){e=d;d=e.handler}if(!d.guid)d.guid=c.guid++;if(j=c.data(a)){var i=j.events=j.events||{},o=j.handle;if(!o)j.handle=o=function(){return typeof c!=="undefined"&&!c.event.triggered?c.event.handle.apply(o.elem,arguments):w};o.elem=a;b=b.split(" ");for(var k,n=0,r;k=b[n++];){j=e?c.extend({},e):{handler:d,data:f};if(k.indexOf(".")>-1){r=k.split("."); +k=r.shift();j.namespace=r.slice(0).sort().join(".")}else{r=[];j.namespace=""}j.type=k;j.guid=d.guid;var u=i[k],z=c.event.special[k]||{};if(!u){u=i[k]=[];if(!z.setup||z.setup.call(a,f,r,o)===false)if(a.addEventListener)a.addEventListener(k,o,false);else a.attachEvent&&a.attachEvent("on"+k,o)}if(z.add){z.add.call(a,j);if(!j.handler.guid)j.handler.guid=d.guid}u.push(j);c.event.global[k]=true}a=null}}},global:{},remove:function(a,b,d,f){if(!(a.nodeType===3||a.nodeType===8)){var e,j=0,i,o,k,n,r,u,z=c.data(a), +C=z&&z.events;if(z&&C){if(b&&b.type){d=b.handler;b=b.type}if(!b||typeof b==="string"&&b.charAt(0)==="."){b=b||"";for(e in C)c.event.remove(a,e+b)}else{for(b=b.split(" ");e=b[j++];){n=e;i=e.indexOf(".")<0;o=[];if(!i){o=e.split(".");e=o.shift();k=new RegExp("(^|\\.)"+c.map(o.slice(0).sort(),db).join("\\.(?:.*\\.)?")+"(\\.|$)")}if(r=C[e])if(d){n=c.event.special[e]||{};for(B=f||0;B=0){a.type= +e=e.slice(0,-1);a.exclusive=true}if(!d){a.stopPropagation();c.event.global[e]&&c.each(c.cache,function(){this.events&&this.events[e]&&c.event.trigger(a,b,this.handle.elem)})}if(!d||d.nodeType===3||d.nodeType===8)return w;a.result=w;a.target=d;b=c.makeArray(b);b.unshift(a)}a.currentTarget=d;(f=c.data(d,"handle"))&&f.apply(d,b);f=d.parentNode||d.ownerDocument;try{if(!(d&&d.nodeName&&c.noData[d.nodeName.toLowerCase()]))if(d["on"+e]&&d["on"+e].apply(d,b)===false)a.result=false}catch(j){}if(!a.isPropagationStopped()&& +f)c.event.trigger(a,b,f,true);else if(!a.isDefaultPrevented()){f=a.target;var i,o=c.nodeName(f,"a")&&e==="click",k=c.event.special[e]||{};if((!k._default||k._default.call(d,a)===false)&&!o&&!(f&&f.nodeName&&c.noData[f.nodeName.toLowerCase()])){try{if(f[e]){if(i=f["on"+e])f["on"+e]=null;c.event.triggered=true;f[e]()}}catch(n){}if(i)f["on"+e]=i;c.event.triggered=false}}},handle:function(a){var b,d,f,e;a=arguments[0]=c.event.fix(a||A.event);a.currentTarget=this;b=a.type.indexOf(".")<0&&!a.exclusive; +if(!b){d=a.type.split(".");a.type=d.shift();f=new RegExp("(^|\\.)"+d.slice(0).sort().join("\\.(?:.*\\.)?")+"(\\.|$)")}e=c.data(this,"events");d=e[a.type];if(e&&d){d=d.slice(0);e=0;for(var j=d.length;e-1?c.map(a.options,function(f){return f.selected}).join("-"):"";else if(a.nodeName.toLowerCase()==="select")d=a.selectedIndex;return d},fa=function(a,b){var d=a.target,f,e;if(!(!da.test(d.nodeName)||d.readOnly)){f=c.data(d,"_change_data");e=Fa(d);if(a.type!=="focusout"||d.type!=="radio")c.data(d,"_change_data", +e);if(!(f===w||e===f))if(f!=null||e){a.type="change";return c.event.trigger(a,b,d)}}};c.event.special.change={filters:{focusout:fa,click:function(a){var b=a.target,d=b.type;if(d==="radio"||d==="checkbox"||b.nodeName.toLowerCase()==="select")return fa.call(this,a)},keydown:function(a){var b=a.target,d=b.type;if(a.keyCode===13&&b.nodeName.toLowerCase()!=="textarea"||a.keyCode===32&&(d==="checkbox"||d==="radio")||d==="select-multiple")return fa.call(this,a)},beforeactivate:function(a){a=a.target;c.data(a, +"_change_data",Fa(a))}},setup:function(){if(this.type==="file")return false;for(var a in ea)c.event.add(this,a+".specialChange",ea[a]);return da.test(this.nodeName)},teardown:function(){c.event.remove(this,".specialChange");return da.test(this.nodeName)}};ea=c.event.special.change.filters}s.addEventListener&&c.each({focus:"focusin",blur:"focusout"},function(a,b){function d(f){f=c.event.fix(f);f.type=b;return c.event.handle.call(this,f)}c.event.special[b]={setup:function(){this.addEventListener(a, +d,true)},teardown:function(){this.removeEventListener(a,d,true)}}});c.each(["bind","one"],function(a,b){c.fn[b]=function(d,f,e){if(typeof d==="object"){for(var j in d)this[b](j,f,d[j],e);return this}if(c.isFunction(f)){e=f;f=w}var i=b==="one"?c.proxy(e,function(k){c(this).unbind(k,i);return e.apply(this,arguments)}):e;if(d==="unload"&&b!=="one")this.one(d,f,e);else{j=0;for(var o=this.length;j0){y=t;break}}t=t[g]}m[q]=y}}}var f=/((?:\((?:\([^()]+\)|[^()]+)+\)|\[(?:\[[^[\]]*\]|['"][^'"]*['"]|[^[\]'"]+)+\]|\\.|[^ >+~,(\[\\]+)+|[>+~])(\s*,\s*)?((?:.|\r|\n)*)/g, +e=0,j=Object.prototype.toString,i=false,o=true;[0,0].sort(function(){o=false;return 0});var k=function(g,h,l,m){l=l||[];var q=h=h||s;if(h.nodeType!==1&&h.nodeType!==9)return[];if(!g||typeof g!=="string")return l;for(var p=[],v,t,y,S,H=true,M=x(h),I=g;(f.exec(""),v=f.exec(I))!==null;){I=v[3];p.push(v[1]);if(v[2]){S=v[3];break}}if(p.length>1&&r.exec(g))if(p.length===2&&n.relative[p[0]])t=ga(p[0]+p[1],h);else for(t=n.relative[p[0]]?[h]:k(p.shift(),h);p.length;){g=p.shift();if(n.relative[g])g+=p.shift(); +t=ga(g,t)}else{if(!m&&p.length>1&&h.nodeType===9&&!M&&n.match.ID.test(p[0])&&!n.match.ID.test(p[p.length-1])){v=k.find(p.shift(),h,M);h=v.expr?k.filter(v.expr,v.set)[0]:v.set[0]}if(h){v=m?{expr:p.pop(),set:z(m)}:k.find(p.pop(),p.length===1&&(p[0]==="~"||p[0]==="+")&&h.parentNode?h.parentNode:h,M);t=v.expr?k.filter(v.expr,v.set):v.set;if(p.length>0)y=z(t);else H=false;for(;p.length;){var D=p.pop();v=D;if(n.relative[D])v=p.pop();else D="";if(v==null)v=h;n.relative[D](y,v,M)}}else y=[]}y||(y=t);y||k.error(D|| +g);if(j.call(y)==="[object Array]")if(H)if(h&&h.nodeType===1)for(g=0;y[g]!=null;g++){if(y[g]&&(y[g]===true||y[g].nodeType===1&&E(h,y[g])))l.push(t[g])}else for(g=0;y[g]!=null;g++)y[g]&&y[g].nodeType===1&&l.push(t[g]);else l.push.apply(l,y);else z(y,l);if(S){k(S,q,l,m);k.uniqueSort(l)}return l};k.uniqueSort=function(g){if(B){i=o;g.sort(B);if(i)for(var h=1;h":function(g,h){var l=typeof h==="string";if(l&&!/\W/.test(h)){h=h.toLowerCase();for(var m=0,q=g.length;m=0))l||m.push(v);else if(l)h[p]=false;return false},ID:function(g){return g[1].replace(/\\/g,"")},TAG:function(g){return g[1].toLowerCase()}, +CHILD:function(g){if(g[1]==="nth"){var h=/(-?)(\d*)n((?:\+|-)?\d*)/.exec(g[2]==="even"&&"2n"||g[2]==="odd"&&"2n+1"||!/\D/.test(g[2])&&"0n+"+g[2]||g[2]);g[2]=h[1]+(h[2]||1)-0;g[3]=h[3]-0}g[0]=e++;return g},ATTR:function(g,h,l,m,q,p){h=g[1].replace(/\\/g,"");if(!p&&n.attrMap[h])g[1]=n.attrMap[h];if(g[2]==="~=")g[4]=" "+g[4]+" ";return g},PSEUDO:function(g,h,l,m,q){if(g[1]==="not")if((f.exec(g[3])||"").length>1||/^\w/.test(g[3]))g[3]=k(g[3],null,null,h);else{g=k.filter(g[3],h,l,true^q);l||m.push.apply(m, +g);return false}else if(n.match.POS.test(g[0])||n.match.CHILD.test(g[0]))return true;return g},POS:function(g){g.unshift(true);return g}},filters:{enabled:function(g){return g.disabled===false&&g.type!=="hidden"},disabled:function(g){return g.disabled===true},checked:function(g){return g.checked===true},selected:function(g){return g.selected===true},parent:function(g){return!!g.firstChild},empty:function(g){return!g.firstChild},has:function(g,h,l){return!!k(l[3],g).length},header:function(g){return/h\d/i.test(g.nodeName)}, +text:function(g){return"text"===g.type},radio:function(g){return"radio"===g.type},checkbox:function(g){return"checkbox"===g.type},file:function(g){return"file"===g.type},password:function(g){return"password"===g.type},submit:function(g){return"submit"===g.type},image:function(g){return"image"===g.type},reset:function(g){return"reset"===g.type},button:function(g){return"button"===g.type||g.nodeName.toLowerCase()==="button"},input:function(g){return/input|select|textarea|button/i.test(g.nodeName)}}, +setFilters:{first:function(g,h){return h===0},last:function(g,h,l,m){return h===m.length-1},even:function(g,h){return h%2===0},odd:function(g,h){return h%2===1},lt:function(g,h,l){return hl[3]-0},nth:function(g,h,l){return l[3]-0===h},eq:function(g,h,l){return l[3]-0===h}},filter:{PSEUDO:function(g,h,l,m){var q=h[1],p=n.filters[q];if(p)return p(g,l,h,m);else if(q==="contains")return(g.textContent||g.innerText||a([g])||"").indexOf(h[3])>=0;else if(q==="not"){h= +h[3];l=0;for(m=h.length;l=0}},ID:function(g,h){return g.nodeType===1&&g.getAttribute("id")===h},TAG:function(g,h){return h==="*"&&g.nodeType===1||g.nodeName.toLowerCase()===h},CLASS:function(g,h){return(" "+(g.className||g.getAttribute("class"))+" ").indexOf(h)>-1},ATTR:function(g,h){var l=h[1];g=n.attrHandle[l]?n.attrHandle[l](g):g[l]!=null?g[l]:g.getAttribute(l);l=g+"";var m=h[2];h=h[4];return g==null?m==="!=":m=== +"="?l===h:m==="*="?l.indexOf(h)>=0:m==="~="?(" "+l+" ").indexOf(h)>=0:!h?l&&g!==false:m==="!="?l!==h:m==="^="?l.indexOf(h)===0:m==="$="?l.substr(l.length-h.length)===h:m==="|="?l===h||l.substr(0,h.length+1)===h+"-":false},POS:function(g,h,l,m){var q=n.setFilters[h[2]];if(q)return q(g,l,h,m)}}},r=n.match.POS;for(var u in n.match){n.match[u]=new RegExp(n.match[u].source+/(?![^\[]*\])(?![^\(]*\))/.source);n.leftMatch[u]=new RegExp(/(^(?:.|\r|\n)*?)/.source+n.match[u].source.replace(/\\(\d+)/g,function(g, +h){return"\\"+(h-0+1)}))}var z=function(g,h){g=Array.prototype.slice.call(g,0);if(h){h.push.apply(h,g);return h}return g};try{Array.prototype.slice.call(s.documentElement.childNodes,0)}catch(C){z=function(g,h){h=h||[];if(j.call(g)==="[object Array]")Array.prototype.push.apply(h,g);else if(typeof g.length==="number")for(var l=0,m=g.length;l";var l=s.documentElement;l.insertBefore(g,l.firstChild);if(s.getElementById(h)){n.find.ID=function(m,q,p){if(typeof q.getElementById!=="undefined"&&!p)return(q=q.getElementById(m[1]))?q.id===m[1]||typeof q.getAttributeNode!=="undefined"&& +q.getAttributeNode("id").nodeValue===m[1]?[q]:w:[]};n.filter.ID=function(m,q){var p=typeof m.getAttributeNode!=="undefined"&&m.getAttributeNode("id");return m.nodeType===1&&p&&p.nodeValue===q}}l.removeChild(g);l=g=null})();(function(){var g=s.createElement("div");g.appendChild(s.createComment(""));if(g.getElementsByTagName("*").length>0)n.find.TAG=function(h,l){l=l.getElementsByTagName(h[1]);if(h[1]==="*"){h=[];for(var m=0;l[m];m++)l[m].nodeType===1&&h.push(l[m]);l=h}return l};g.innerHTML=""; +if(g.firstChild&&typeof g.firstChild.getAttribute!=="undefined"&&g.firstChild.getAttribute("href")!=="#")n.attrHandle.href=function(h){return h.getAttribute("href",2)};g=null})();s.querySelectorAll&&function(){var g=k,h=s.createElement("div");h.innerHTML="

";if(!(h.querySelectorAll&&h.querySelectorAll(".TEST").length===0)){k=function(m,q,p,v){q=q||s;if(!v&&q.nodeType===9&&!x(q))try{return z(q.querySelectorAll(m),p)}catch(t){}return g(m,q,p,v)};for(var l in g)k[l]=g[l];h=null}}(); +(function(){var g=s.createElement("div");g.innerHTML="
";if(!(!g.getElementsByClassName||g.getElementsByClassName("e").length===0)){g.lastChild.className="e";if(g.getElementsByClassName("e").length!==1){n.order.splice(1,0,"CLASS");n.find.CLASS=function(h,l,m){if(typeof l.getElementsByClassName!=="undefined"&&!m)return l.getElementsByClassName(h[1])};g=null}}})();var E=s.compareDocumentPosition?function(g,h){return!!(g.compareDocumentPosition(h)&16)}: +function(g,h){return g!==h&&(g.contains?g.contains(h):true)},x=function(g){return(g=(g?g.ownerDocument||g:0).documentElement)?g.nodeName!=="HTML":false},ga=function(g,h){var l=[],m="",q;for(h=h.nodeType?[h]:h;q=n.match.PSEUDO.exec(g);){m+=q[0];g=g.replace(n.match.PSEUDO,"")}g=n.relative[g]?g+"*":g;q=0;for(var p=h.length;q=0===d})};c.fn.extend({find:function(a){for(var b=this.pushStack("","find",a),d=0,f=0,e=this.length;f0)for(var j=d;j0},closest:function(a,b){if(c.isArray(a)){var d=[],f=this[0],e,j= +{},i;if(f&&a.length){e=0;for(var o=a.length;e-1:c(f).is(e)){d.push({selector:i,elem:f});delete j[i]}}f=f.parentNode}}return d}var k=c.expr.match.POS.test(a)?c(a,b||this.context):null;return this.map(function(n,r){for(;r&&r.ownerDocument&&r!==b;){if(k?k.index(r)>-1:c(r).is(a))return r;r=r.parentNode}return null})},index:function(a){if(!a||typeof a=== +"string")return c.inArray(this[0],a?c(a):this.parent().children());return c.inArray(a.jquery?a[0]:a,this)},add:function(a,b){a=typeof a==="string"?c(a,b||this.context):c.makeArray(a);b=c.merge(this.get(),a);return this.pushStack(qa(a[0])||qa(b[0])?b:c.unique(b))},andSelf:function(){return this.add(this.prevObject)}});c.each({parent:function(a){return(a=a.parentNode)&&a.nodeType!==11?a:null},parents:function(a){return c.dir(a,"parentNode")},parentsUntil:function(a,b,d){return c.dir(a,"parentNode", +d)},next:function(a){return c.nth(a,2,"nextSibling")},prev:function(a){return c.nth(a,2,"previousSibling")},nextAll:function(a){return c.dir(a,"nextSibling")},prevAll:function(a){return c.dir(a,"previousSibling")},nextUntil:function(a,b,d){return c.dir(a,"nextSibling",d)},prevUntil:function(a,b,d){return c.dir(a,"previousSibling",d)},siblings:function(a){return c.sibling(a.parentNode.firstChild,a)},children:function(a){return c.sibling(a.firstChild)},contents:function(a){return c.nodeName(a,"iframe")? +a.contentDocument||a.contentWindow.document:c.makeArray(a.childNodes)}},function(a,b){c.fn[a]=function(d,f){var e=c.map(this,b,d);eb.test(a)||(f=d);if(f&&typeof f==="string")e=c.filter(f,e);e=this.length>1?c.unique(e):e;if((this.length>1||gb.test(f))&&fb.test(a))e=e.reverse();return this.pushStack(e,a,R.call(arguments).join(","))}});c.extend({filter:function(a,b,d){if(d)a=":not("+a+")";return c.find.matches(a,b)},dir:function(a,b,d){var f=[];for(a=a[b];a&&a.nodeType!==9&&(d===w||a.nodeType!==1||!c(a).is(d));){a.nodeType=== +1&&f.push(a);a=a[b]}return f},nth:function(a,b,d){b=b||1;for(var f=0;a;a=a[d])if(a.nodeType===1&&++f===b)break;return a},sibling:function(a,b){for(var d=[];a;a=a.nextSibling)a.nodeType===1&&a!==b&&d.push(a);return d}});var Ja=/ jQuery\d+="(?:\d+|null)"/g,V=/^\s+/,Ka=/(<([\w:]+)[^>]*?)\/>/g,hb=/^(?:area|br|col|embed|hr|img|input|link|meta|param)$/i,La=/<([\w:]+)/,ib=/"},F={option:[1,""],legend:[1,"
","
"],thead:[1,"","
"],tr:[2,"","
"],td:[3,"","
"],col:[2,"","
"],area:[1,"",""],_default:[0,"",""]};F.optgroup=F.option;F.tbody=F.tfoot=F.colgroup=F.caption=F.thead;F.th=F.td;if(!c.support.htmlSerialize)F._default=[1,"div
","
"];c.fn.extend({text:function(a){if(c.isFunction(a))return this.each(function(b){var d= +c(this);d.text(a.call(this,b,d.text()))});if(typeof a!=="object"&&a!==w)return this.empty().append((this[0]&&this[0].ownerDocument||s).createTextNode(a));return c.text(this)},wrapAll:function(a){if(c.isFunction(a))return this.each(function(d){c(this).wrapAll(a.call(this,d))});if(this[0]){var b=c(a,this[0].ownerDocument).eq(0).clone(true);this[0].parentNode&&b.insertBefore(this[0]);b.map(function(){for(var d=this;d.firstChild&&d.firstChild.nodeType===1;)d=d.firstChild;return d}).append(this)}return this}, +wrapInner:function(a){if(c.isFunction(a))return this.each(function(b){c(this).wrapInner(a.call(this,b))});return this.each(function(){var b=c(this),d=b.contents();d.length?d.wrapAll(a):b.append(a)})},wrap:function(a){return this.each(function(){c(this).wrapAll(a)})},unwrap:function(){return this.parent().each(function(){c.nodeName(this,"body")||c(this).replaceWith(this.childNodes)}).end()},append:function(){return this.domManip(arguments,true,function(a){this.nodeType===1&&this.appendChild(a)})}, +prepend:function(){return this.domManip(arguments,true,function(a){this.nodeType===1&&this.insertBefore(a,this.firstChild)})},before:function(){if(this[0]&&this[0].parentNode)return this.domManip(arguments,false,function(b){this.parentNode.insertBefore(b,this)});else if(arguments.length){var a=c(arguments[0]);a.push.apply(a,this.toArray());return this.pushStack(a,"before",arguments)}},after:function(){if(this[0]&&this[0].parentNode)return this.domManip(arguments,false,function(b){this.parentNode.insertBefore(b, +this.nextSibling)});else if(arguments.length){var a=this.pushStack(this,"after",arguments);a.push.apply(a,c(arguments[0]).toArray());return a}},remove:function(a,b){for(var d=0,f;(f=this[d])!=null;d++)if(!a||c.filter(a,[f]).length){if(!b&&f.nodeType===1){c.cleanData(f.getElementsByTagName("*"));c.cleanData([f])}f.parentNode&&f.parentNode.removeChild(f)}return this},empty:function(){for(var a=0,b;(b=this[a])!=null;a++)for(b.nodeType===1&&c.cleanData(b.getElementsByTagName("*"));b.firstChild;)b.removeChild(b.firstChild); +return this},clone:function(a){var b=this.map(function(){if(!c.support.noCloneEvent&&!c.isXMLDoc(this)){var d=this.outerHTML,f=this.ownerDocument;if(!d){d=f.createElement("div");d.appendChild(this.cloneNode(true));d=d.innerHTML}return c.clean([d.replace(Ja,"").replace(/=([^="'>\s]+\/)>/g,'="$1">').replace(V,"")],f)[0]}else return this.cloneNode(true)});if(a===true){ra(this,b);ra(this.find("*"),b.find("*"))}return b},html:function(a){if(a===w)return this[0]&&this[0].nodeType===1?this[0].innerHTML.replace(Ja, +""):null;else if(typeof a==="string"&&!ta.test(a)&&(c.support.leadingWhitespace||!V.test(a))&&!F[(La.exec(a)||["",""])[1].toLowerCase()]){a=a.replace(Ka,Ma);try{for(var b=0,d=this.length;b0||e.cacheable||this.length>1?k.cloneNode(true):k)}o.length&&c.each(o,Qa)}return this}});c.fragments={};c.each({appendTo:"append",prependTo:"prepend",insertBefore:"before",insertAfter:"after",replaceAll:"replaceWith"},function(a,b){c.fn[a]=function(d){var f=[];d=c(d);var e=this.length===1&&this[0].parentNode;if(e&&e.nodeType===11&&e.childNodes.length===1&&d.length===1){d[b](this[0]); +return this}else{e=0;for(var j=d.length;e0?this.clone(true):this).get();c.fn[b].apply(c(d[e]),i);f=f.concat(i)}return this.pushStack(f,a,d.selector)}}});c.extend({clean:function(a,b,d,f){b=b||s;if(typeof b.createElement==="undefined")b=b.ownerDocument||b[0]&&b[0].ownerDocument||s;for(var e=[],j=0,i;(i=a[j])!=null;j++){if(typeof i==="number")i+="";if(i){if(typeof i==="string"&&!jb.test(i))i=b.createTextNode(i);else if(typeof i==="string"){i=i.replace(Ka,Ma);var o=(La.exec(i)||["", +""])[1].toLowerCase(),k=F[o]||F._default,n=k[0],r=b.createElement("div");for(r.innerHTML=k[1]+i+k[2];n--;)r=r.lastChild;if(!c.support.tbody){n=ib.test(i);o=o==="table"&&!n?r.firstChild&&r.firstChild.childNodes:k[1]===""&&!n?r.childNodes:[];for(k=o.length-1;k>=0;--k)c.nodeName(o[k],"tbody")&&!o[k].childNodes.length&&o[k].parentNode.removeChild(o[k])}!c.support.leadingWhitespace&&V.test(i)&&r.insertBefore(b.createTextNode(V.exec(i)[0]),r.firstChild);i=r.childNodes}if(i.nodeType)e.push(i);else e= +c.merge(e,i)}}if(d)for(j=0;e[j];j++)if(f&&c.nodeName(e[j],"script")&&(!e[j].type||e[j].type.toLowerCase()==="text/javascript"))f.push(e[j].parentNode?e[j].parentNode.removeChild(e[j]):e[j]);else{e[j].nodeType===1&&e.splice.apply(e,[j+1,0].concat(c.makeArray(e[j].getElementsByTagName("script"))));d.appendChild(e[j])}return e},cleanData:function(a){for(var b,d,f=c.cache,e=c.event.special,j=c.support.deleteExpando,i=0,o;(o=a[i])!=null;i++)if(d=o[c.expando]){b=f[d];if(b.events)for(var k in b.events)e[k]? +c.event.remove(o,k):Ca(o,k,b.handle);if(j)delete o[c.expando];else o.removeAttribute&&o.removeAttribute(c.expando);delete f[d]}}});var kb=/z-?index|font-?weight|opacity|zoom|line-?height/i,Na=/alpha\([^)]*\)/,Oa=/opacity=([^)]*)/,ha=/float/i,ia=/-([a-z])/ig,lb=/([A-Z])/g,mb=/^-?\d+(?:px)?$/i,nb=/^-?\d/,ob={position:"absolute",visibility:"hidden",display:"block"},pb=["Left","Right"],qb=["Top","Bottom"],rb=s.defaultView&&s.defaultView.getComputedStyle,Pa=c.support.cssFloat?"cssFloat":"styleFloat",ja= +function(a,b){return b.toUpperCase()};c.fn.css=function(a,b){return X(this,a,b,true,function(d,f,e){if(e===w)return c.curCSS(d,f);if(typeof e==="number"&&!kb.test(f))e+="px";c.style(d,f,e)})};c.extend({style:function(a,b,d){if(!a||a.nodeType===3||a.nodeType===8)return w;if((b==="width"||b==="height")&&parseFloat(d)<0)d=w;var f=a.style||a,e=d!==w;if(!c.support.opacity&&b==="opacity"){if(e){f.zoom=1;b=parseInt(d,10)+""==="NaN"?"":"alpha(opacity="+d*100+")";a=f.filter||c.curCSS(a,"filter")||"";f.filter= +Na.test(a)?a.replace(Na,b):b}return f.filter&&f.filter.indexOf("opacity=")>=0?parseFloat(Oa.exec(f.filter)[1])/100+"":""}if(ha.test(b))b=Pa;b=b.replace(ia,ja);if(e)f[b]=d;return f[b]},css:function(a,b,d,f){if(b==="width"||b==="height"){var e,j=b==="width"?pb:qb;function i(){e=b==="width"?a.offsetWidth:a.offsetHeight;f!=="border"&&c.each(j,function(){f||(e-=parseFloat(c.curCSS(a,"padding"+this,true))||0);if(f==="margin")e+=parseFloat(c.curCSS(a,"margin"+this,true))||0;else e-=parseFloat(c.curCSS(a, +"border"+this+"Width",true))||0})}a.offsetWidth!==0?i():c.swap(a,ob,i);return Math.max(0,Math.round(e))}return c.curCSS(a,b,d)},curCSS:function(a,b,d){var f,e=a.style;if(!c.support.opacity&&b==="opacity"&&a.currentStyle){f=Oa.test(a.currentStyle.filter||"")?parseFloat(RegExp.$1)/100+"":"";return f===""?"1":f}if(ha.test(b))b=Pa;if(!d&&e&&e[b])f=e[b];else if(rb){if(ha.test(b))b="float";b=b.replace(lb,"-$1").toLowerCase();e=a.ownerDocument.defaultView;if(!e)return null;if(a=e.getComputedStyle(a,null))f= +a.getPropertyValue(b);if(b==="opacity"&&f==="")f="1"}else if(a.currentStyle){d=b.replace(ia,ja);f=a.currentStyle[b]||a.currentStyle[d];if(!mb.test(f)&&nb.test(f)){b=e.left;var j=a.runtimeStyle.left;a.runtimeStyle.left=a.currentStyle.left;e.left=d==="fontSize"?"1em":f||0;f=e.pixelLeft+"px";e.left=b;a.runtimeStyle.left=j}}return f},swap:function(a,b,d){var f={};for(var e in b){f[e]=a.style[e];a.style[e]=b[e]}d.call(a);for(e in b)a.style[e]=f[e]}});if(c.expr&&c.expr.filters){c.expr.filters.hidden=function(a){var b= +a.offsetWidth,d=a.offsetHeight,f=a.nodeName.toLowerCase()==="tr";return b===0&&d===0&&!f?true:b>0&&d>0&&!f?false:c.curCSS(a,"display")==="none"};c.expr.filters.visible=function(a){return!c.expr.filters.hidden(a)}}var sb=J(),tb=//gi,ub=/select|textarea/i,vb=/color|date|datetime|email|hidden|month|number|password|range|search|tel|text|time|url|week/i,N=/=\?(&|$)/,ka=/\?/,wb=/(\?|&)_=.*?(&|$)/,xb=/^(\w+:)?\/\/([^\/?#]+)/,yb=/%20/g,zb=c.fn.load;c.fn.extend({load:function(a,b,d){if(typeof a!== +"string")return zb.call(this,a);else if(!this.length)return this;var f=a.indexOf(" ");if(f>=0){var e=a.slice(f,a.length);a=a.slice(0,f)}f="GET";if(b)if(c.isFunction(b)){d=b;b=null}else if(typeof b==="object"){b=c.param(b,c.ajaxSettings.traditional);f="POST"}var j=this;c.ajax({url:a,type:f,dataType:"html",data:b,complete:function(i,o){if(o==="success"||o==="notmodified")j.html(e?c("
").append(i.responseText.replace(tb,"")).find(e):i.responseText);d&&j.each(d,[i.responseText,o,i])}});return this}, +serialize:function(){return c.param(this.serializeArray())},serializeArray:function(){return this.map(function(){return this.elements?c.makeArray(this.elements):this}).filter(function(){return this.name&&!this.disabled&&(this.checked||ub.test(this.nodeName)||vb.test(this.type))}).map(function(a,b){a=c(this).val();return a==null?null:c.isArray(a)?c.map(a,function(d){return{name:b.name,value:d}}):{name:b.name,value:a}}).get()}});c.each("ajaxStart ajaxStop ajaxComplete ajaxError ajaxSuccess ajaxSend".split(" "), +function(a,b){c.fn[b]=function(d){return this.bind(b,d)}});c.extend({get:function(a,b,d,f){if(c.isFunction(b)){f=f||d;d=b;b=null}return c.ajax({type:"GET",url:a,data:b,success:d,dataType:f})},getScript:function(a,b){return c.get(a,null,b,"script")},getJSON:function(a,b,d){return c.get(a,b,d,"json")},post:function(a,b,d,f){if(c.isFunction(b)){f=f||d;d=b;b={}}return c.ajax({type:"POST",url:a,data:b,success:d,dataType:f})},ajaxSetup:function(a){c.extend(c.ajaxSettings,a)},ajaxSettings:{url:location.href, +global:true,type:"GET",contentType:"application/x-www-form-urlencoded",processData:true,async:true,xhr:A.XMLHttpRequest&&(A.location.protocol!=="file:"||!A.ActiveXObject)?function(){return new A.XMLHttpRequest}:function(){try{return new A.ActiveXObject("Microsoft.XMLHTTP")}catch(a){}},accepts:{xml:"application/xml, text/xml",html:"text/html",script:"text/javascript, application/javascript",json:"application/json, text/javascript",text:"text/plain",_default:"*/*"}},lastModified:{},etag:{},ajax:function(a){function b(){e.success&& +e.success.call(k,o,i,x);e.global&&f("ajaxSuccess",[x,e])}function d(){e.complete&&e.complete.call(k,x,i);e.global&&f("ajaxComplete",[x,e]);e.global&&!--c.active&&c.event.trigger("ajaxStop")}function f(q,p){(e.context?c(e.context):c.event).trigger(q,p)}var e=c.extend(true,{},c.ajaxSettings,a),j,i,o,k=a&&a.context||e,n=e.type.toUpperCase();if(e.data&&e.processData&&typeof e.data!=="string")e.data=c.param(e.data,e.traditional);if(e.dataType==="jsonp"){if(n==="GET")N.test(e.url)||(e.url+=(ka.test(e.url)? +"&":"?")+(e.jsonp||"callback")+"=?");else if(!e.data||!N.test(e.data))e.data=(e.data?e.data+"&":"")+(e.jsonp||"callback")+"=?";e.dataType="json"}if(e.dataType==="json"&&(e.data&&N.test(e.data)||N.test(e.url))){j=e.jsonpCallback||"jsonp"+sb++;if(e.data)e.data=(e.data+"").replace(N,"="+j+"$1");e.url=e.url.replace(N,"="+j+"$1");e.dataType="script";A[j]=A[j]||function(q){o=q;b();d();A[j]=w;try{delete A[j]}catch(p){}z&&z.removeChild(C)}}if(e.dataType==="script"&&e.cache===null)e.cache=false;if(e.cache=== +false&&n==="GET"){var r=J(),u=e.url.replace(wb,"$1_="+r+"$2");e.url=u+(u===e.url?(ka.test(e.url)?"&":"?")+"_="+r:"")}if(e.data&&n==="GET")e.url+=(ka.test(e.url)?"&":"?")+e.data;e.global&&!c.active++&&c.event.trigger("ajaxStart");r=(r=xb.exec(e.url))&&(r[1]&&r[1]!==location.protocol||r[2]!==location.host);if(e.dataType==="script"&&n==="GET"&&r){var z=s.getElementsByTagName("head")[0]||s.documentElement,C=s.createElement("script");C.src=e.url;if(e.scriptCharset)C.charset=e.scriptCharset;if(!j){var B= +false;C.onload=C.onreadystatechange=function(){if(!B&&(!this.readyState||this.readyState==="loaded"||this.readyState==="complete")){B=true;b();d();C.onload=C.onreadystatechange=null;z&&C.parentNode&&z.removeChild(C)}}}z.insertBefore(C,z.firstChild);return w}var E=false,x=e.xhr();if(x){e.username?x.open(n,e.url,e.async,e.username,e.password):x.open(n,e.url,e.async);try{if(e.data||a&&a.contentType)x.setRequestHeader("Content-Type",e.contentType);if(e.ifModified){c.lastModified[e.url]&&x.setRequestHeader("If-Modified-Since", +c.lastModified[e.url]);c.etag[e.url]&&x.setRequestHeader("If-None-Match",c.etag[e.url])}r||x.setRequestHeader("X-Requested-With","XMLHttpRequest");x.setRequestHeader("Accept",e.dataType&&e.accepts[e.dataType]?e.accepts[e.dataType]+", */*":e.accepts._default)}catch(ga){}if(e.beforeSend&&e.beforeSend.call(k,x,e)===false){e.global&&!--c.active&&c.event.trigger("ajaxStop");x.abort();return false}e.global&&f("ajaxSend",[x,e]);var g=x.onreadystatechange=function(q){if(!x||x.readyState===0||q==="abort"){E|| +d();E=true;if(x)x.onreadystatechange=c.noop}else if(!E&&x&&(x.readyState===4||q==="timeout")){E=true;x.onreadystatechange=c.noop;i=q==="timeout"?"timeout":!c.httpSuccess(x)?"error":e.ifModified&&c.httpNotModified(x,e.url)?"notmodified":"success";var p;if(i==="success")try{o=c.httpData(x,e.dataType,e)}catch(v){i="parsererror";p=v}if(i==="success"||i==="notmodified")j||b();else c.handleError(e,x,i,p);d();q==="timeout"&&x.abort();if(e.async)x=null}};try{var h=x.abort;x.abort=function(){x&&h.call(x); +g("abort")}}catch(l){}e.async&&e.timeout>0&&setTimeout(function(){x&&!E&&g("timeout")},e.timeout);try{x.send(n==="POST"||n==="PUT"||n==="DELETE"?e.data:null)}catch(m){c.handleError(e,x,null,m);d()}e.async||g();return x}},handleError:function(a,b,d,f){if(a.error)a.error.call(a.context||a,b,d,f);if(a.global)(a.context?c(a.context):c.event).trigger("ajaxError",[b,a,f])},active:0,httpSuccess:function(a){try{return!a.status&&location.protocol==="file:"||a.status>=200&&a.status<300||a.status===304||a.status=== +1223||a.status===0}catch(b){}return false},httpNotModified:function(a,b){var d=a.getResponseHeader("Last-Modified"),f=a.getResponseHeader("Etag");if(d)c.lastModified[b]=d;if(f)c.etag[b]=f;return a.status===304||a.status===0},httpData:function(a,b,d){var f=a.getResponseHeader("content-type")||"",e=b==="xml"||!b&&f.indexOf("xml")>=0;a=e?a.responseXML:a.responseText;e&&a.documentElement.nodeName==="parsererror"&&c.error("parsererror");if(d&&d.dataFilter)a=d.dataFilter(a,b);if(typeof a==="string")if(b=== +"json"||!b&&f.indexOf("json")>=0)a=c.parseJSON(a);else if(b==="script"||!b&&f.indexOf("javascript")>=0)c.globalEval(a);return a},param:function(a,b){function d(i,o){if(c.isArray(o))c.each(o,function(k,n){b||/\[\]$/.test(i)?f(i,n):d(i+"["+(typeof n==="object"||c.isArray(n)?k:"")+"]",n)});else!b&&o!=null&&typeof o==="object"?c.each(o,function(k,n){d(i+"["+k+"]",n)}):f(i,o)}function f(i,o){o=c.isFunction(o)?o():o;e[e.length]=encodeURIComponent(i)+"="+encodeURIComponent(o)}var e=[];if(b===w)b=c.ajaxSettings.traditional; +if(c.isArray(a)||a.jquery)c.each(a,function(){f(this.name,this.value)});else for(var j in a)d(j,a[j]);return e.join("&").replace(yb,"+")}});var la={},Ab=/toggle|show|hide/,Bb=/^([+-]=)?([\d+-.]+)(.*)$/,W,va=[["height","marginTop","marginBottom","paddingTop","paddingBottom"],["width","marginLeft","marginRight","paddingLeft","paddingRight"],["opacity"]];c.fn.extend({show:function(a,b){if(a||a===0)return this.animate(K("show",3),a,b);else{a=0;for(b=this.length;a").appendTo("body");f=e.css("display");if(f==="none")f="block";e.remove();la[d]=f}c.data(this[a],"olddisplay",f)}}a=0;for(b=this.length;a=0;f--)if(d[f].elem===this){b&&d[f](true);d.splice(f,1)}});b||this.dequeue();return this}});c.each({slideDown:K("show",1),slideUp:K("hide",1),slideToggle:K("toggle",1),fadeIn:{opacity:"show"},fadeOut:{opacity:"hide"}},function(a,b){c.fn[a]=function(d,f){return this.animate(b,d,f)}});c.extend({speed:function(a,b,d){var f=a&&typeof a==="object"?a:{complete:d||!d&&b||c.isFunction(a)&&a,duration:a,easing:d&&b||b&&!c.isFunction(b)&&b};f.duration=c.fx.off?0:typeof f.duration=== +"number"?f.duration:c.fx.speeds[f.duration]||c.fx.speeds._default;f.old=f.complete;f.complete=function(){f.queue!==false&&c(this).dequeue();c.isFunction(f.old)&&f.old.call(this)};return f},easing:{linear:function(a,b,d,f){return d+f*a},swing:function(a,b,d,f){return(-Math.cos(a*Math.PI)/2+0.5)*f+d}},timers:[],fx:function(a,b,d){this.options=b;this.elem=a;this.prop=d;if(!b.orig)b.orig={}}});c.fx.prototype={update:function(){this.options.step&&this.options.step.call(this.elem,this.now,this);(c.fx.step[this.prop]|| +c.fx.step._default)(this);if((this.prop==="height"||this.prop==="width")&&this.elem.style)this.elem.style.display="block"},cur:function(a){if(this.elem[this.prop]!=null&&(!this.elem.style||this.elem.style[this.prop]==null))return this.elem[this.prop];return(a=parseFloat(c.css(this.elem,this.prop,a)))&&a>-10000?a:parseFloat(c.curCSS(this.elem,this.prop))||0},custom:function(a,b,d){function f(j){return e.step(j)}this.startTime=J();this.start=a;this.end=b;this.unit=d||this.unit||"px";this.now=this.start; +this.pos=this.state=0;var e=this;f.elem=this.elem;if(f()&&c.timers.push(f)&&!W)W=setInterval(c.fx.tick,13)},show:function(){this.options.orig[this.prop]=c.style(this.elem,this.prop);this.options.show=true;this.custom(this.prop==="width"||this.prop==="height"?1:0,this.cur());c(this.elem).show()},hide:function(){this.options.orig[this.prop]=c.style(this.elem,this.prop);this.options.hide=true;this.custom(this.cur(),0)},step:function(a){var b=J(),d=true;if(a||b>=this.options.duration+this.startTime){this.now= +this.end;this.pos=this.state=1;this.update();this.options.curAnim[this.prop]=true;for(var f in this.options.curAnim)if(this.options.curAnim[f]!==true)d=false;if(d){if(this.options.display!=null){this.elem.style.overflow=this.options.overflow;a=c.data(this.elem,"olddisplay");this.elem.style.display=a?a:this.options.display;if(c.css(this.elem,"display")==="none")this.elem.style.display="block"}this.options.hide&&c(this.elem).hide();if(this.options.hide||this.options.show)for(var e in this.options.curAnim)c.style(this.elem, +e,this.options.orig[e]);this.options.complete.call(this.elem)}return false}else{e=b-this.startTime;this.state=e/this.options.duration;a=this.options.easing||(c.easing.swing?"swing":"linear");this.pos=c.easing[this.options.specialEasing&&this.options.specialEasing[this.prop]||a](this.state,e,0,1,this.options.duration);this.now=this.start+(this.end-this.start)*this.pos;this.update()}return true}};c.extend(c.fx,{tick:function(){for(var a=c.timers,b=0;b
"; +a.insertBefore(b,a.firstChild);d=b.firstChild;f=d.firstChild;e=d.nextSibling.firstChild.firstChild;this.doesNotAddBorder=f.offsetTop!==5;this.doesAddBorderForTableAndCells=e.offsetTop===5;f.style.position="fixed";f.style.top="20px";this.supportsFixedPosition=f.offsetTop===20||f.offsetTop===15;f.style.position=f.style.top="";d.style.overflow="hidden";d.style.position="relative";this.subtractsBorderForOverflowNotVisible=f.offsetTop===-5;this.doesNotIncludeMarginInBodyOffset=a.offsetTop!==j;a.removeChild(b); +c.offset.initialize=c.noop},bodyOffset:function(a){var b=a.offsetTop,d=a.offsetLeft;c.offset.initialize();if(c.offset.doesNotIncludeMarginInBodyOffset){b+=parseFloat(c.curCSS(a,"marginTop",true))||0;d+=parseFloat(c.curCSS(a,"marginLeft",true))||0}return{top:b,left:d}},setOffset:function(a,b,d){if(/static/.test(c.curCSS(a,"position")))a.style.position="relative";var f=c(a),e=f.offset(),j=parseInt(c.curCSS(a,"top",true),10)||0,i=parseInt(c.curCSS(a,"left",true),10)||0;if(c.isFunction(b))b=b.call(a, +d,e);d={top:b.top-e.top+j,left:b.left-e.left+i};"using"in b?b.using.call(a,d):f.css(d)}};c.fn.extend({position:function(){if(!this[0])return null;var a=this[0],b=this.offsetParent(),d=this.offset(),f=/^body|html$/i.test(b[0].nodeName)?{top:0,left:0}:b.offset();d.top-=parseFloat(c.curCSS(a,"marginTop",true))||0;d.left-=parseFloat(c.curCSS(a,"marginLeft",true))||0;f.top+=parseFloat(c.curCSS(b[0],"borderTopWidth",true))||0;f.left+=parseFloat(c.curCSS(b[0],"borderLeftWidth",true))||0;return{top:d.top- +f.top,left:d.left-f.left}},offsetParent:function(){return this.map(function(){for(var a=this.offsetParent||s.body;a&&!/^body|html$/i.test(a.nodeName)&&c.css(a,"position")==="static";)a=a.offsetParent;return a})}});c.each(["Left","Top"],function(a,b){var d="scroll"+b;c.fn[d]=function(f){var e=this[0],j;if(!e)return null;if(f!==w)return this.each(function(){if(j=wa(this))j.scrollTo(!a?f:c(j).scrollLeft(),a?f:c(j).scrollTop());else this[d]=f});else return(j=wa(e))?"pageXOffset"in j?j[a?"pageYOffset": +"pageXOffset"]:c.support.boxModel&&j.document.documentElement[d]||j.document.body[d]:e[d]}});c.each(["Height","Width"],function(a,b){var d=b.toLowerCase();c.fn["inner"+b]=function(){return this[0]?c.css(this[0],d,false,"padding"):null};c.fn["outer"+b]=function(f){return this[0]?c.css(this[0],d,false,f?"margin":"border"):null};c.fn[d]=function(f){var e=this[0];if(!e)return f==null?null:this;if(c.isFunction(f))return this.each(function(j){var i=c(this);i[d](f.call(this,j,i[d]()))});return"scrollTo"in +e&&e.document?e.document.compatMode==="CSS1Compat"&&e.document.documentElement["client"+b]||e.document.body["client"+b]:e.nodeType===9?Math.max(e.documentElement["client"+b],e.body["scroll"+b],e.documentElement["scroll"+b],e.body["offset"+b],e.documentElement["offset"+b]):f===w?c.css(e,d):this.css(d,typeof f==="string"?f:f+"px")}});A.jQuery=A.$=c})(window); diff --git a/docs/user/source/percona-theme/static/percona.com.css b/docs/user/source/percona-theme/static/percona.com.css new file mode 100644 index 00000000..2b118641 --- /dev/null +++ b/docs/user/source/percona-theme/static/percona.com.css @@ -0,0 +1 @@ +@charset "utf-8";html{color:#000;background:#FFF;}body,div,dl,dt,dd,ul,ol,li,h1,h2,h3,h4,h5,h6,pre,code,form,fieldset,legend,input,textarea,p,blockquote,th,td{margin:0;padding:0;}table{border-collapse:collapse;border-spacing:0;}fieldset,img{border:0;}address,caption,cite,code,dfn,em,strong,th,var{font-style:normal;font-weight:400;}li{list-style:none;}caption,th{text-align:left;}h1,h2,h3,h4,h5,h6{font-size:100%;font-weight:400;}q:before,q:after{content:'';}abbr,acronym{border:0;font-variant:normal;}sup{vertical-align:text-top;}sub{vertical-align:text-bottom;}input,textarea,select{font-family:inherit;font-weight:inherit;font-size:100%;}legend{color:#000;}del,ins{text-decoration:none;}body,html{height:100%;margin:0;padding:0}form{display:inline}a{border:none;cursor:pointer}img{border:none}div,img{behavior:url(/static/css/iepngfix.htc)}em{font-style:italic;}del{text-decoration:line-through;}.hidden{display:none}#header{background:#333;height:95px;overflow:hidden;zoom:1}#header .header{height:95px;margin:0 auto;overflow:hidden;width:960px;zoom:1}#header .header .logo{float:left;overflow:hidden;padding:20px 0;width:240px;zoom:1}#header .header .logo{overflow:hidden;zoom:1;float:left;width:240px;padding:20px 0px;}#header .header .right{overflow:hidden;zoom:1;float:left;width:720px;height:35px;padding:30px 0px;}#header .header .right .searchlink{overflow:hidden;zoom:1;width:35px;height:35px;float:right;padding:0px 0px 0px 10px;}#header .header .right .navicontainer{overflow:hidden;zoom:1;float:right;height:35px;background:#ffffff url(ui-navi-l.png) top left no-repeat;}#header .header .right .navi{overflow:hidden;zoom:1;height:27px;padding:4px 10px;background:url(ui-navi-r.png) top right no-repeat;}#header .header .right .navicontainer .navi span{overflow:hidden;zoom:1;height:27px;float:left;margin:0px;}#header .header .right .navicontainer .navi span:hover{background:#f0f0f0 url(ui-navi-hover-l.png) top left no-repeat;}#header .header .right .navicontainer .navi span.selected,#header .header .right .navicontainer .navi span.selected:hover{background:#d5390b url(ui-navi-sel-l.png) top left no-repeat;}#header .header .right .navicontainer .navi span a,#header .header .right .navicontainer .navi span a:visited{display:block;padding:6px 10px 4px 10px;height:17px;font-family:Arial,Helvetica,sans-serif;font-size:14px;line-height:14px;color:#000000;text-decoration:none;}#header .header .right .navicontainer .navi span a:hover{background:url(ui-navi-hover-r.png) top right no-repeat;}#header .header .right .navicontainer .navi span.selected a.selected,#header .header .right .navicontainer .navi span.selected a.selected:visited,#header .header .right .navicontainer .navi span.selected a.selected:hover{background:url(ui-navi-sel-r.png) top right no-repeat;color:#ffffff;}#slogan{overflow:hidden;zoom:1;height:125px;background:#d24300 urk(ui-orange-front.png) bottom center no-repeat;text-align:center;}#stripe{overflow:hidden;zoom:1;height:20px;background:#d24300 url(ui-orange-content.png) top center no-repeat;}#footer{overflow:hidden;zoom:1;background:#333333;border-top:2px #d95200 solid;}#footer .footer{overflow:hidden;zoom:1;width:960px;margin:0px auto;padding:10px 0px;}#footer .footer .logo{overflow:hidden;zoom:1;float:left;padding:17px 0px 0px 0px;}#footer .footer .text{overflow:hidden;zoom:1;float:right;text-align:right;font-family:Arial,Helvetica,sans-serif;font-size:11px;line-height:15px;color:#e0e0e0;}#footer .footer .text a,#footer .footer .text a:visited{color:#e0e0e0;text-decoration:none;}#footer .footer .text a:hover{color:#ffffff;text-decoration:underline;}div.navi-dropdown{display:none;position:absolute;overflow:hidden;zoom:1;width:255px;z-index:900;}div.navi-dropdown .navi-dropdown-header-l{overflow:hidden;zoom:1;width:255px;height:20px;background:url(ui-dropdown-header-l.png) top left no-repeat;}div.navi-dropdown .navi-dropdown-header-r{overflow:hidden;zoom:1;width:255px;height:20px;background:url(ui-dropdown-header-r.png) top left no-repeat;}div.navi-dropdown .navi-dropdown-content{overflow:hidden;zoom:1;width:225px;padding:0px 15px 5px 15px;background:#ffffff url(ui-dropdown-bg.png) repeat-y;font-family:Arial,Helvetica,sans-serif;font-size:14px;line-height:20px;color:#333333;}div.navi-dropdown .navi-dropdown-content .item{padding:3px 0px 1px 0px;}div.navi-dropdown .navi-dropdown-content a,div.navi-dropdown .navi-dropdown-content a:visited{display:block;color:#333333;text-decoration:none;}div.navi-dropdown .navi-dropdown-content a:hover{color:#d12907;text-decoration:underline;}div.navi-dropdown .navi-dropdown-footer{overflow:hidden;zoom:1;width:255px;height:10px;background:url(ui-dropdown-footer.png) top left no-repeat;}div.search-dropdown{display:none;position:absolute;overflow:hidden;zoom:1;width:255px;}div.search-dropdown .search-dropdown-header{overflow:hidden;zoom:1;width:255px;height:20px;background:url(ui-dropdown-header-search.png) top left no-repeat;}div.search-dropdown .search-dropdown-content{overflow:hidden;zoom:1;width:225px;padding:0px 15px 5px 15px;background:#ffffff url(ui-dropdown-bg.png) repeat-y;font-family:Arial,Helvetica,sans-serif;font-size:14px;line-height:20px;color:#333333;}div.search-dropdown .search-dropdown-content .form{padding-top:2px;}div.search-dropdown .search-dropdown-content .form input{border:1px #c0c0c0 solid;padding:4px;width:210px;outline:none;}div.search-dropdown .search-dropdown-content .form input:focus{border:1px #707070 solid;outline:none;}div.search-dropdown .search-dropdown-footer{overflow:hidden;zoom:1;width:255px;height:10px;background:url(ui-dropdown-footer.png) top left no-repeat;}#sidenavi{overflow:hidden;zoom:1;float:left;width:260px;border-top:1px #e0e0e0 solid;border-right:1px #e0e0e0 solid;margin:0px 30px 0px 0px;padding:0px 0px 20px 0px;font-family:Arial,Helvetica,sans-serif;font-size:18px;line-height:25px;color:#333333;}#sidenavi.noborder{border-top:none;border-right:none;margin:0px 31px 0px 0px;}#sidenavi .sidebanner{border-left:1px #e0e0e0 solid;border-bottom:1px #e0e0e0 solid;text-align:center;padding:15px 10px;}#sidenavi.noborder .sidebanner{border-top:1px #e0e0e0 solid;border-right:1px #e0e0e0 solid;}#sidenavi .sidebanner .header{padding:0px 0px 10px 0px;line-height:18px;text-align:center;}#sidenavi .sidebanner .numbers{padding:0px 0px 0px 58px;background:url(phone.png) 5px center no-repeat;font-family:Arial,Helvetica,sans-serif;font-size:12px;line-height:18px;text-align:left;}#sidenavi #sidefloater{padding-top:10px;}#sidenavi .item{padding:10px 10px 8px 10px;}#sidenavi > .item.selected{background:url(ui-leftnavi-sel.png) top left no-repeat;}#sidenavi a,#sidenavi a:visited{display:block;color:#333333;text-decoration:none;}#sidenavi a:hover{color:#d12907;text-decoration:none;}#sidenavi > .item.selected > a,#sidenavi > .item.selected > a:visited{color:#d12907;text-decoration:none;}#sidenavi .sidesubnavi{overflow:hidden;zoom:1;font-family:Arial,Helvetica,sans-serif;font-size:13px;line-height:17px;color:#333333;}#sidenavi .sidesubnavi .subitem{padding:7px 10px 0px 10px;}#sidenavi .sidesubnavi .subitem.selected a,#sidenavi .sidesubnavi .subitem.selected a:visited{color:#d12907;text-decoration:none;}#contentcontainer{overflow:hidden;zoom:1;width:960px;padding:30px 0px;margin:0px auto;}#content{overflow:hidden;zoom:1;font-family:Arial,Helvetica,sans-serif;font-size:14px;line-height:20px;color:#333333;}#content p{margin:10px 0px;}#content a,#content a:visited{color:#d12907;text-decoration:underline;}#content a:hover{color:#712000;text-decoration:underline;}#content h1{font-family:Arial,Helvetica,sans-serif;font-size:32px;line-height:40px;margin:5px 0px 20px 0px;color:#d12907;}#content h2{font-family:Arial,Helvetica,sans-serif;font-size:20px;line-height:20px;padding:0px 0px 3px 0px;margin:30px 0px 15px 0px;color:#000000;border-bottom:1px #e0e0e0 solid;}#content h3{font-family:Arial,Helvetica,sans-serif;font-weight:bold;font-size:16px;line-height:22px;margin:20px 0px 10px 0px;color:#000000;}#content h4{font-family:Arial,Helvetica,sans-serif;font-size:14px;line-height:14px;font-weight:bold;padding:5px 0px 0px 0px;margin:-16px 0px 20px 0px;color:#000000;border-top:1px #e0e0e0 solid;}#content h4 a,#content h4 a:visited{color:#000000;text-decoration:none;}#content h4 a:hover{color:#d12907;text-decoration:none;}#content dl dt{font-weight:bold;margin-top:10px;margin-bottom:10px;}#content dl dd{padding:0px 0px 0px 30px;}#content ul{list-style-type:square;padding:0px 0px 0px 30px;}#content ul li{list-style-type:square;margin:8px 0px;}#content ol{list-style-type:decimal;padding:0px 0px 0px 30px;}#content ol li{list-style-type:decimal;margin:8px 0px;}#content div.pagecontent{overflow:hidden;zoom:1;}div.contentbox{border:1px #e0e0e0 solid;}div.contentbox div.title{font-size:16px;line-height:20px;font-weight:bold;padding:8px 15px 2px 15px;background:url(ui-leftnavi-sel.png) repeat-x;}div.contentbox div.content{padding:15px;}div.frontpage-p{overflow:hidden;zoom:1;width:960px;margin:0px;margin-bottom:20px;padding:0px;}div.frontpage-p div.frontpage-p-container{overflow:hidden;zoom:1;width:960px;height:200px;padding-bottom:30px;z-index:100;}div.frontpage-p a.nivo-imageLink{position:absolute;top:0px;left:0px;width:960px;height:200px;border:0;padding:0;margin:0;z-index:20;display:none;}div.frontpage-p div.frontpage-p-container div.nivo-directionNav{width:1px;height:1px;display:none !important;z-index:18 !important;}div.frontpage-p div.frontpage-p-container div.nivo-controlNav{position:absolute;top:200px;width:960px;text-align:center;font-size:28px;line-height:25px;}div.frontpage-p div.frontpage-p-container div.nivo-controlNav a{padding:0px 3px;text-decoration:none !important;color:#919191 !important;}div.frontpage-p div.frontpage-p-container div.nivo-controlNav a.active{color:#d12907 !important;}div.frontpage-p div.frontpage-p-selector{overflow:hidden;zoom:1;height:20px;text-align:center;}div.frontpage-main{overflow:hidden;zoom:1;width:960px;margin:20px 0px;padding:0px;}div.frontpage-main div.frontpage-left{overflow:hidden;zoom:1;width:645px;float:left;padding:0px;}div.frontpage-boxes{overflow:hidden;zoom:1;width:645px;margin:25px 0px 0px 0px;padding:0px;}div.frontpage-boxes div.frontpage-boxes-selector{overflow:hidden;zoom:1;width:645px;}div.frontpage-boxes div.frontpage-boxes-selector div.frontpage-boxes-selector-item{overflow:hidden;zoom:1;width:160px;float:left;margin-left:-1px;border-top:1px #cccccc solid;border-left:1px #cccccc solid;border-right:1px #cccccc solid;border-bottom:1px #cccccc solid;text-align:center;margin-top:10px;padding:0px 0px 0px 0px;}div.frontpage-boxes div.frontpage-boxes-selector div.frontpage-boxes-selector-item:first-child{margin-left:0px;}div.frontpage-boxes div.frontpage-boxes-selector div.frontpage-boxes-selector-item.selected{background:url(ui-tab-bg.png) repeat-x;margin-top:0px;border-bottom:none;padding:5px 0px 6px 0px;}div.frontpage-boxes div.frontpage-boxes-selector div.frontpage-boxes-selector-item a{display:block;font-size:20px;line-height:20px;color:#444444 !important;text-decoration:none !important;padding:9px 0px 8px 0px;}div.frontpage-boxes div.frontpage-boxes-container{overflow:hidden;zoom:1;width:603px;height:150px;padding:20px;border-left:1px #cccccc solid;border-right:1px #cccccc solid;border-bottom:1px #cccccc solid;}div.frontpage-boxes div.frontpage-boxes-container div.frontpage-box img{padding:0px 15px 15px 5px;}div.frontpage-main div.frontpage-right{overflow:hidden;zoom:1;width:295px;float:right;margin-left:20px;padding:0px;}div.frontpage-block{overflow:hidden;zoom:1;border:1px #cccccc solid;width:288px;margin:0 0 20px 5px;}div.frontpage-block div.header{text-align:left;padding:15px 15px 0px 15px;background:url(ui-tab-bg.png) repeat-x;font-family:Arial,Helvetica,sans-serif;font-size:20px;line-height:20px;}div.frontpage-block div.content{overflow:hidden;zoom:1;padding:10px 15px 15px 15px;}div.frontpage-block div.content div.call-us{font-size:12px;line-height:17px;}div.frontpage-block div.content div.training{padding:20px;overflow:hidden;zoom:1;font-size:12px;line-height:17px;}div.frontpage-block div.content div.training ul.training-short-list{list-style-type:none !important;margin:0 !important;padding:0 !important;}div.frontpage-block div.content div.training ul.training-short-list li{list-style-type:none !important;}div.frontpage-block div.content div.more{overflow:hidden;zoom:1;text-align:right;padding:15px 0px 0px 0px;font-size:12px;line-height:17px;}.our-team-page h2{clear:both;}div.our-team-item{overflow:hidden;zoom:1;width:162px;margin-left:5px;height:230px;float:left;}div.our-team-item .img img{border:1px #e0e0e0 solid;padding:2px;}table.phonetable{margin-top:1em;border-collapse:collapse;}.phonetable{margin-left:2em;}table.phonetable th,table.phonetable tr{text-align:center;}table.phonetable th{border:1px #e0e0e0 solid;background:#f8f8f8;padding:7px;font-weight:bold;}table.phonetable td{border:1px #e0e0e0 solid;padding:7px;}table.phonetable .label{text-align:left;}table.phonetable td.label{padding-left:2em;}.form-item{clear:both;margin-top:1em;position:relative;}.form-item label{display:block;font-weight:bold;position:absolute;top:0;left:0;width:13em;}.form-required{color:#fa0;font-weight:bold;}.form-item .description{color:#888;font-size:0.85em;line-height:150%;position:relative;left:14em;}#edit-submitbutton{position:relative;left:12em;margin:1em 0;}.form-item input[type=text],.form-item select,.form-item textarea{border:1px solid #CCC;width:493px;position:relative;top:0;left:12em;}.form-item textarea{height:12em;padding:3px;}.form-item-spacer{padding-top:1em;}.form-item #captcha{position:relative;top:0;left:12em;}#edit-submitted-captcha{margin-top:0.5em;width:154px;}fieldset.form-item-set{border:1px solid #ccc;display:block;margin:12px 0;padding:12px;}fieldset.form-item-set legend{border:none;display:block;padding:0 2px;}div.error{background:#fff;border:solid 1px #c52020;color:#C52020;padding:5px;}div.messages{margin:5px 20px;font-size:11px;}div.messages ul,div.messages ul li{list-style-image:none;list-style-type:none;}div.messages ul li{padding:0 0 0.2em 0;}.form-item .error{background-color :#fdd;}#emergency-contacts .node-field-name{text-align:right;font-weight:bold;padding-right:1em;}#emergency-contacts .node-field-value-phone{font-weight:bold;color:#137F00;}#emergency-contacts .node-field-help{font-weight:bold;}#compact_footer{width:auto !important;}#compact_contentcontainer{overflow:hidden;zoom:1;width:auto;padding:30px 0px;margin:0px 20px;}.custlogo img{padding:20px;border:1px solid white;}.custlogo img:hover{border:1px solid gray;}table.formtable{border-collapse:collapse;}table.formtable th{font-weight:normal;white-space:nowrap;padding:4px 20px 4px 0px;}table.formtable td{padding:4px 0px 4px 0px;}table.formtable td input[type='text'],table.formtable td select{border:1px #e0e0e0 solid;padding:4px;width:400px;}table.formtable td.submit{padding:10px 0px 0px 0px;text-align:center;}table.datatable{margin-top:1em;border-collapse:collapse;}.datatable{margin-left:2em;}table.datatable th,table.datatable tr{text-align:center;}table.datatable th{border:1px #e0e0e0 solid;background:#f8f8f8;padding:7px;font-weight:bold;}table.datatable td{border:1px #e0e0e0 solid;padding:7px;}table.datatable .label{text-align:left;}table.datatable td.label{padding-left:2em;}.frontpage-sidebar .header{padding:0px 0px 10px 0px;font-size:18px;font-weight:normal;text-align:center;}.frontpage-sidebar .header.link{padding:13px 0px 10px 4px;text-align:left;}.frontpage-sidebar .header a,.frontpage-sidebar .header a:visited{color:#333333 !important;text-decoration:none !important;}.frontpage-sidebar .header a:hover{color:#d12907 !important;text-decoration:none !important;}.frontpage-sidebar .header.bloglink{font-size:16px;padding:0px 0px 10px 10px;text-align:center;}.frontpage-sidebar .header.blogheader{font-weight:normal;text-align:center;font-size:15px;padding:13px 10px 10px 0px;}.frontpage-sidebar .header a.email{padding:13px 10px 10px 40px;background:url(email-small.png) left center no-repeat;}.frontpage-sidebar .call-us .numbers{padding:0px 0px 0px 38px;background:url(phone-small.png) 2px center no-repeat;font-family:Arial,Helvetica,sans-serif;font-size:11px;line-height:18px;text-align:left;}.frontpage-sidebar .eventum a,.frontpage-sidebar .eventum a:visited{padding:0px 2px 0px 55px;font-size:12px;line-height:18px;text-align:left;background:url(support-small.png) left center no-repeat;display:block;color:#333333 !important;text-decoration:none !important;}.frontpage-sidebar .eventum a:hover{color:#d12907 !important;text-decoration:underline !important;}div.presentation{border-top:1px #e0e0e0 dotted;padding:15px 0px;}div.presentation:first-child{margin-top:0;border:none;}div.presentation table.presentation{border-collapse:collapse;}div.presentation table.presentation td div.bordered-image-screenshot{border:1px #e0e0e0 solid;background:#f8f8f8;padding:5px;}div.presentation table.presentation td.presentations-descr{padding-left:15px;}div.presentation table.presentation td.presentations-descr h4{font-size:18px;font-weight:bold;}.customer-vote{width:412px;text-align:justify;}strong{font-weight:bold;}html,body{height:100%;}#stickywrapper{position:relative;min-height:100%;}* html #stickywrapper{height:100%;}#stickycontent{padding-bottom:102px;}#stickyfooter{position:relative;margin:-97px auto 0 auto;}a.links{font-style:oblique;text-decoration:underline;}span.subpart{font-weight:bold;}div.software-info-container{overflow:hidden;zoom:1;float:right;padding:0px 0px 25px 25px;}table.software-info-container{width:240px;border-collapse:collapse;}table.software-info-container td{border:1px #e0e0e0 solid;padding:10px 10px 10px 10px;}table.software-info-container td.latest{padding:10px 10px 10px 62px;background:url(software-latest.png) 15px center no-repeat;min-height:32px;font-size:16px;line-height:24px;}table.software-info-container td.download a{font-weight:bold;}table.software-info-container td.download{padding:15px 62px 15px 20px;background:url(software-download.png) 195px center no-repeat;min-height:32px;font-size:18px;line-height:24px;}table.software-info-container td.links{text-align:left;padding:4px 10px 4px 20px;}table.software-info-container td.links div{margin:10px 0px;}.inv{display:none;}table.downloadstable{margin-top:20px;border-collapse:collapse;}table.downloadstable th{border:1px #e0e0e0 solid;background:#f8f8f8;padding:7px;font-weight:bold;}table.downloadstable td{border:1px #e0e0e0 solid;padding:7px;}table.downloadstable td.file{width:90%;text-align:left;}table.downloadstable td.modified{width:5%;text-align:center;white-space:nowrap;}table.downloadstable td.size{width:5%;text-align:right;white-space:nowrap;}div.downloads-maintenance-promo,div.downloads-warning{border:1px #e0e0e0 solid;padding:15px 20px 15px 150px;margin:30px 0px;background:url(shield.png) 35px center no-repeat;}div.downloads-maintenance-promo > .close-button{float:right;clear:right;margin-top:-10px;margin-right:-15px;cursor:pointer;cursor:hand;}div.downloads-warning{background:url(warning.png) 35px center no-repeat;}div.downloads-version{border-top:1px #e0e0e0 solid;margin-top:-10px;padding-top:10px;text-align:right;font-size:14px;line-height:14px;font-weight:bold;}div.downloads-anchors{font-size:12px;line-height:15px;margin:20px 0px;}div.downloads-backtotop{font-size:12px;line-height:15px;padding-top:8px;}.downloadsignupdialog .ui-dialog-titlebar{display:none;}#downloadsignup h2{font-family:Arial,Helvetica,sans-serif;font-size:22px;line-height:22px;margin:10px 0px 20px 0px;color:#d12907;}#downloadsignup .intro{margin:10px 0px 15px 0px;}#downloadsignup .form .field{overflow:hidden;zoom:1;margin:10px 0px;}#downloadsignup .form .field .label{overflow:hidden;zoom:1;width:150px;float:left;padding-top:5px;}#downloadsignup .form .field .element{overflow:hidden;zoom:1;width:410px;float:left;}#downloadsignup .form .field .element input,#downloadsignup .form .field .element select{width:400px;border:1px #cccccc solid;padding:3px;outline:none;}#downloadsignup .form .field .element input:focus,#downloadsignup .form .field .element select:focus{border:1px #333333 solid;background:#f8f8f8;outline:none;}#downloadsignup .form .field .radiolist{overflow:hidden;zoom:1;display:block;padding:0;margin:0;}#downloadsignup .form .field table.radiolist{width:100%;}#downloadsignup .form .field .radiolist td{width:25%;}#downloadsignup .form .field div.radiolist label{display:block;min-width:55px;float:left;zoom:1;padding:8px 10px 2px 24px !important;text-indent:-24px;overflow:auto;}#downloadsignup .form .field table.radiolist label{padding:8px 15px 2px 0px !important;zoom:1;display:block;}#downloadsignup .form .field .radiolist label input{margin:0px 7px 0px 3px !important;}.schedule td{padding:3px;border:1px solid #eeeeee;padding-left:10px;font-size:16px;}.tdmini{font-weight:bold;font-size:10px !important;}.tdbreak{background-color:#ffeeee;text-align:center;}.trhead td{background-color:#d12907;color:#ffffff;font-weight:bold;}.speaker{font-size:10px;}table.left-headers th{font-weight:bold;text-align:right;padding:5px 12px;vertical-align:top;border-right:1px solid black;}table.left-headers td{padding:5px 12px;}.training-list tr th{font-weight:bold;}.training-list tr td{padding-right:15px;}a.interwiki{background:transparent url(/docs/wiki/lib/images/interwiki.png) 0px 1px no-repeat;padding-left:16px;}a.iw_wp{background-image:url(/docs/wiki/lib/images/interwiki/wp.gif)}a.iw_wpfr{background-image:url(/docs/wiki/lib/images/interwiki/wpfr.gif)}a.iw_wpde{background-image:url(/docs/wiki/lib/images/interwiki/wpde.gif)}a.iw_wpes{background-image:url(/docs/wiki/lib/images/interwiki/wpes.gif)}a.iw_wppl{background-image:url(/docs/wiki/lib/images/interwiki/wppl.gif)}a.iw_wpjp{background-image:url(/docs/wiki/lib/images/interwiki/wpjp.gif)}a.iw_wpmeta{background-image:url(/docs/wiki/lib/images/interwiki/wpmeta.gif)}a.iw_doku{background-image:url(/docs/wiki/lib/images/interwiki/doku.gif)}a.iw_dokubug{background-image:url(/docs/wiki/lib/images/interwiki/dokubug.gif)}a.iw_amazon{background-image:url(/docs/wiki/lib/images/interwiki/amazon.gif)}a.iw_amazon_de{background-image:url(/docs/wiki/lib/images/interwiki/amazon.de.gif)}a.iw_amazon_uk{background-image:url(/docs/wiki/lib/images/interwiki/amazon.uk.gif)}a.iw_phpfn{background-image:url(/docs/wiki/lib/images/interwiki/phpfn.gif)}a.iw_coral{background-image:url(/docs/wiki/lib/images/interwiki/coral.gif)}a.iw_sb{background-image:url(/docs/wiki/lib/images/interwiki/sb.gif)}a.iw_google{background-image:url(/docs/wiki/lib/images/interwiki/google.gif)}a.iw_meatball{background-image:url(/docs/wiki/lib/images/interwiki/meatball.gif)}a.iw_wiki{background-image:url(/docs/wiki/lib/images/interwiki/wiki.gif)}a.mediafile{background:transparent url(/docs/wiki/lib/images/fileicons/file.png) 0px 1px no-repeat;padding-left:18px;padding-bottom:1px;}a.mf_txt{background-image:url(/docs/wiki/lib/images/fileicons/txt.png)}a.mf_sxi{background-image:url(/docs/wiki/lib/images/fileicons/sxi.png)}a.mf_tgz{background-image:url(/docs/wiki/lib/images/fileicons/tgz.png)}a.mf_wav{background-image:url(/docs/wiki/lib/images/fileicons/wav.png)}a.mf_jpg{background-image:url(/docs/wiki/lib/images/fileicons/jpg.png)}a.mf_sxd{background-image:url(/docs/wiki/lib/images/fileicons/sxd.png)}a.mf_js{background-image:url(/docs/wiki/lib/images/fileicons/js.png)}a.mf_ps{background-image:url(/docs/wiki/lib/images/fileicons/ps.png)}a.mf_conf{background-image:url(/docs/wiki/lib/images/fileicons/conf.png)}a.mf_swf{background-image:url(/docs/wiki/lib/images/fileicons/swf.png)}a.mf_xml{background-image:url(/docs/wiki/lib/images/fileicons/xml.png)}a.mf_py{background-image:url(/docs/wiki/lib/images/fileicons/py.png)}a.mf_cpp{background-image:url(/docs/wiki/lib/images/fileicons/cpp.png)}a.mf_css{background-image:url(/docs/wiki/lib/images/fileicons/css.png)}a.mf_jpeg{background-image:url(/docs/wiki/lib/images/fileicons/jpeg.png)}a.mf_odi{background-image:url(/docs/wiki/lib/images/fileicons/odi.png)}a.mf_pptx{background-image:url(/docs/wiki/lib/images/fileicons/pptx.png)}a.mf_doc{background-image:url(/docs/wiki/lib/images/fileicons/doc.png)}a.mf_bz2{background-image:url(/docs/wiki/lib/images/fileicons/bz2.png)}a.mf_png{background-image:url(/docs/wiki/lib/images/fileicons/png.png)}a.mf_ogg{background-image:url(/docs/wiki/lib/images/fileicons/ogg.png)}a.mf_xls{background-image:url(/docs/wiki/lib/images/fileicons/xls.png)}a.mf_tar{background-image:url(/docs/wiki/lib/images/fileicons/tar.png)}a.mf_pl{background-image:url(/docs/wiki/lib/images/fileicons/pl.png)}a.mf_mp3{background-image:url(/docs/wiki/lib/images/fileicons/mp3.png)}a.mf_pdf{background-image:url(/docs/wiki/lib/images/fileicons/pdf.png)}a.mf_audio{background-image:url(/docs/wiki/lib/images/fileicons/audio.png)}a.mf_rtf{background-image:url(/docs/wiki/lib/images/fileicons/rtf.png)}a.mf_java{background-image:url(/docs/wiki/lib/images/fileicons/java.png)}a.mf_cs{background-image:url(/docs/wiki/lib/images/fileicons/cs.png)}a.mf_odt{background-image:url(/docs/wiki/lib/images/fileicons/odt.png)}a.mf_c{background-image:url(/docs/wiki/lib/images/fileicons/c.png)}a.mf_rpm{background-image:url(/docs/wiki/lib/images/fileicons/rpm.png)}a.mf_docx{background-image:url(/docs/wiki/lib/images/fileicons/docx.png)}a.mf_ppt{background-image:url(/docs/wiki/lib/images/fileicons/ppt.png)}a.mf_odp{background-image:url(/docs/wiki/lib/images/fileicons/odp.png)}a.mf_html{background-image:url(/docs/wiki/lib/images/fileicons/html.png)}a.mf_gz{background-image:url(/docs/wiki/lib/images/fileicons/gz.png)}a.mf_zip{background-image:url(/docs/wiki/lib/images/fileicons/zip.png)}a.mf_gif{background-image:url(/docs/wiki/lib/images/fileicons/gif.png)}a.mf_htm{background-image:url(/docs/wiki/lib/images/fileicons/htm.png)}a.mf_sql{background-image:url(/docs/wiki/lib/images/fileicons/sql.png)}a.mf_rar{background-image:url(/docs/wiki/lib/images/fileicons/rar.png)}a.mf_rb{background-image:url(/docs/wiki/lib/images/fileicons/rb.png)}a.mf_csv{background-image:url(/docs/wiki/lib/images/fileicons/csv.png)}a.mf_odc{background-image:url(/docs/wiki/lib/images/fileicons/odc.png)}a.mf_odf{background-image:url(/docs/wiki/lib/images/fileicons/odf.png)}a.mf_deb{background-image:url(/docs/wiki/lib/images/fileicons/deb.png)}a.mf_ods{background-image:url(/docs/wiki/lib/images/fileicons/ods.png)}a.mf_xlsx{background-image:url(/docs/wiki/lib/images/fileicons/xlsx.png)}a.mf_lua{background-image:url(/docs/wiki/lib/images/fileicons/lua.png)}a.mf_sxc{background-image:url(/docs/wiki/lib/images/fileicons/sxc.png)}a.mf_odg{background-image:url(/docs/wiki/lib/images/fileicons/odg.png)}a.mf_7z{background-image:url(/docs/wiki/lib/images/fileicons/7z.png)}a.mf_sxw{background-image:url(/docs/wiki/lib/images/fileicons/sxw.png)}a.mf_php{background-image:url(/docs/wiki/lib/images/fileicons/php.png)}div.clearer{clear:both;line-height:0;height:0;overflow:hidden;}div.no{display:inline;margin:0;padding:0;}.hidden{display:none;}div.error{background:#fcc url(/docs/wiki/lib/styles/../images/error.png) 0.5em 0px no-repeat;color:#000;border-bottom:1px solid #faa;font-size:90%;margin:0;padding-left:3em;overflow:hidden;}div.info{background:#ccf url(/docs/wiki/lib/styles/../images/info.png) 0.5em 0px no-repeat;color:#000;border-bottom:1px solid #aaf;font-size:90%;margin:0;padding-left:3em;overflow:hidden;}div.success{background:#cfc url(/docs/wiki/lib/styles/../images/success.png) 0.5em 0px no-repeat;color:#000;border-bottom:1px solid #afa;font-size:90%;margin:0;padding-left:3em;overflow:hidden;}div.notify{background:#ffc url(/docs/wiki/lib/styles/../images/notify.png) 0.5em 0px no-repeat;color:#000;border-bottom:1px solid #ffa;font-size:90%;margin:0;padding-left:3em;overflow:hidden;}.medialeft{float:left;}.mediaright{float:right;}.mediacenter{display:block;margin-left:auto;margin-right:auto;}.leftalign{text-align:left;}.centeralign{text-align:center;}.rightalign{text-align:right;}em.u{font-style:normal;text-decoration:underline;}em em.u{font-style:italic;}.code .br0{color:#6c6;}.code .co0{color:#808080;font-style:italic;}.code .co1{color:#808080;font-style:italic;}.code .co2{color:#808080;font-style:italic;}.code .co3{color:#808080;}.code .coMULTI{color:#808080;font-style:italic;}.code .es0{color:#009;font-weight:bold;}.code .kw1{color:#b1b100;}.code .kw2{color:#000;font-weight:bold;}.code .kw3{color:#006;}.code .kw4{color:#933;}.code .kw5{color:#00f;}.code .me1{color:#060;}.code .me2{color:#060;}.code .nu0{color:#c6c;}.code .re0{color:#00f;}.code .re1{color:#00f;}.code .re2{color:#00f;}.code .re3{color:#f33;font-weight:bold;}.code .re4{color:#099;}.code .st0{color:#f00;}.code .sy0{color:#6c6;}div#acl_manager div#acl__tree{font-size:90%;width:25%;height:300px;float:left;overflow:auto;border:1px solid #8cacbb;text-align:left;}div#acl_manager div#acl__tree a.cur{background-color:#ff9;font-weight:bold;}div#acl_manager div#acl__tree ul{list-style-type:none;margin:0;padding:0;}div#acl_manager div#acl__tree li{padding-left:1em;}div#acl_manager div#acl__tree ul img{margin-right:0.25em;cursor:pointer;}div#acl_manager div#acl__detail{width:73%;height:300px;float:right;overflow:auto;}div#acl_manager div#acl__detail fieldset{width:90%;}div#acl_manager div#acl__detail div#acl__user{border:1px solid #8cacbb;padding:0.5em;margin-bottom:0.6em;}div#acl_manager table.inline{width:100%;margin:0;}div#acl_manager .aclgroup{background:transparent url(/docs/wiki/lib/plugins/acl/pix/group.png) 0px 1px no-repeat;padding:1px 0px 1px 18px;}div#acl_manager .acluser{background:transparent url(/docs/wiki/lib/plugins/acl/pix/user.png) 0px 1px no-repeat;padding:1px 0px 1px 18px;}div#acl_manager .aclpage{background:transparent url(/docs/wiki/lib/plugins/acl/pix/page.png) 0px 1px no-repeat;padding:1px 0px 1px 18px;}div#acl_manager .aclns{background:transparent url(/docs/wiki/lib/plugins/acl/pix/ns.png) 0px 1px no-repeat;padding:1px 0px 1px 18px;}div#acl_manager label.disabled{color:#666!important;}#acl_manager label{text-align:left;font-weight:normal;display:inline;}#acl_manager table{margin-left:10%;width:80%;}#acl_manager table tr{background-color:inherit;}#acl_manager table tr:hover{background-color:#dee7ec;}div.toolbar #tool__bar_table button.selected{background:#fff url(/docs/wiki/lib/plugins/edittable/images/buttonshadow_toggled.png) repeat-x bottom;}div.toolbar #tool__bar_table button.disabled{background:#fff url(/docs/wiki/lib/plugins/edittable/images/buttonshadow_toggled2.png) repeat-x bottom;opacity:0.4;}div.toolbar #tool__bar_table button.separator{margin-left:0.5em;}div.toolbar #tool__bar_table{margin-bottom:0.5em;}#dw__editform #edit__wrap{margin-top:1.5em;overflow:auto;border:1px solid #8cacbb;}div.dokuwiki table.edit{margin:-1px;}div.dokuwiki table.edit th,div.dokuwiki table.edit td{min-width:5em;}div.dokuwiki table.edit input{border:none;background:transparent;font:inherit;width:100%;}html>body div.dokuwiki table.edit th,html>body div.dokuwiki table.edit td{background-image:url(/docs/wiki/lib/plugins/edittable/images/inputshadow.png);background-repeat:repeat-x;background-position:top;}div.dokuwiki table.edit td.handle{color:#666;background-color:#f5f5f5;padding:0;vertical-align:bottom;position:relative;}div.dokuwiki table.edit td.rowhandle{width:3em;}div.dokuwiki table.edit td.handle{cursor:move;}div.dokuwiki table.edit td.curhandle{background-color:#dee7ec;}div.dokuwiki table.edit td.disabledhandle{background-image:none;background-color:#c0c0c0;cursor:no-drop;}html>body div.dokuwiki table.edit td.handle{background-image:url(/docs/wiki/lib/plugins/edittable/images/buttonshadow.png);background-repeat:repeat-x;background-position:bottom;}#table__dragmarker{display:block;height:100%;width:100%;position:relative;}#table__dragmarker .dragmarker_topright{position:absolute;top:-0.5em;right:0px;}#table__dragmarker .dragmarker_bottomright{position:absolute;top:0.5em;right:0px;}#table__dragmarker .dragmarker_bottomleft{position:absolute;top:0.5em;left:0px;}.handle .handle_dropdown{float:right;margin-top:3px;}.handle .handle_dropdown img{padding:4px 2px 1px;cursor:pointer;}#dw__editform .handle .handle_dropdown div{position:absolute;z-index:25;}#dw__editform .handle .handle_dropdown div ul{background:#fff none repeat scroll 0 0;border:1px solid;list-style-image:none;list-style-position:outside;list-style-type:none;opacity:0.9;padding:0.3em;margin:0;cursor:auto;font-size:0.9em;}#dw__editform .handle .handle_dropdown div ul li{width:100%;text-align:left;}#dw__editform .handle .handle_dropdown div ul li a{width:100%;display:block;cursor:pointer;}#dw__editform .handle .handle_dropdown div ul li a:hover{background:#dee7ec;}div.dokuwiki div.editbutton_table{margin-top:-1em;}div.dokuwiki div.editbutton_table form input.button{float:none;margin-left:0.6em;padding:0 0.3em;background-image:none;border-top:none;border-bottom-right-radius:0.5em;-moz-border-radius-bottomright:0.5em;-webkit-border-bottom-right-radius:0.5em;border-bottom-left-radius:0.5em;-moz-border-radius-bottomleft:0.5em;-webkit-border-bottom-left-radius:0.5em;}div.dokuwiki div.section_highlight table{background-color:#dee7ec;}div.dokuwiki div.table.section_highlight{background-color:transparent !important;}.noteredirect{margin:1em;margin-left:auto;margin-right:auto;width:70% !important;min-height:18px;clear:both;text-align:justify;vertical-align:middle;border-collapse:collapse;padding:7px 10px 5px 32px;background-position:10px 50%;background-repeat:no-repeat;-moz-border-radius:10px;-khtml-border-radius:10px;border-radius:10px;background-color:#B5E0FF;background-image:url(/docs/wiki/lib/plugins/pageredirect/images/important_small.png);}#user__manager tr.disabled{color:#6f6f6f;background:#e4e4e4;}#user__manager tr.user_info{vertical-align:top;}#user__manager div.edit_user{width:46%;float:left;}#user__manager table{margin-bottom:1em;}#user__manager input.button[disabled]{color:#ccc!important;border-color:#ccc!important;}#plugin__manager h2{margin-left:0;}#plugin__manager form{display:block;margin:0;padding:0;}#plugin__manager legend{display:none;}#plugin__manager fieldset{width:auto;}#plugin__manager .button{margin:0;}#plugin__manager p,#plugin__manager label{text-align:left;}#plugin__manager .hidden{display:none;}#plugin__manager .new{background:#dee7ec;}#plugin__manager input[disabled]{color:#ccc;border-color:#ccc;}#plugin__manager .pm_menu,#plugin__manager .pm_info{margin-left:0;text-align:left;}#plugin__manager .pm_menu{float:left;width:48%;}#plugin__manager .pm_info{float:right;width:50%;}#plugin__manager .common fieldset{margin:0;padding:0 0 1.0em 0;text-align:left;border:none;}#plugin__manager .common label{padding:0 0 0.5em 0;}#plugin__manager .common input.edit{width:24em;margin:0.5em;}#plugin__manager .plugins fieldset{color:#000;background:#fff;text-align:right;border-top:none;border-right:none;border-left:none;}#plugin__manager .plugins fieldset.protected{background:#fdd;color:#000;}#plugin__manager .plugins fieldset.disabled{background:#e0e0e0;color:#a8a8a8;}#plugin__manager .plugins .legend{color:#000;background:inherit;display:block;margin:0;padding:0;font-size:1em;line-height:1.4em;font-weight:normal;text-align:left;float:left;padding:0;clear:none;}#plugin__manager .plugins .button{font-size:95%;}#plugin__manager .plugins fieldset.buttons{border:none;}#plugin__manager .plugins fieldset.buttons .button{float:left;}#plugin__manager .pm_info h3{margin-left:0;}#plugin__manager .pm_info dl{margin:1em 0;padding:0;}#plugin__manager .pm_info dt{width:6em;float:left;clear:left;margin:0;padding:0;}#plugin__manager .pm_info dd{margin:0 0 0 7em;padding:0;background:none;}#plugin__manager .plugins .enable{float:left;width:auto;margin-right:0.5em;}.dokuwiki #plugin__captcha_wrapper img{margin:1px;vertical-align:bottom;border:1px solid #8cacbb;}#config__manager div.success,#config__manager div.error,#config__manager div.info{background-position:0.5em;padding:0.5em;text-align:center;}#config__manager fieldset{margin:1em;width:auto;margin-bottom:2em;background-color:#dee7ec;color:#000;padding:0 1em;}#config__manager legend{font-size:1.25em;}#config__manager form{}#config__manager table{margin:1em 0;width:100%;}#config__manager fieldset td{text-align:left;}#config__manager fieldset td.value{width:31em;}#config__manager td.label{padding:0.8em 0 0.6em 1em;vertical-align:top;}#config__manager td.label label{clear:left;display:block;}#config__manager td.label img{padding:0 10px;vertical-align:middle;float:right;}#config__manager td.label span.outkey{font-size:70%;margin-top:-1.7em;margin-left:-1em;display:block;background-color:#fff;color:#666;float:left;padding:0 0.1em;position:relative;z-index:1;}#config__manager td input.edit{width:30em;}#config__manager td .input{width:30.8em;}#config__manager td select.edit{}#config__manager td textarea.edit{width:27.5em;height:4em;}#config__manager tr .input,#config__manager tr input,#config__manager tr textarea,#config__manager tr select{background-color:#fff;color:#000;}#config__manager tr.default .input,#config__manager tr.default input,#config__manager tr.default textarea,#config__manager tr.default select,#config__manager .selectiondefault{background-color:#cdf;color:#000;}#config__manager tr.protected .input,#config__manager tr.protected input,#config__manager tr.protected textarea,#config__manager tr.protected select,#config__manager tr.protected .selection{background-color:#fcc!important;color:#000 !important;}#config__manager td.error{background-color:red;color:#000;}#config__manager .selection{width:14.8em;float:left;margin:0 0.3em 2px 0;}#config__manager .selection label{float:right;width:14em;font-size:90%;}* html #config__manager .selection label{padding-top:2px;}#config__manager .selection input.checkbox{padding-left:0.7em;}#config__manager .other{clear:both;padding-top:0.5em;}#config__manager .other label{padding-left:2px;font-size:90%;}div.noteclassic,div.noteimportant,div.notewarning,div.notetip{margin:2em;margin-left:auto;margin-right:auto;width:70% !important;min-height:40px;clear:both;text-align:justify;vertical-align:middle;border-collapse:collapse;padding:15px 20px 15px 80px;background-position:20px 50%;background-repeat:no-repeat;-moz-border-radius:20px;-khtml-border-radius:20px;border-radius:20px;}div.noteclassic{background-color:#eef;background-image:url(/docs/wiki/lib/plugins/note/images/note.png);}div.noteimportant{background-color:#ffc;background-image:url(/docs/wiki/lib/plugins/note/images/important.png);}div.notewarning{background-color:#fdd;background-image:url(/docs/wiki/lib/plugins/note/images/warning.png);}div.notetip{background-color:#dfd;background-image:url(/docs/wiki/lib/plugins/note/images/tip.png);}.dtree{font-family:Verdana,Geneva,Arial,Helvetica,sans-serif;font-size:11px;color:#000;white-space:nowrap;line-height:normal;}.dtree img{border:0px;vertical-align:top;}.dtree a{color:#090;text-decoration:none;}.dtree a.node,.dtree a.nodeSel a.navSel{white-space:nowrap;padding:1px 2px 1px 2px;}.dtree a.nodeSel{background-color:#dee7ec;}.dtree a.navSel{background-color:#ff9;}.indexmenu_nojs{display:block;}div.li a.indexmenu_idx{color:#f30 !important;text-decoration:none !important;font-weight:bold;}div.li a.indexmenu_idx_head{font-weight:bold;}div.dokuwiki div.indexmenu_list_themes{clear:both;border-top:2px solid #8cacbb;padding-left:1em;}.dtree a.nodeFdUrl:hover,.dtree a.nodeSel:hover,a.navSel:hover,.dtree a.nodeUrl:hover{color:#090;text-decoration:underline;background-color:#dee7ec;}.dtree a.node:hover{text-decoration:none;}.dtree .indexmenu_tocbullet{position:absolute;background:transparent url(/docs/wiki/lib/plugins/indexmenu/images/toc_bullet.gif) no-repeat scroll;vertical-align:middle;width:11px;height:11px;}.dtree .indexmenu_larrow{position:absolute;filter:alpha(opacity=60);-moz-opacity:.60;opacity:.60;background:transparent url(/docs/wiki/lib/plugins/indexmenu/images/larrow.gif) repeat-y scroll;padding-left:22px;z-index:100;}.indexmenu_toc{font-size:80%;line-height:1.2em;white-space:normal;overflow:hidden;width:200px !important;z-index:100 !important;word-wrap:break-word;}.indexmenu_toc .indexmenu_toc_inside{border:1px solid #8cacbb;background-color:#fff;text-align:left;padding:0.5em 0 0.7em 0;max-height:300px;height:expression( this.scrollHeight > 300 ? "300px":"auto" );overflow:auto;}.dtree .indexmenu_rarrow{position:absolute;background:white url(/docs/wiki/lib/plugins/indexmenu/images/rarrow.gif) no-repeat scroll;width:11px;height:15px;}.indexmenu_rmenu{position:absolute;z-index:100;background-color:#fff;border:1px solid black;font-size:80%;line-height:100%;padding-bottom:5px;}.indexmenu_rmenuhead{background:#CFC url(/docs/wiki/lib/plugins/indexmenu/images/close.gif) no-repeat scroll;border-bottom:1px solid #000;color:#000;font-size:90%;margin:0pt;text-align:left;padding:1px 15px;vertical-align:middle;overflow:hidden;width:80px;}.indexmenu_rmenu ul,.indexmenu_rmenu li{list-style-type:none !important;list-style-image:none !important;color:#000 !important;margin:2px !important;text-align:center;}.indexmenu_rmenu a:hover{background-color:#000 !important;color:#fff !important;}.indexmenu_opts{font-size:80%;}.dtree .emptynode{background:transparent url(/docs/wiki/lib/plugins/indexmenu/images/empty.gif) no-repeat scroll;display:inline;padding:1px 8px;width:16px;height:16px;vertical-align:top;zoom:1;}div.dokuwiki .header{padding:3px 0 0 2px;}div.dokuwiki .pagename{float:left;font-size:200%;font-weight:bolder;color:#dee7ec;text-align:left;vertical-align:middle;}div.dokuwiki .pagename a{color:#436976 !important;text-decoration:none !important;}div.dokuwiki .logo{float:right;font-size:220%;font-weight:bolder;text-align:right;vertical-align:middle;}div.dokuwiki .logo a{color:#dee7ec !important;text-decoration:none !important;font-variant:small-caps;letter-spacing:2pt;}div.dokuwiki .bar{border:1px #e0e0e0 solid;background:#f8f8f8;padding:10px;clear:both;}div.dokuwiki .bar-left{float:left;}div.dokuwiki .bar-right{float:right;text-align:right;}div.dokuwiki #bar__bottom{margin-bottom:3px;}div.dokuwiki .bar-tools{display:none;border-left:1px #e0e0e0 solid;border-right:1px #e0e0e0 solid;border-bottom:1px #e0e0e0 solid;background:#f8f8f8;padding:10px;clear:both;}div.dokuwiki div.meta{clear:both;margin:20px 0px 0px 0px;color:#638c9c;font-size:70%;}div.dokuwiki div.meta div.user{float:left;}div.dokuwiki div.meta div.doc{text-align:right;}*{padding:0;margin:0;}body{font:80% "Lucida Grande",Verdana,Lucida,Helvetica,Arial,sans-serif;background-color:#fff;color:#000;}div.dokuwiki div.page{text-align:justify;}div.dokuwiki table{font-size:100%;}div.dokuwiki tr,div.dokuwiki td,div.dokuwiki th{}div.dokuwiki img{border:0;}div.dokuwiki p,div.dokuwiki blockquote,div.dokuwiki table,div.dokuwiki pre{margin:0 0 1.0em 0;}div.dokuwiki hr{border:0px;border-top:1px solid #8cacbb;text-align:center;height:0px;}div.dokuwiki div.nothing{text-align:center;margin:2em;}div.dokuwiki form{border:none;display:inline;}div.dokuwiki label.block{display:block;text-align:right;font-weight:bold;}div.dokuwiki label.simple{display:block;text-align:left;font-weight:normal;}div.dokuwiki label.block input.edit{width:50%;}div.dokuwiki fieldset{width:300px;text-align:center;border:1px solid #8cacbb;padding:0.5em;margin:auto;}div.dokuwiki textarea.edit{font-family:monospace;font-size:14px;color:#000;background-color:#fff;border:1px solid #8cacbb;padding:0.3em 0 0 0.3em;width:100%;}html>body div.dokuwiki textarea.edit{background:#fff url(/docs/wiki/lib/tpl/default/images/inputshadow.png) repeat-x top;}div.dokuwiki input.edit,div.dokuwiki select.edit{font-size:100%;border:1px solid #8cacbb;color:#000;background-color:#fff;vertical-align:middle;margin:1px;padding:0.20em 0.3em;display:inline;}html>body div.dokuwiki input.edit,html>body div.dokuwiki select.edit{background:#fff url(/docs/wiki/lib/tpl/default/images/inputshadow.png) repeat-x top;}div.dokuwiki select.edit{padding:0.1em 0;}div.dokuwiki input.missing{font-size:100%;border:1px solid #8cacbb;color:#000;background-color:#fcc;vertical-align:middle;margin:1px;padding:0.20em 0.3em;display:inline;}div.dokuwiki textarea.edit[disabled],div.dokuwiki textarea.edit[readonly],div.dokuwiki input.edit[disabled],div.dokuwiki input.edit[readonly],div.dokuwiki input.button[disabled],div.dokuwiki select.edit[disabled]{background-color:#f5f5f5!important;color:#666!important;}div.dokuwiki div.toolbar,div.dokuwiki div#wiki__editbar{margin:2px 0;text-align:left;}div.dokuwiki div#size__ctl{float:right;width:60px;height:2.7em;}div.dokuwiki #size__ctl img{cursor:pointer;}div.dokuwiki div#wiki__editbar div.editButtons{float:left;padding:0 1.0em 0.7em 0;}div.dokuwiki div#wiki__editbar div.summary{float:left;}div.dokuwiki .nowrap{white-space:nowrap;}div.dokuwiki div#draft__status{float:right;color:#638c9c;}div.dokuwiki div.license{padding:0.5em;font-size:90%;text-align:center;}div.dokuwiki form#dw__editform div.license{clear:left;font-size:90%;}div.dokuwiki input.button,div.dokuwiki button.button{border:1px solid #8cacbb;color:#000;background-color:#fff;vertical-align:middle;text-decoration:none;font-size:100%;cursor:pointer;margin:1px;padding:0.125em 0.4em;}html>body div.dokuwiki input.button,html>body div.dokuwiki button.button{background:#fff url(/docs/wiki/lib/tpl/default/images/buttonshadow.png) repeat-x bottom;}* html div.dokuwiki input.button,* html div.dokuwiki button.button{height:1.8em;}div.dokuwiki div.secedit input.button{border:1px solid #8cacbb;color:#000;background-color:#fff;vertical-align:middle;text-decoration:none;margin:0;padding:0;font-size:10px;cursor:pointer;float:right;display:inline;}div.dokuwiki div.pagenav{margin:1em 0 0 0;}div.dokuwiki div.pagenav-prev{text-align:right;float:left;width:49%}div.dokuwiki div.pagenav-next{text-align:left;float:right;width:49%}div.dokuwiki a:link,div.dokuwiki a:visited{color:#436976;text-decoration:none;}div.dokuwiki a:hover,div.dokuwiki a:active{color:#000;text-decoration:underline;}div.dokuwiki h1 a{text-decoration:none !important;}div.dokuwiki h2 a,div.dokuwiki h3 a,div.dokuwiki h4 a,div.dokuwiki h5 a,div.dokuwiki a.nolink{color:#000 !important;text-decoration:none !important;}div.dokuwiki a.interwiki{}div.dokuwiki a.media{}div.dokuwiki a.mail{background:transparent url(/docs/wiki/lib/tpl/default/images/mail_icon.gif) 0px 1px no-repeat;padding:1px 0px 1px 16px;}div.dokuwiki a.wikilink2{text-decoration:none !important;border-bottom:dashed 1px #f30 !important;}div.dokuwiki div.preview{background-color:#f5f5f5;margin:0 0 0 2em;padding:4px;border:1px dashed #000;}div.dokuwiki div.breadcrumbs{background:url(http://s0.percona.com/ui-tab-bg.png) -14px left repeat-x;color:#999;font-size:11px;font-style:italic;padding:7px 0 15px 12px;}div.dokuwiki div.breadcrumbs a,div.dokuwiki div.breadcrumbs a:visited{color:#999 !important;border-color:#999 !important;}div.dokuwiki div.breadcrumbs a:hover{color:#d12907 !important;border-color:#d12907 !important;}div.dokuwiki span.user{color:#ccc;font-size:90%;}div.dokuwiki li.minor{color:#666;font-style:italic;}div.dokuwiki img.media{margin:3px;}div.dokuwiki img.medialeft{border:0;float:left;margin:0 1.5em 0 0;}div.dokuwiki img.mediaright{border:0;float:right;margin:0 0 0 1.5em;}div.dokuwiki img.mediacenter{border:0;display:block;margin:0 auto;}div.dokuwiki img.middle{vertical-align:middle;}div.dokuwiki acronym{cursor:help;border-bottom:1px dotted #000;}div.dokuwiki li.open{list-style-image:url(/docs/wiki/lib/tpl/default/images/open.gif);}div.dokuwiki li.closed{list-style-image:url(/docs/wiki/lib/tpl/default/images/closed.gif);}div.dokuwiki blockquote{border-left:2px solid #8cacbb;padding-left:3px;}div.dokuwiki pre{font-size:80%;padding:10px;border:1px dashed #8cacbb;color:#000;overflow:auto;}div.dokuwiki pre.pre{background-color:#f7f9fa;}div.dokuwiki pre.code{background-color:#f7f9fa;}div.dokuwiki pre.file{background-color:#dee7ec;}div.dokuwiki dl.file,div.dokuwiki dl.code{margin-top:2em;margin-bottom:2.5em;}div.dokuwiki dl.file dt,div.dokuwiki dl.code dt{border:1px dashed #8cacbb;display:inline;padding:0.1em 1em;margin-left:2em;}div.dokuwiki dl.code dt a,div.dokuwiki dl.file dt a{color:#000;}div.dokuwiki dl.code dt{background-color:#f7f9fa;border-bottom:1px solid #f7f9fa;}div.dokuwiki dl.file dt{background-color:#dee7ec;border-bottom:1px solid #dee7ec;}div.dokuwiki table.inline{background-color:#fff;border-spacing:0px;border-collapse:collapse;}div.dokuwiki table.inline th{padding:3px;border:1px solid #8cacbb;background-color:#dee7ec;}div.dokuwiki table.inline td{padding:3px;border:1px solid #8cacbb;}#toc{width:258px;font-size:12px;line-height:16px;clear:both;border:1px #e0e0e0 solid;background:#fff url(http://s1.percona.com/ui-tab-bg.png) top left repeat-x;}#toc div.tocheader{text-align:left;font-weight:bold;padding:7px 10px;margin-bottom:2px;font-size:16px;}#toc div.tocheader a,#toc div.tocheader a:visited{color:#000 !important;text-decoration:none !important;}#toc div.tocheader a:hover{color:#d12907 !important;text-decoration:none !important;}#toc span.toc_open,#toc span.toc_close{float:right;display:block;margin:0.4em 3px 0 0;}#toc span.toc_open span,#toc span.toc_close span{display:none;}#toc span.toc_open{margin-top:0.4em;border-top:0.4em solid #000;}#toc span.toc_close{margin-top:0;border-bottom:0.4em solid #000;}#toc #toc__inside{text-align:left;padding:1px 15px 15px 13px;}#toc ul.toc{list-style-type:none;padding-left:0px !important;margin:0;}#toc ul.toc ul{padding-left:15px !important;}#toc ul.toc li{margin:5px 0px !important;}#toc ul.toc li.clear{padding-left:0;}#toc a.toc:link,#toc a.toc:visited{color:#d12907;text-decoration:underline;}#toc a.toc:hover,#toc a.toc:active{color:#712000;text-decoration:underline;}div.dokuwiki table.diff{background-color:#fff;width:100%;}div.dokuwiki td.diff-blockheader{font-weight:bold;}div.dokuwiki table.diff th{border-bottom:1px solid #8cacbb;font-size:110%;width:50%;font-weight:normal;text-align:left;}div.dokuwiki table.diff th a{font-weight:bold;}div.dokuwiki table.diff th span.user{color:#000;font-size:80%;}div.dokuwiki table.diff th span.sum{font-size:80%;font-weight:bold;}div.dokuwiki table.diff th.minor{font-style:italic;}div.dokuwiki table.diff td{font-family:monospace;font-size:100%;}div.dokuwiki td.diff-addedline{background-color:#dfd;}div.dokuwiki td.diff-deletedline{background-color:#ffb;}div.dokuwiki td.diff-context{background-color:#f5f5f5;}div.dokuwiki table.diff td.diff-addedline strong,div.dokuwiki table.diff td.diff-deletedline strong{color:red;}div.dokuwiki div.footnotes{clear:both;border-top:1px solid #8cacbb;padding-left:1em;margin-top:1em;}div.dokuwiki div.fn{font-size:90%;}div.dokuwiki a.fn_bot{font-weight:bold;}div.insitu-footnote{font-size:80%;line-height:1.2em;border:1px solid #8cacbb;background-color:#f7f9fa;text-align:left;padding:4px;max-width:40%;}* html .insitu-footnote pre.code,* html .insitu-footnote pre.file{padding-bottom:18px;}div.dokuwiki .search_result{margin-bottom:6px;padding:0 10px 0 30px;}div.dokuwiki .search_snippet{color:#ccc;font-size:12px;margin-left:20px;}div.dokuwiki .search_sep{color:#000;}div.dokuwiki .search_hit{color:#000;background-color:#ff9;}div.dokuwiki strong.search_hit{font-weight:normal;}div.dokuwiki div.search_quickresult{margin:0 0 15px 30px;padding:0 10px 10px 0;border-bottom:1px dashed #8cacbb;}div.dokuwiki div.search_quickresult h3{margin:0 0 1.0em 0;font-size:1em;font-weight:bold;}div.dokuwiki ul.search_quickhits{margin:0 0 0.5em 1.0em;}div.dokuwiki ul.search_quickhits li{margin:0 1.0em 0 1.0em;float:left;width:30%;}div.dokuwiki div.section_highlight{background-color:#dee7ec;}div.footerinc{text-align:center;}.footerinc a img{opacity:0.5;border:0;}.footerinc a:hover img{opacity:1;}div.dokuwiki div.ajax_qsearch{position:absolute;right:237px;;width:200px;opacity:0.9;display:none;font-size:80%;line-height:1.2em;border:1px solid #8cacbb;background-color:#f7f9fa;text-align:left;padding:4px;}button.toolbutton{background-color:#fff;padding:0px;margin:0 1px 0 0;border:1px solid #8cacbb;cursor:pointer;}html>body button.toolbutton{background:#fff url(/docs/wiki/lib/tpl/default/images/buttonshadow.png) repeat-x bottom;}div.picker{width:250px;border:1px solid #8cacbb;background-color:#dee7ec;}div.pk_hl{width:125px;}button.pickerbutton{padding:0px;margin:0 1px 1px 0;border:0;background-color:transparent;font-size:80%;cursor:pointer;}div.dokuwiki div.img_big{float:left;margin-right:0.5em;}div.dokuwiki dl.img_tags dt{font-weight:bold;background-color:#dee7ec;}div.dokuwiki dl.img_tags dd{background-color:#f5f5f5;}div.dokuwiki div.imagemeta{color:#666;font-size:70%;line-height:95%;}div.dokuwiki div.imagemeta img.thumb{float:left;margin-right:0.1em;}div.dokuwiki h4{border-top:none !important;margin:20px 0px 20px 0px !important;}#media__manager{height:100%;overflow:hidden;}#media__left{width:30%;border-right:solid 1px #8cacbb;height:100%;overflow:auto;position:absolute;left:0;}#media__right{width:69.7%;height:100%;overflow:auto;position:absolute;right:0;}#media__manager h1{margin:0;padding:0;margin-bottom:0.5em;}#media__tree img{float:left;padding:0.5em 0.3em 0 0;}#media__tree ul{list-style-type:none;list-style-image:none;margin-left:1.5em;}#media__tree li{clear:left;list-style-type:none;list-style-image:none;}*+html #media__tree li,* html #media__tree li{border:1px solid #fff;}#media__opts{padding-left:1em;margin-bottom:0.5em;}#media__opts input{float:left;display:block;margin-top:4px;position:absolute;}*+html #media__opts input,* html #media__opts input{position:static;}#media__opts label{display:block;float:left;margin-left:20px;margin-bottom:4px;}*+html #media__opts label,* html #media__opts label{margin-left:10px;}#media__opts br{clear:left;}#media__content img.load{margin:1em auto;}#media__content #scroll__here{border:1px dashed #8cacbb;}#media__content .odd{background-color:#f7f9fa;padding:0.4em;}#media__content .even{padding:0.4em;}#media__content a.mediafile{margin-right:1.5em;font-weight:bold;}#media__content div.detail{padding:0.3em 0 0.3em 2em;}#media__content div.detail div.thumb{float:left;width:130px;text-align:center;margin-right:0.4em;}#media__content img.btn{vertical-align:text-bottom;}#media__content div.example{color:#666;margin-left:1em;}#media__content div.upload{font-size:90%;padding:0 0.5em 0.5em 0.5em;}#media__content form#dw__upload,#media__content div#dw__flashupload{display:block;border-bottom:solid 1px #8cacbb;padding:0 0.5em 1em 0.5em;}#media__content form#dw__upload fieldset{padding:0;margin:0;border:none;width:auto;}#media__content form#dw__upload p{text-align:left;padding:0.25em 0;margin:0;line-height:1.0em;}#media__content form#dw__upload label.check{float:none;width:auto;margin-left:11.5em;}#media__content form.meta{display:block;padding:0 0 1em 0;}#media__content form.meta label{display:block;width:25%;float:left;font-weight:bold;margin-left:1em;clear:left;}#media__content form.meta .edit{font:100% "Lucida Grande",Verdana,Lucida,Helvetica,Arial,sans-serif;float:left;width:70%;padding-right:0;padding-left:0.2em;margin:2px;}#media__content form.meta textarea.edit{height:8em;}#media__content form.meta div.metafield{clear:left;}#media__content form.meta div.buttons{clear:left;margin-left:20%;padding-left:1em;}#media__popup{background-color:#fff;display:none;border:1px solid #8cacbb;position:absolute;width:270px;}#media__popup h1{text-align:center;font-weight:normal;background-color:#dee7ec;height:16px;margin-bottom:5px;font-size:12px;border-bottom:0;}#media__popup p{display:block;line-height:14pt;margin:0.5em;}#media_nolink{padding:4px 0;}#media__popup label{float:left;width:9em;}#media__popup .button{margin-left:auto;margin-right:auto;}#media__popup .btnlbl{text-align:center;}#media__popup .btnlbl input{margin:0 1em;}#media__closeimg{float:right;}#media__linkopts label,#media__nolnk{width:80px;float:left;margin-left:10px;}#media__linkopts label{line-height:20px;}#media__nolnk,#media__linkopts label.long{margin-bottom:8px;line-height:12px;}#media__linkopts label.long{width:150px;float:none;}#media__linkopts br{clear:both;}#media__linkopts select{width:60px;margin-left:10px;}#media__linkopts input.edit{width:50px;margin-left:10px;}#media__linkopts #media__title{width:150px;}#admin__version{clear:left;float:right;color:#666;}.dokuwiki ul.admin_tasks{font-size:115%;float:left;width:40%;list-style-type:none;}.dokuwiki ul.admin_tasks li{line-height:22px;padding-left:35px;margin:1em 0;background:transparent none no-repeat scroll 0 0;text-align:left;}.dokuwiki ul.admin_tasks li div.li{font-weight:bold;}.dokuwiki ul.admin_tasks li.admin_acl{background-image:url(/docs/wiki/lib/tpl/default/../../images/admin/acl.png);}.dokuwiki ul.admin_tasks li.admin_usermanager{background-image:url(/docs/wiki/lib/tpl/default/../../images/admin/usermanager.png);}.dokuwiki ul.admin_tasks li.admin_plugin{background-image:url(/docs/wiki/lib/tpl/default/../../images/admin/plugin.png);}.dokuwiki ul.admin_tasks li.admin_config{background-image:url(/docs/wiki/lib/tpl/default/../../images/admin/config.png);}.dokuwiki ul.admin_tasks li.admin_revert{background-image:url(/docs/wiki/lib/tpl/default/../../images/admin/revert.png);}.dokuwiki ul.admin_tasks li.admin_popularity{background-image:url(/docs/wiki/lib/tpl/default/../../images/admin/popularity.png);}#link__wiz{position:absolute;display:block;z-index:99;width:300px;height:250px;padding:0;margin:0;overflow:hidden;border:1px solid #8cacbb;background-color:#f5f5f5;text-align:center;}#link__wiz_header{background-color:#dee7ec;height:16px;margin-bottom:5px;}#link__wiz_close{cursor:pointer;margin:0;}#link__wiz_result{background-color:#fff;width:293px;height:193px;overflow:auto;border:1px solid #8cacbb;margin:3px auto;text-align:left;}#link__wiz_result div.type_u{padding:3px 3px 3px 22px;background:transparent url(/docs/wiki/lib/tpl/default/../../images/up.png) 3px 3px no-repeat;}#link__wiz_result div.type_f{padding:3px 3px 3px 22px;background:transparent url(/docs/wiki/lib/tpl/default/../../images/page.png) 3px 3px no-repeat;}#link__wiz_result div.type_d{padding:3px 3px 3px 22px;background:transparent url(/docs/wiki/lib/tpl/default/../../images/ns.png) 3px 3px no-repeat;}#link__wiz_result div.even{background-color:#f5f5f5;}#link__wiz_result div.selected{background-color:#dee7ec;}#link__wiz_result span{display:block;color:#666;}.ondrag{cursor:move;opacity:0.8;}form#subscribe__form{display:block;width:300px;text-align:center;}form#subscribe__form fieldset{text-align:left;margin:0.5em 0;}form#subscribe__form label{display:block;margin:0 0.5em 0.5em;} \ No newline at end of file diff --git a/docs/user/source/percona-theme/static/percona.com.js b/docs/user/source/percona-theme/static/percona.com.js new file mode 100644 index 00000000..93342f82 --- /dev/null +++ b/docs/user/source/percona-theme/static/percona.com.js @@ -0,0 +1,173 @@ +(function(E,A){function U(){return false}function ba(){return true}function ja(a,b,d){d[0].type=a;return c.event.handle.apply(b,d)}function Ga(a){var b,d,e=[],f=[],h,k,l,n,s,v,B,D;k=c.data(this,this.nodeType?"events":"__events__");if(typeof k==="function")k=k.events;if(!(a.liveFired===this||!k||!k.live||a.button&&a.type==="click")){if(a.namespace)D=RegExp("(^|\\.)"+a.namespace.split(".").join("\\.(?:.*\\.)?")+"(\\.|$)");a.liveFired=this;var H=k.live.slice(0);for(n=0;nd)break;a.currentTarget=f.elem;a.data=f.handleObj.data; +a.handleObj=f.handleObj;D=f.handleObj.origHandler.apply(f.elem,arguments);if(D===false||a.isPropagationStopped()){d=f.level;if(D===false)b=false}}return b}}function Y(a,b){return(a&&a!=="*"?a+".":"")+b.replace(Ha,"`").replace(Ia,"&")}function ka(a,b,d){if(c.isFunction(b))return c.grep(a,function(f,h){return!!b.call(f,h,f)===d});else if(b.nodeType)return c.grep(a,function(f){return f===b===d});else if(typeof b==="string"){var e=c.grep(a,function(f){return f.nodeType===1});if(Ja.test(b))return c.filter(b, +e,!d);else b=c.filter(b,e)}return c.grep(a,function(f){return c.inArray(f,b)>=0===d})}function la(a,b){var d=0;b.each(function(){if(this.nodeName===(a[d]&&a[d].nodeName)){var e=c.data(a[d++]),f=c.data(this,e);if(e=e&&e.events){delete f.handle;f.events={};for(var h in e)for(var k in e[h])c.event.add(this,h,e[h][k],e[h][k].data)}}})}function Ka(a,b){b.src?c.ajax({url:b.src,async:false,dataType:"script"}):c.globalEval(b.text||b.textContent||b.innerHTML||"");b.parentNode&&b.parentNode.removeChild(b)} +function ma(a,b,d){var e=b==="width"?a.offsetWidth:a.offsetHeight;if(d==="border")return e;c.each(b==="width"?La:Ma,function(){d||(e-=parseFloat(c.css(a,"padding"+this))||0);if(d==="margin")e+=parseFloat(c.css(a,"margin"+this))||0;else e-=parseFloat(c.css(a,"border"+this+"Width"))||0});return e}function ca(a,b,d,e){if(c.isArray(b)&&b.length)c.each(b,function(f,h){d||Na.test(a)?e(a,h):ca(a+"["+(typeof h==="object"||c.isArray(h)?f:"")+"]",h,d,e)});else if(!d&&b!=null&&typeof b==="object")c.isEmptyObject(b)? +e(a,""):c.each(b,function(f,h){ca(a+"["+f+"]",h,d,e)});else e(a,b)}function S(a,b){var d={};c.each(na.concat.apply([],na.slice(0,b)),function(){d[this]=a});return d}function oa(a){if(!da[a]){var b=c("<"+a+">").appendTo("body"),d=b.css("display");b.remove();if(d==="none"||d==="")d="block";da[a]=d}return da[a]}function ea(a){return c.isWindow(a)?a:a.nodeType===9?a.defaultView||a.parentWindow:false}var u=E.document,c=function(){function a(){if(!b.isReady){try{u.documentElement.doScroll("left")}catch(i){setTimeout(a, +1);return}b.ready()}}var b=function(i,r){return new b.fn.init(i,r)},d=E.jQuery,e=E.$,f,h=/^(?:[^<]*(<[\w\W]+>)[^>]*$|#([\w\-]+)$)/,k=/\S/,l=/^\s+/,n=/\s+$/,s=/\W/,v=/\d/,B=/^<(\w+)\s*\/?>(?:<\/\1>)?$/,D=/^[\],:{}\s]*$/,H=/\\(?:["\\\/bfnrt]|u[0-9a-fA-F]{4})/g,w=/"[^"\\\n\r]*"|true|false|null|-?\d+(?:\.\d*)?(?:[eE][+\-]?\d+)?/g,G=/(?:^|:|,)(?:\s*\[)+/g,M=/(webkit)[ \/]([\w.]+)/,g=/(opera)(?:.*version)?[ \/]([\w.]+)/,j=/(msie) ([\w.]+)/,o=/(mozilla)(?:.*? rv:([\w.]+))?/,m=navigator.userAgent,p=false, +q=[],t,x=Object.prototype.toString,C=Object.prototype.hasOwnProperty,P=Array.prototype.push,N=Array.prototype.slice,R=String.prototype.trim,Q=Array.prototype.indexOf,L={};b.fn=b.prototype={init:function(i,r){var y,z,F;if(!i)return this;if(i.nodeType){this.context=this[0]=i;this.length=1;return this}if(i==="body"&&!r&&u.body){this.context=u;this[0]=u.body;this.selector="body";this.length=1;return this}if(typeof i==="string")if((y=h.exec(i))&&(y[1]||!r))if(y[1]){F=r?r.ownerDocument||r:u;if(z=B.exec(i))if(b.isPlainObject(r)){i= +[u.createElement(z[1])];b.fn.attr.call(i,r,true)}else i=[F.createElement(z[1])];else{z=b.buildFragment([y[1]],[F]);i=(z.cacheable?z.fragment.cloneNode(true):z.fragment).childNodes}return b.merge(this,i)}else{if((z=u.getElementById(y[2]))&&z.parentNode){if(z.id!==y[2])return f.find(i);this.length=1;this[0]=z}this.context=u;this.selector=i;return this}else if(!r&&!s.test(i)){this.selector=i;this.context=u;i=u.getElementsByTagName(i);return b.merge(this,i)}else return!r||r.jquery?(r||f).find(i):b(r).find(i); +else if(b.isFunction(i))return f.ready(i);if(i.selector!==A){this.selector=i.selector;this.context=i.context}return b.makeArray(i,this)},selector:"",jquery:"1.4.3",length:0,size:function(){return this.length},toArray:function(){return N.call(this,0)},get:function(i){return i==null?this.toArray():i<0?this.slice(i)[0]:this[i]},pushStack:function(i,r,y){var z=b();b.isArray(i)?P.apply(z,i):b.merge(z,i);z.prevObject=this;z.context=this.context;if(r==="find")z.selector=this.selector+(this.selector?" ": +"")+y;else if(r)z.selector=this.selector+"."+r+"("+y+")";return z},each:function(i,r){return b.each(this,i,r)},ready:function(i){b.bindReady();if(b.isReady)i.call(u,b);else q&&q.push(i);return this},eq:function(i){return i===-1?this.slice(i):this.slice(i,+i+1)},first:function(){return this.eq(0)},last:function(){return this.eq(-1)},slice:function(){return this.pushStack(N.apply(this,arguments),"slice",N.call(arguments).join(","))},map:function(i){return this.pushStack(b.map(this,function(r,y){return i.call(r, +y,r)}))},end:function(){return this.prevObject||b(null)},push:P,sort:[].sort,splice:[].splice};b.fn.init.prototype=b.fn;b.extend=b.fn.extend=function(){var i=arguments[0]||{},r=1,y=arguments.length,z=false,F,I,K,J,fa;if(typeof i==="boolean"){z=i;i=arguments[1]||{};r=2}if(typeof i!=="object"&&!b.isFunction(i))i={};if(y===r){i=this;--r}for(;r0)){if(q){for(var r=0;i=q[r++];)i.call(u,b);q=null}b.fn.triggerHandler&&b(u).triggerHandler("ready")}}},bindReady:function(){if(!p){p=true;if(u.readyState==="complete")return setTimeout(b.ready, +1);if(u.addEventListener){u.addEventListener("DOMContentLoaded",t,false);E.addEventListener("load",b.ready,false)}else if(u.attachEvent){u.attachEvent("onreadystatechange",t);E.attachEvent("onload",b.ready);var i=false;try{i=E.frameElement==null}catch(r){}u.documentElement.doScroll&&i&&a()}}},isFunction:function(i){return b.type(i)==="function"},isArray:Array.isArray||function(i){return b.type(i)==="array"},isWindow:function(i){return i&&typeof i==="object"&&"setInterval"in i},isNaN:function(i){return i== +null||!v.test(i)||isNaN(i)},type:function(i){return i==null?String(i):L[x.call(i)]||"object"},isPlainObject:function(i){if(!i||b.type(i)!=="object"||i.nodeType||b.isWindow(i))return false;if(i.constructor&&!C.call(i,"constructor")&&!C.call(i.constructor.prototype,"isPrototypeOf"))return false;for(var r in i);return r===A||C.call(i,r)},isEmptyObject:function(i){for(var r in i)return false;return true},error:function(i){throw i;},parseJSON:function(i){if(typeof i!=="string"||!i)return null;i=b.trim(i); +if(D.test(i.replace(H,"@").replace(w,"]").replace(G,"")))return E.JSON&&E.JSON.parse?E.JSON.parse(i):(new Function("return "+i))();else b.error("Invalid JSON: "+i)},noop:function(){},globalEval:function(i){if(i&&k.test(i)){var r=u.getElementsByTagName("head")[0]||u.documentElement,y=u.createElement("script");y.type="text/javascript";if(b.support.scriptEval)y.appendChild(u.createTextNode(i));else y.text=i;r.insertBefore(y,r.firstChild);r.removeChild(y)}},nodeName:function(i,r){return i.nodeName&&i.nodeName.toUpperCase()=== +r.toUpperCase()},each:function(i,r,y){var z,F=0,I=i.length,K=I===A||b.isFunction(i);if(y)if(K)for(z in i){if(r.apply(i[z],y)===false)break}else for(;F";a=u.createDocumentFragment();a.appendChild(d.firstChild);c.support.checkClone=a.cloneNode(true).cloneNode(true).lastChild.checked;c(function(){var s=u.createElement("div"); +s.style.width=s.style.paddingLeft="1px";u.body.appendChild(s);c.boxModel=c.support.boxModel=s.offsetWidth===2;if("zoom"in s.style){s.style.display="inline";s.style.zoom=1;c.support.inlineBlockNeedsLayout=s.offsetWidth===2;s.style.display="";s.innerHTML="
";c.support.shrinkWrapBlocks=s.offsetWidth!==2}s.innerHTML="
t
";var v=s.getElementsByTagName("td");c.support.reliableHiddenOffsets=v[0].offsetHeight=== +0;v[0].style.display="";v[1].style.display="none";c.support.reliableHiddenOffsets=c.support.reliableHiddenOffsets&&v[0].offsetHeight===0;s.innerHTML="";u.body.removeChild(s).style.display="none"});a=function(s){var v=u.createElement("div");s="on"+s;var B=s in v;if(!B){v.setAttribute(s,"return;");B=typeof v[s]==="function"}return B};c.support.submitBubbles=a("submit");c.support.changeBubbles=a("change");a=b=d=f=h=null}})();c.props={"for":"htmlFor","class":"className",readonly:"readOnly",maxlength:"maxLength", +cellspacing:"cellSpacing",rowspan:"rowSpan",colspan:"colSpan",tabindex:"tabIndex",usemap:"useMap",frameborder:"frameBorder"};var pa={},Oa=/^(?:\{.*\}|\[.*\])$/;c.extend({cache:{},uuid:0,expando:"jQuery"+c.now(),noData:{embed:true,object:"clsid:D27CDB6E-AE6D-11cf-96B8-444553540000",applet:true},data:function(a,b,d){if(c.acceptData(a)){a=a==E?pa:a;var e=a.nodeType,f=e?a[c.expando]:null,h=c.cache;if(!(e&&!f&&typeof b==="string"&&d===A)){if(e)f||(a[c.expando]=f=++c.uuid);else h=a;if(typeof b==="object")if(e)h[f]= +c.extend(h[f],b);else c.extend(h,b);else if(e&&!h[f])h[f]={};a=e?h[f]:h;if(d!==A)a[b]=d;return typeof b==="string"?a[b]:a}}},removeData:function(a,b){if(c.acceptData(a)){a=a==E?pa:a;var d=a.nodeType,e=d?a[c.expando]:a,f=c.cache,h=d?f[e]:e;if(b){if(h){delete h[b];d&&c.isEmptyObject(h)&&c.removeData(a)}}else if(d&&c.support.deleteExpando)delete a[c.expando];else if(a.removeAttribute)a.removeAttribute(c.expando);else if(d)delete f[e];else for(var k in a)delete a[k]}},acceptData:function(a){if(a.nodeName){var b= +c.noData[a.nodeName.toLowerCase()];if(b)return!(b===true||a.getAttribute("classid")!==b)}return true}});c.fn.extend({data:function(a,b){if(typeof a==="undefined")return this.length?c.data(this[0]):null;else if(typeof a==="object")return this.each(function(){c.data(this,a)});var d=a.split(".");d[1]=d[1]?"."+d[1]:"";if(b===A){var e=this.triggerHandler("getData"+d[1]+"!",[d[0]]);if(e===A&&this.length){e=c.data(this[0],a);if(e===A&&this[0].nodeType===1){e=this[0].getAttribute("data-"+a);if(typeof e=== +"string")try{e=e==="true"?true:e==="false"?false:e==="null"?null:!c.isNaN(e)?parseFloat(e):Oa.test(e)?c.parseJSON(e):e}catch(f){}else e=A}}return e===A&&d[1]?this.data(d[0]):e}else return this.each(function(){var h=c(this),k=[d[0],b];h.triggerHandler("setData"+d[1]+"!",k);c.data(this,a,b);h.triggerHandler("changeData"+d[1]+"!",k)})},removeData:function(a){return this.each(function(){c.removeData(this,a)})}});c.extend({queue:function(a,b,d){if(a){b=(b||"fx")+"queue";var e=c.data(a,b);if(!d)return e|| +[];if(!e||c.isArray(d))e=c.data(a,b,c.makeArray(d));else e.push(d);return e}},dequeue:function(a,b){b=b||"fx";var d=c.queue(a,b),e=d.shift();if(e==="inprogress")e=d.shift();if(e){b==="fx"&&d.unshift("inprogress");e.call(a,function(){c.dequeue(a,b)})}}});c.fn.extend({queue:function(a,b){if(typeof a!=="string"){b=a;a="fx"}if(b===A)return c.queue(this[0],a);return this.each(function(){var d=c.queue(this,a,b);a==="fx"&&d[0]!=="inprogress"&&c.dequeue(this,a)})},dequeue:function(a){return this.each(function(){c.dequeue(this, +a)})},delay:function(a,b){a=c.fx?c.fx.speeds[a]||a:a;b=b||"fx";return this.queue(b,function(){var d=this;setTimeout(function(){c.dequeue(d,b)},a)})},clearQueue:function(a){return this.queue(a||"fx",[])}});var qa=/[\n\t]/g,ga=/\s+/,Pa=/\r/g,Qa=/^(?:href|src|style)$/,Ra=/^(?:button|input)$/i,Sa=/^(?:button|input|object|select|textarea)$/i,Ta=/^a(?:rea)?$/i,ra=/^(?:radio|checkbox)$/i;c.fn.extend({attr:function(a,b){return c.access(this,a,b,true,c.attr)},removeAttr:function(a){return this.each(function(){c.attr(this, +a,"");this.nodeType===1&&this.removeAttribute(a)})},addClass:function(a){if(c.isFunction(a))return this.each(function(s){var v=c(this);v.addClass(a.call(this,s,v.attr("class")))});if(a&&typeof a==="string")for(var b=(a||"").split(ga),d=0,e=this.length;d-1)return true;return false}, +val:function(a){if(!arguments.length){var b=this[0];if(b){if(c.nodeName(b,"option")){var d=b.attributes.value;return!d||d.specified?b.value:b.text}if(c.nodeName(b,"select")){var e=b.selectedIndex;d=[];var f=b.options;b=b.type==="select-one";if(e<0)return null;var h=b?e:0;for(e=b?e+1:f.length;h=0;else if(c.nodeName(this,"select")){var B=c.makeArray(v);c("option",this).each(function(){this.selected= +c.inArray(c(this).val(),B)>=0});if(!B.length)this.selectedIndex=-1}else this.value=v}})}});c.extend({attrFn:{val:true,css:true,html:true,text:true,data:true,width:true,height:true,offset:true},attr:function(a,b,d,e){if(!a||a.nodeType===3||a.nodeType===8)return A;if(e&&b in c.attrFn)return c(a)[b](d);e=a.nodeType!==1||!c.isXMLDoc(a);var f=d!==A;b=e&&c.props[b]||b;if(a.nodeType===1){var h=Qa.test(b);if((b in a||a[b]!==A)&&e&&!h){if(f){b==="type"&&Ra.test(a.nodeName)&&a.parentNode&&c.error("type property can't be changed"); +if(d===null)a.nodeType===1&&a.removeAttribute(b);else a[b]=d}if(c.nodeName(a,"form")&&a.getAttributeNode(b))return a.getAttributeNode(b).nodeValue;if(b==="tabIndex")return(b=a.getAttributeNode("tabIndex"))&&b.specified?b.value:Sa.test(a.nodeName)||Ta.test(a.nodeName)&&a.href?0:A;return a[b]}if(!c.support.style&&e&&b==="style"){if(f)a.style.cssText=""+d;return a.style.cssText}f&&a.setAttribute(b,""+d);if(!a.attributes[b]&&a.hasAttribute&&!a.hasAttribute(b))return A;a=!c.support.hrefNormalized&&e&& +h?a.getAttribute(b,2):a.getAttribute(b);return a===null?A:a}}});var X=/\.(.*)$/,ha=/^(?:textarea|input|select)$/i,Ha=/\./g,Ia=/ /g,Ua=/[^\w\s.|`]/g,Va=function(a){return a.replace(Ua,"\\$&")},sa={focusin:0,focusout:0};c.event={add:function(a,b,d,e){if(!(a.nodeType===3||a.nodeType===8)){if(c.isWindow(a)&&a!==E&&!a.frameElement)a=E;if(d===false)d=U;var f,h;if(d.handler){f=d;d=f.handler}if(!d.guid)d.guid=c.guid++;if(h=c.data(a)){var k=a.nodeType?"events":"__events__",l=h[k],n=h.handle;if(typeof l=== +"function"){n=l.handle;l=l.events}else if(!l){a.nodeType||(h[k]=h=function(){});h.events=l={}}if(!n)h.handle=n=function(){return typeof c!=="undefined"&&!c.event.triggered?c.event.handle.apply(n.elem,arguments):A};n.elem=a;b=b.split(" ");for(var s=0,v;k=b[s++];){h=f?c.extend({},f):{handler:d,data:e};if(k.indexOf(".")>-1){v=k.split(".");k=v.shift();h.namespace=v.slice(0).sort().join(".")}else{v=[];h.namespace=""}h.type=k;if(!h.guid)h.guid=d.guid;var B=l[k],D=c.event.special[k]||{};if(!B){B=l[k]=[]; +if(!D.setup||D.setup.call(a,e,v,n)===false)if(a.addEventListener)a.addEventListener(k,n,false);else a.attachEvent&&a.attachEvent("on"+k,n)}if(D.add){D.add.call(a,h);if(!h.handler.guid)h.handler.guid=d.guid}B.push(h);c.event.global[k]=true}a=null}}},global:{},remove:function(a,b,d,e){if(!(a.nodeType===3||a.nodeType===8)){if(d===false)d=U;var f,h,k=0,l,n,s,v,B,D,H=a.nodeType?"events":"__events__",w=c.data(a),G=w&&w[H];if(w&&G){if(typeof G==="function"){w=G;G=G.events}if(b&&b.type){d=b.handler;b=b.type}if(!b|| +typeof b==="string"&&b.charAt(0)==="."){b=b||"";for(f in G)c.event.remove(a,f+b)}else{for(b=b.split(" ");f=b[k++];){v=f;l=f.indexOf(".")<0;n=[];if(!l){n=f.split(".");f=n.shift();s=RegExp("(^|\\.)"+c.map(n.slice(0).sort(),Va).join("\\.(?:.*\\.)?")+"(\\.|$)")}if(B=G[f])if(d){v=c.event.special[f]||{};for(h=e||0;h=0){a.type= +f=f.slice(0,-1);a.exclusive=true}if(!d){a.stopPropagation();c.event.global[f]&&c.each(c.cache,function(){this.events&&this.events[f]&&c.event.trigger(a,b,this.handle.elem)})}if(!d||d.nodeType===3||d.nodeType===8)return A;a.result=A;a.target=d;b=c.makeArray(b);b.unshift(a)}a.currentTarget=d;(e=d.nodeType?c.data(d,"handle"):(c.data(d,"__events__")||{}).handle)&&e.apply(d,b);e=d.parentNode||d.ownerDocument;try{if(!(d&&d.nodeName&&c.noData[d.nodeName.toLowerCase()]))if(d["on"+f]&&d["on"+f].apply(d,b)=== +false){a.result=false;a.preventDefault()}}catch(h){}if(!a.isPropagationStopped()&&e)c.event.trigger(a,b,e,true);else if(!a.isDefaultPrevented()){e=a.target;var k,l=f.replace(X,""),n=c.nodeName(e,"a")&&l==="click",s=c.event.special[l]||{};if((!s._default||s._default.call(d,a)===false)&&!n&&!(e&&e.nodeName&&c.noData[e.nodeName.toLowerCase()])){try{if(e[l]){if(k=e["on"+l])e["on"+l]=null;c.event.triggered=true;e[l]()}}catch(v){}if(k)e["on"+l]=k;c.event.triggered=false}}},handle:function(a){var b,d,e; +d=[];var f,h=c.makeArray(arguments);a=h[0]=c.event.fix(a||E.event);a.currentTarget=this;b=a.type.indexOf(".")<0&&!a.exclusive;if(!b){e=a.type.split(".");a.type=e.shift();d=e.slice(0).sort();e=RegExp("(^|\\.)"+d.join("\\.(?:.*\\.)?")+"(\\.|$)")}a.namespace=a.namespace||d.join(".");f=c.data(this,this.nodeType?"events":"__events__");if(typeof f==="function")f=f.events;d=(f||{})[a.type];if(f&&d){d=d.slice(0);f=0;for(var k=d.length;f-1?c.map(a.options,function(e){return e.selected}).join("-"):"";else if(a.nodeName.toLowerCase()==="select")d=a.selectedIndex;return d},Z=function(a,b){var d=a.target,e,f;if(!(!ha.test(d.nodeName)||d.readOnly)){e=c.data(d,"_change_data");f=va(d);if(a.type!=="focusout"||d.type!=="radio")c.data(d,"_change_data",f);if(!(e===A||f===e))if(e!=null||f){a.type="change";a.liveFired= +A;return c.event.trigger(a,b,d)}}};c.event.special.change={filters:{focusout:Z,beforedeactivate:Z,click:function(a){var b=a.target,d=b.type;if(d==="radio"||d==="checkbox"||b.nodeName.toLowerCase()==="select")return Z.call(this,a)},keydown:function(a){var b=a.target,d=b.type;if(a.keyCode===13&&b.nodeName.toLowerCase()!=="textarea"||a.keyCode===32&&(d==="checkbox"||d==="radio")||d==="select-multiple")return Z.call(this,a)},beforeactivate:function(a){a=a.target;c.data(a,"_change_data",va(a))}},setup:function(){if(this.type=== +"file")return false;for(var a in V)c.event.add(this,a+".specialChange",V[a]);return ha.test(this.nodeName)},teardown:function(){c.event.remove(this,".specialChange");return ha.test(this.nodeName)}};V=c.event.special.change.filters;V.focus=V.beforeactivate}u.addEventListener&&c.each({focus:"focusin",blur:"focusout"},function(a,b){function d(e){e=c.event.fix(e);e.type=b;return c.event.trigger(e,null,e.target)}c.event.special[b]={setup:function(){sa[b]++===0&&u.addEventListener(a,d,true)},teardown:function(){--sa[b]=== +0&&u.removeEventListener(a,d,true)}}});c.each(["bind","one"],function(a,b){c.fn[b]=function(d,e,f){if(typeof d==="object"){for(var h in d)this[b](h,e,d[h],f);return this}if(c.isFunction(e)||e===false){f=e;e=A}var k=b==="one"?c.proxy(f,function(n){c(this).unbind(n,k);return f.apply(this,arguments)}):f;if(d==="unload"&&b!=="one")this.one(d,e,f);else{h=0;for(var l=this.length;h0?this.bind(b,d,e):this.trigger(b)};if(c.attrFn)c.attrFn[b]=true});E.attachEvent&&!E.addEventListener&&c(E).bind("unload",function(){for(var a in c.cache)if(c.cache[a].handle)try{c.event.remove(c.cache[a].handle.elem)}catch(b){}}); +(function(){function a(g,j,o,m,p,q){p=0;for(var t=m.length;p0){C=x;break}}x=x[g]}m[p]=C}}}var d=/((?:\((?:\([^()]+\)|[^()]+)+\)|\[(?:\[[^\[\]]*\]|['"][^'"]*['"]|[^\[\]'"]+)+\]|\\.|[^ >+~,(\[\\]+)+|[>+~])(\s*,\s*)?((?:.|\r|\n)*)/g,e=0,f=Object.prototype.toString,h=false,k=true;[0,0].sort(function(){k=false;return 0});var l=function(g,j,o,m){o=o||[];var p=j=j||u;if(j.nodeType!==1&&j.nodeType!==9)return[];if(!g||typeof g!=="string")return o;var q=[],t,x,C,P,N=true,R=l.isXML(j),Q=g,L;do{d.exec("");if(t=d.exec(Q)){Q=t[3];q.push(t[1]);if(t[2]){P=t[3]; +break}}}while(t);if(q.length>1&&s.exec(g))if(q.length===2&&n.relative[q[0]])x=M(q[0]+q[1],j);else for(x=n.relative[q[0]]?[j]:l(q.shift(),j);q.length;){g=q.shift();if(n.relative[g])g+=q.shift();x=M(g,x)}else{if(!m&&q.length>1&&j.nodeType===9&&!R&&n.match.ID.test(q[0])&&!n.match.ID.test(q[q.length-1])){t=l.find(q.shift(),j,R);j=t.expr?l.filter(t.expr,t.set)[0]:t.set[0]}if(j){t=m?{expr:q.pop(),set:D(m)}:l.find(q.pop(),q.length===1&&(q[0]==="~"||q[0]==="+")&&j.parentNode?j.parentNode:j,R);x=t.expr?l.filter(t.expr, +t.set):t.set;if(q.length>0)C=D(x);else N=false;for(;q.length;){t=L=q.pop();if(n.relative[L])t=q.pop();else L="";if(t==null)t=j;n.relative[L](C,t,R)}}else C=[]}C||(C=x);C||l.error(L||g);if(f.call(C)==="[object Array]")if(N)if(j&&j.nodeType===1)for(g=0;C[g]!=null;g++){if(C[g]&&(C[g]===true||C[g].nodeType===1&&l.contains(j,C[g])))o.push(x[g])}else for(g=0;C[g]!=null;g++)C[g]&&C[g].nodeType===1&&o.push(x[g]);else o.push.apply(o,C);else D(C,o);if(P){l(P,p,o,m);l.uniqueSort(o)}return o};l.uniqueSort=function(g){if(w){h= +k;g.sort(w);if(h)for(var j=1;j0};l.find=function(g,j,o){var m;if(!g)return[];for(var p=0,q=n.order.length;p":function(g,j){var o=typeof j==="string",m,p=0,q=g.length;if(o&&!/\W/.test(j))for(j=j.toLowerCase();p=0))o||m.push(t);else if(o)j[q]=false;return false},ID:function(g){return g[1].replace(/\\/g,"")},TAG:function(g){return g[1].toLowerCase()},CHILD:function(g){if(g[1]==="nth"){var j=/(-?)(\d*)n((?:\+|-)?\d*)/.exec(g[2]==="even"&&"2n"||g[2]==="odd"&&"2n+1"||!/\D/.test(g[2])&&"0n+"+g[2]||g[2]);g[2]=j[1]+(j[2]||1)-0;g[3]=j[3]-0}g[0]=e++;return g},ATTR:function(g,j,o, +m,p,q){j=g[1].replace(/\\/g,"");if(!q&&n.attrMap[j])g[1]=n.attrMap[j];if(g[2]==="~=")g[4]=" "+g[4]+" ";return g},PSEUDO:function(g,j,o,m,p){if(g[1]==="not")if((d.exec(g[3])||"").length>1||/^\w/.test(g[3]))g[3]=l(g[3],null,null,j);else{g=l.filter(g[3],j,o,true^p);o||m.push.apply(m,g);return false}else if(n.match.POS.test(g[0])||n.match.CHILD.test(g[0]))return true;return g},POS:function(g){g.unshift(true);return g}},filters:{enabled:function(g){return g.disabled===false&&g.type!=="hidden"},disabled:function(g){return g.disabled=== +true},checked:function(g){return g.checked===true},selected:function(g){return g.selected===true},parent:function(g){return!!g.firstChild},empty:function(g){return!g.firstChild},has:function(g,j,o){return!!l(o[3],g).length},header:function(g){return/h\d/i.test(g.nodeName)},text:function(g){return"text"===g.type},radio:function(g){return"radio"===g.type},checkbox:function(g){return"checkbox"===g.type},file:function(g){return"file"===g.type},password:function(g){return"password"===g.type},submit:function(g){return"submit"=== +g.type},image:function(g){return"image"===g.type},reset:function(g){return"reset"===g.type},button:function(g){return"button"===g.type||g.nodeName.toLowerCase()==="button"},input:function(g){return/input|select|textarea|button/i.test(g.nodeName)}},setFilters:{first:function(g,j){return j===0},last:function(g,j,o,m){return j===m.length-1},even:function(g,j){return j%2===0},odd:function(g,j){return j%2===1},lt:function(g,j,o){return jo[3]-0},nth:function(g,j,o){return o[3]- +0===j},eq:function(g,j,o){return o[3]-0===j}},filter:{PSEUDO:function(g,j,o,m){var p=j[1],q=n.filters[p];if(q)return q(g,o,j,m);else if(p==="contains")return(g.textContent||g.innerText||l.getText([g])||"").indexOf(j[3])>=0;else if(p==="not"){j=j[3];o=0;for(m=j.length;o=0}},ID:function(g,j){return g.nodeType===1&&g.getAttribute("id")===j},TAG:function(g,j){return j==="*"&&g.nodeType===1||g.nodeName.toLowerCase()=== +j},CLASS:function(g,j){return(" "+(g.className||g.getAttribute("class"))+" ").indexOf(j)>-1},ATTR:function(g,j){var o=j[1];o=n.attrHandle[o]?n.attrHandle[o](g):g[o]!=null?g[o]:g.getAttribute(o);var m=o+"",p=j[2],q=j[4];return o==null?p==="!=":p==="="?m===q:p==="*="?m.indexOf(q)>=0:p==="~="?(" "+m+" ").indexOf(q)>=0:!q?m&&o!==false:p==="!="?m!==q:p==="^="?m.indexOf(q)===0:p==="$="?m.substr(m.length-q.length)===q:p==="|="?m===q||m.substr(0,q.length+1)===q+"-":false},POS:function(g,j,o,m){var p=n.setFilters[j[2]]; +if(p)return p(g,o,j,m)}}},s=n.match.POS,v=function(g,j){return"\\"+(j-0+1)},B;for(B in n.match){n.match[B]=RegExp(n.match[B].source+/(?![^\[]*\])(?![^\(]*\))/.source);n.leftMatch[B]=RegExp(/(^(?:.|\r|\n)*?)/.source+n.match[B].source.replace(/\\(\d+)/g,v))}var D=function(g,j){g=Array.prototype.slice.call(g,0);if(j){j.push.apply(j,g);return j}return g};try{Array.prototype.slice.call(u.documentElement.childNodes,0)}catch(H){D=function(g,j){var o=j||[],m=0;if(f.call(g)==="[object Array]")Array.prototype.push.apply(o, +g);else if(typeof g.length==="number")for(var p=g.length;m";var o=u.documentElement;o.insertBefore(g,o.firstChild);if(u.getElementById(j)){n.find.ID=function(m,p,q){if(typeof p.getElementById!=="undefined"&&!q)return(p=p.getElementById(m[1]))?p.id===m[1]||typeof p.getAttributeNode!=="undefined"&&p.getAttributeNode("id").nodeValue===m[1]?[p]:A:[]};n.filter.ID=function(m,p){var q=typeof m.getAttributeNode!=="undefined"&&m.getAttributeNode("id");return m.nodeType===1&&q&&q.nodeValue===p}}o.removeChild(g); +o=g=null})();(function(){var g=u.createElement("div");g.appendChild(u.createComment(""));if(g.getElementsByTagName("*").length>0)n.find.TAG=function(j,o){var m=o.getElementsByTagName(j[1]);if(j[1]==="*"){for(var p=[],q=0;m[q];q++)m[q].nodeType===1&&p.push(m[q]);m=p}return m};g.innerHTML="";if(g.firstChild&&typeof g.firstChild.getAttribute!=="undefined"&&g.firstChild.getAttribute("href")!=="#")n.attrHandle.href=function(j){return j.getAttribute("href",2)};g=null})();u.querySelectorAll&& +function(){var g=l,j=u.createElement("div");j.innerHTML="

";if(!(j.querySelectorAll&&j.querySelectorAll(".TEST").length===0)){l=function(m,p,q,t){p=p||u;if(!t&&!l.isXML(p))if(p.nodeType===9)try{return D(p.querySelectorAll(m),q)}catch(x){}else if(p.nodeType===1&&p.nodeName.toLowerCase()!=="object"){var C=p.id,P=p.id="__sizzle__";try{return D(p.querySelectorAll("#"+P+" "+m),q)}catch(N){}finally{if(C)p.id=C;else p.removeAttribute("id")}}return g(m,p,q,t)};for(var o in g)l[o]=g[o]; +j=null}}();(function(){var g=u.documentElement,j=g.matchesSelector||g.mozMatchesSelector||g.webkitMatchesSelector||g.msMatchesSelector,o=false;try{j.call(u.documentElement,":sizzle")}catch(m){o=true}if(j)l.matchesSelector=function(p,q){try{if(o||!n.match.PSEUDO.test(q))return j.call(p,q)}catch(t){}return l(q,null,null,[p]).length>0}})();(function(){var g=u.createElement("div");g.innerHTML="
";if(!(!g.getElementsByClassName||g.getElementsByClassName("e").length=== +0)){g.lastChild.className="e";if(g.getElementsByClassName("e").length!==1){n.order.splice(1,0,"CLASS");n.find.CLASS=function(j,o,m){if(typeof o.getElementsByClassName!=="undefined"&&!m)return o.getElementsByClassName(j[1])};g=null}}})();l.contains=u.documentElement.contains?function(g,j){return g!==j&&(g.contains?g.contains(j):true)}:function(g,j){return!!(g.compareDocumentPosition(j)&16)};l.isXML=function(g){return(g=(g?g.ownerDocument||g:0).documentElement)?g.nodeName!=="HTML":false};var M=function(g, +j){for(var o=[],m="",p,q=j.nodeType?[j]:j;p=n.match.PSEUDO.exec(g);){m+=p[0];g=g.replace(n.match.PSEUDO,"")}g=n.relative[g]?g+"*":g;p=0;for(var t=q.length;p0)for(var h=d;h0},closest:function(a, +b){var d=[],e,f,h=this[0];if(c.isArray(a)){var k={},l,n=1;if(h&&a.length){e=0;for(f=a.length;e-1:c(h).is(e))d.push({selector:l,elem:h,level:n})}h=h.parentNode;n++}}return d}k=$a.test(a)?c(a,b||this.context):null;e=0;for(f=this.length;e-1:c.find.matchesSelector(h,a)){d.push(h);break}else{h=h.parentNode;if(!h|| +!h.ownerDocument||h===b)break}d=d.length>1?c.unique(d):d;return this.pushStack(d,"closest",a)},index:function(a){if(!a||typeof a==="string")return c.inArray(this[0],a?c(a):this.parent().children());return c.inArray(a.jquery?a[0]:a,this)},add:function(a,b){var d=typeof a==="string"?c(a,b||this.context):c.makeArray(a),e=c.merge(this.get(),d);return this.pushStack(!d[0]||!d[0].parentNode||d[0].parentNode.nodeType===11||!e[0]||!e[0].parentNode||e[0].parentNode.nodeType===11?e:c.unique(e))},andSelf:function(){return this.add(this.prevObject)}}); +c.each({parent:function(a){return(a=a.parentNode)&&a.nodeType!==11?a:null},parents:function(a){return c.dir(a,"parentNode")},parentsUntil:function(a,b,d){return c.dir(a,"parentNode",d)},next:function(a){return c.nth(a,2,"nextSibling")},prev:function(a){return c.nth(a,2,"previousSibling")},nextAll:function(a){return c.dir(a,"nextSibling")},prevAll:function(a){return c.dir(a,"previousSibling")},nextUntil:function(a,b,d){return c.dir(a,"nextSibling",d)},prevUntil:function(a,b,d){return c.dir(a,"previousSibling", +d)},siblings:function(a){return c.sibling(a.parentNode.firstChild,a)},children:function(a){return c.sibling(a.firstChild)},contents:function(a){return c.nodeName(a,"iframe")?a.contentDocument||a.contentWindow.document:c.makeArray(a.childNodes)}},function(a,b){c.fn[a]=function(d,e){var f=c.map(this,b,d);Wa.test(a)||(e=d);if(e&&typeof e==="string")f=c.filter(e,f);f=this.length>1?c.unique(f):f;if((this.length>1||Ya.test(e))&&Xa.test(a))f=f.reverse();return this.pushStack(f,a,Za.call(arguments).join(","))}}); +c.extend({filter:function(a,b,d){if(d)a=":not("+a+")";return b.length===1?c.find.matchesSelector(b[0],a)?[b[0]]:[]:c.find.matches(a,b)},dir:function(a,b,d){var e=[];for(a=a[b];a&&a.nodeType!==9&&(d===A||a.nodeType!==1||!c(a).is(d));){a.nodeType===1&&e.push(a);a=a[b]}return e},nth:function(a,b,d){b=b||1;for(var e=0;a;a=a[d])if(a.nodeType===1&&++e===b)break;return a},sibling:function(a,b){for(var d=[];a;a=a.nextSibling)a.nodeType===1&&a!==b&&d.push(a);return d}});var xa=/ jQuery\d+="(?:\d+|null)"/g, +$=/^\s+/,ya=/<(?!area|br|col|embed|hr|img|input|link|meta|param)(([\w:]+)[^>]*)\/>/ig,za=/<([\w:]+)/,ab=/\s]+\/)>/g,O={option:[1,""],legend:[1,"
","
"],thead:[1,"","
"],tr:[2,"","
"],td:[3,"","
"],col:[2,"","
"], +area:[1,"",""],_default:[0,"",""]};O.optgroup=O.option;O.tbody=O.tfoot=O.colgroup=O.caption=O.thead;O.th=O.td;if(!c.support.htmlSerialize)O._default=[1,"div
","
"];c.fn.extend({text:function(a){if(c.isFunction(a))return this.each(function(b){var d=c(this);d.text(a.call(this,b,d.text()))});if(typeof a!=="object"&&a!==A)return this.empty().append((this[0]&&this[0].ownerDocument||u).createTextNode(a));return c.text(this)},wrapAll:function(a){if(c.isFunction(a))return this.each(function(d){c(this).wrapAll(a.call(this, +d))});if(this[0]){var b=c(a,this[0].ownerDocument).eq(0).clone(true);this[0].parentNode&&b.insertBefore(this[0]);b.map(function(){for(var d=this;d.firstChild&&d.firstChild.nodeType===1;)d=d.firstChild;return d}).append(this)}return this},wrapInner:function(a){if(c.isFunction(a))return this.each(function(b){c(this).wrapInner(a.call(this,b))});return this.each(function(){var b=c(this),d=b.contents();d.length?d.wrapAll(a):b.append(a)})},wrap:function(a){return this.each(function(){c(this).wrapAll(a)})}, +unwrap:function(){return this.parent().each(function(){c.nodeName(this,"body")||c(this).replaceWith(this.childNodes)}).end()},append:function(){return this.domManip(arguments,true,function(a){this.nodeType===1&&this.appendChild(a)})},prepend:function(){return this.domManip(arguments,true,function(a){this.nodeType===1&&this.insertBefore(a,this.firstChild)})},before:function(){if(this[0]&&this[0].parentNode)return this.domManip(arguments,false,function(b){this.parentNode.insertBefore(b,this)});else if(arguments.length){var a= +c(arguments[0]);a.push.apply(a,this.toArray());return this.pushStack(a,"before",arguments)}},after:function(){if(this[0]&&this[0].parentNode)return this.domManip(arguments,false,function(b){this.parentNode.insertBefore(b,this.nextSibling)});else if(arguments.length){var a=this.pushStack(this,"after",arguments);a.push.apply(a,c(arguments[0]).toArray());return a}},remove:function(a,b){for(var d=0,e;(e=this[d])!=null;d++)if(!a||c.filter(a,[e]).length){if(!b&&e.nodeType===1){c.cleanData(e.getElementsByTagName("*")); +c.cleanData([e])}e.parentNode&&e.parentNode.removeChild(e)}return this},empty:function(){for(var a=0,b;(b=this[a])!=null;a++)for(b.nodeType===1&&c.cleanData(b.getElementsByTagName("*"));b.firstChild;)b.removeChild(b.firstChild);return this},clone:function(a){var b=this.map(function(){if(!c.support.noCloneEvent&&!c.isXMLDoc(this)){var d=this.outerHTML,e=this.ownerDocument;if(!d){d=e.createElement("div");d.appendChild(this.cloneNode(true));d=d.innerHTML}return c.clean([d.replace(xa,"").replace(cb,'="$1">').replace($, +"")],e)[0]}else return this.cloneNode(true)});if(a===true){la(this,b);la(this.find("*"),b.find("*"))}return b},html:function(a){if(a===A)return this[0]&&this[0].nodeType===1?this[0].innerHTML.replace(xa,""):null;else if(typeof a==="string"&&!Aa.test(a)&&(c.support.leadingWhitespace||!$.test(a))&&!O[(za.exec(a)||["",""])[1].toLowerCase()]){a=a.replace(ya,"<$1>");try{for(var b=0,d=this.length;b0||e.cacheable||this.length>1?l.cloneNode(true):l)}k.length&&c.each(k,Ka)}return this}});c.buildFragment=function(a,b,d){var e,f,h;b=b&&b[0]?b[0].ownerDocument||b[0]:u;if(a.length===1&&typeof a[0]==="string"&&a[0].length<512&&b===u&&!Aa.test(a[0])&&(c.support.checkClone|| +!Ba.test(a[0]))){f=true;if(h=c.fragments[a[0]])if(h!==1)e=h}if(!e){e=b.createDocumentFragment();c.clean(a,b,e,d)}if(f)c.fragments[a[0]]=h?e:1;return{fragment:e,cacheable:f}};c.fragments={};c.each({appendTo:"append",prependTo:"prepend",insertBefore:"before",insertAfter:"after",replaceAll:"replaceWith"},function(a,b){c.fn[a]=function(d){var e=[];d=c(d);var f=this.length===1&&this[0].parentNode;if(f&&f.nodeType===11&&f.childNodes.length===1&&d.length===1){d[b](this[0]);return this}else{f=0;for(var h= +d.length;f0?this.clone(true):this).get();c(d[f])[b](k);e=e.concat(k)}return this.pushStack(e,a,d.selector)}}});c.extend({clean:function(a,b,d,e){b=b||u;if(typeof b.createElement==="undefined")b=b.ownerDocument||b[0]&&b[0].ownerDocument||u;for(var f=[],h=0,k;(k=a[h])!=null;h++){if(typeof k==="number")k+="";if(k){if(typeof k==="string"&&!bb.test(k))k=b.createTextNode(k);else if(typeof k==="string"){k=k.replace(ya,"<$1>");var l=(za.exec(k)||["",""])[1].toLowerCase(),n=O[l]||O._default, +s=n[0],v=b.createElement("div");for(v.innerHTML=n[1]+k+n[2];s--;)v=v.lastChild;if(!c.support.tbody){s=ab.test(k);l=l==="table"&&!s?v.firstChild&&v.firstChild.childNodes:n[1]===""&&!s?v.childNodes:[];for(n=l.length-1;n>=0;--n)c.nodeName(l[n],"tbody")&&!l[n].childNodes.length&&l[n].parentNode.removeChild(l[n])}!c.support.leadingWhitespace&&$.test(k)&&v.insertBefore(b.createTextNode($.exec(k)[0]),v.firstChild);k=v.childNodes}if(k.nodeType)f.push(k);else f=c.merge(f,k)}}if(d)for(h=0;f[h];h++)if(e&& +c.nodeName(f[h],"script")&&(!f[h].type||f[h].type.toLowerCase()==="text/javascript"))e.push(f[h].parentNode?f[h].parentNode.removeChild(f[h]):f[h]);else{f[h].nodeType===1&&f.splice.apply(f,[h+1,0].concat(c.makeArray(f[h].getElementsByTagName("script"))));d.appendChild(f[h])}return f},cleanData:function(a){for(var b,d,e=c.cache,f=c.event.special,h=c.support.deleteExpando,k=0,l;(l=a[k])!=null;k++)if(!(l.nodeName&&c.noData[l.nodeName.toLowerCase()]))if(d=l[c.expando]){if((b=e[d])&&b.events)for(var n in b.events)f[n]? +c.event.remove(l,n):c.removeEvent(l,n,b.handle);if(h)delete l[c.expando];else l.removeAttribute&&l.removeAttribute(c.expando);delete e[d]}}});var Ca=/alpha\([^)]*\)/i,db=/opacity=([^)]*)/,eb=/-([a-z])/ig,fb=/([A-Z])/g,Da=/^-?\d+(?:px)?$/i,gb=/^-?\d/,hb={position:"absolute",visibility:"hidden",display:"block"},La=["Left","Right"],Ma=["Top","Bottom"],W,ib=u.defaultView&&u.defaultView.getComputedStyle,jb=function(a,b){return b.toUpperCase()};c.fn.css=function(a,b){if(arguments.length===2&&b===A)return this; +return c.access(this,a,b,true,function(d,e,f){return f!==A?c.style(d,e,f):c.css(d,e)})};c.extend({cssHooks:{opacity:{get:function(a,b){if(b){var d=W(a,"opacity","opacity");return d===""?"1":d}else return a.style.opacity}}},cssNumber:{zIndex:true,fontWeight:true,opacity:true,zoom:true,lineHeight:true},cssProps:{"float":c.support.cssFloat?"cssFloat":"styleFloat"},style:function(a,b,d,e){if(!(!a||a.nodeType===3||a.nodeType===8||!a.style)){var f,h=c.camelCase(b),k=a.style,l=c.cssHooks[h];b=c.cssProps[h]|| +h;if(d!==A){if(!(typeof d==="number"&&isNaN(d)||d==null)){if(typeof d==="number"&&!c.cssNumber[h])d+="px";if(!l||!("set"in l)||(d=l.set(a,d))!==A)try{k[b]=d}catch(n){}}}else{if(l&&"get"in l&&(f=l.get(a,false,e))!==A)return f;return k[b]}}},css:function(a,b,d){var e,f=c.camelCase(b),h=c.cssHooks[f];b=c.cssProps[f]||f;if(h&&"get"in h&&(e=h.get(a,true,d))!==A)return e;else if(W)return W(a,b,f)},swap:function(a,b,d){var e={},f;for(f in b){e[f]=a.style[f];a.style[f]=b[f]}d.call(a);for(f in b)a.style[f]= +e[f]},camelCase:function(a){return a.replace(eb,jb)}});c.curCSS=c.css;c.each(["height","width"],function(a,b){c.cssHooks[b]={get:function(d,e,f){var h;if(e){if(d.offsetWidth!==0)h=ma(d,b,f);else c.swap(d,hb,function(){h=ma(d,b,f)});return h+"px"}},set:function(d,e){if(Da.test(e)){e=parseFloat(e);if(e>=0)return e+"px"}else return e}}});if(!c.support.opacity)c.cssHooks.opacity={get:function(a,b){return db.test((b&&a.currentStyle?a.currentStyle.filter:a.style.filter)||"")?parseFloat(RegExp.$1)/100+"": +b?"1":""},set:function(a,b){var d=a.style;d.zoom=1;var e=c.isNaN(b)?"":"alpha(opacity="+b*100+")",f=d.filter||"";d.filter=Ca.test(f)?f.replace(Ca,e):d.filter+" "+e}};if(ib)W=function(a,b,d){var e;d=d.replace(fb,"-$1").toLowerCase();if(!(b=a.ownerDocument.defaultView))return A;if(b=b.getComputedStyle(a,null)){e=b.getPropertyValue(d);if(e===""&&!c.contains(a.ownerDocument.documentElement,a))e=c.style(a,d)}return e};else if(u.documentElement.currentStyle)W=function(a,b){var d,e,f=a.currentStyle&&a.currentStyle[b], +h=a.style;if(!Da.test(f)&&gb.test(f)){d=h.left;e=a.runtimeStyle.left;a.runtimeStyle.left=a.currentStyle.left;h.left=b==="fontSize"?"1em":f||0;f=h.pixelLeft+"px";h.left=d;a.runtimeStyle.left=e}return f};if(c.expr&&c.expr.filters){c.expr.filters.hidden=function(a){var b=a.offsetHeight;return a.offsetWidth===0&&b===0||!c.support.reliableHiddenOffsets&&(a.style.display||c.css(a,"display"))==="none"};c.expr.filters.visible=function(a){return!c.expr.filters.hidden(a)}}var kb=c.now(),lb=/)<[^<]*)*<\/script>/gi, +mb=/^(?:select|textarea)/i,nb=/^(?:color|date|datetime|email|hidden|month|number|password|range|search|tel|text|time|url|week)$/i,ob=/^(?:GET|HEAD|DELETE)$/,Na=/\[\]$/,T=/\=\?(&|$)/,ia=/\?/,pb=/([?&])_=[^&]*/,qb=/^(\w+:)?\/\/([^\/?#]+)/,rb=/%20/g,sb=/#.*$/,Ea=c.fn.load;c.fn.extend({load:function(a,b,d){if(typeof a!=="string"&&Ea)return Ea.apply(this,arguments);else if(!this.length)return this;var e=a.indexOf(" ");if(e>=0){var f=a.slice(e,a.length);a=a.slice(0,e)}e="GET";if(b)if(c.isFunction(b)){d= +b;b=null}else if(typeof b==="object"){b=c.param(b,c.ajaxSettings.traditional);e="POST"}var h=this;c.ajax({url:a,type:e,dataType:"html",data:b,complete:function(k,l){if(l==="success"||l==="notmodified")h.html(f?c("
").append(k.responseText.replace(lb,"")).find(f):k.responseText);d&&h.each(d,[k.responseText,l,k])}});return this},serialize:function(){return c.param(this.serializeArray())},serializeArray:function(){return this.map(function(){return this.elements?c.makeArray(this.elements):this}).filter(function(){return this.name&& +!this.disabled&&(this.checked||mb.test(this.nodeName)||nb.test(this.type))}).map(function(a,b){var d=c(this).val();return d==null?null:c.isArray(d)?c.map(d,function(e){return{name:b.name,value:e}}):{name:b.name,value:d}}).get()}});c.each("ajaxStart ajaxStop ajaxComplete ajaxError ajaxSuccess ajaxSend".split(" "),function(a,b){c.fn[b]=function(d){return this.bind(b,d)}});c.extend({get:function(a,b,d,e){if(c.isFunction(b)){e=e||d;d=b;b=null}return c.ajax({type:"GET",url:a,data:b,success:d,dataType:e})}, +getScript:function(a,b){return c.get(a,null,b,"script")},getJSON:function(a,b,d){return c.get(a,b,d,"json")},post:function(a,b,d,e){if(c.isFunction(b)){e=e||d;d=b;b={}}return c.ajax({type:"POST",url:a,data:b,success:d,dataType:e})},ajaxSetup:function(a){c.extend(c.ajaxSettings,a)},ajaxSettings:{url:location.href,global:true,type:"GET",contentType:"application/x-www-form-urlencoded",processData:true,async:true,xhr:function(){return new E.XMLHttpRequest},accepts:{xml:"application/xml, text/xml",html:"text/html", +script:"text/javascript, application/javascript",json:"application/json, text/javascript",text:"text/plain",_default:"*/*"}},ajax:function(a){var b=c.extend(true,{},c.ajaxSettings,a),d,e,f,h=b.type.toUpperCase(),k=ob.test(h);b.url=b.url.replace(sb,"");b.context=a&&a.context!=null?a.context:b;if(b.data&&b.processData&&typeof b.data!=="string")b.data=c.param(b.data,b.traditional);if(b.dataType==="jsonp"){if(h==="GET")T.test(b.url)||(b.url+=(ia.test(b.url)?"&":"?")+(b.jsonp||"callback")+"=?");else if(!b.data|| +!T.test(b.data))b.data=(b.data?b.data+"&":"")+(b.jsonp||"callback")+"=?";b.dataType="json"}if(b.dataType==="json"&&(b.data&&T.test(b.data)||T.test(b.url))){d=b.jsonpCallback||"jsonp"+kb++;if(b.data)b.data=(b.data+"").replace(T,"="+d+"$1");b.url=b.url.replace(T,"="+d+"$1");b.dataType="script";var l=E[d];E[d]=function(m){f=m;c.handleSuccess(b,w,e,f);c.handleComplete(b,w,e,f);if(c.isFunction(l))l(m);else{E[d]=A;try{delete E[d]}catch(p){}}v&&v.removeChild(B)}}if(b.dataType==="script"&&b.cache===null)b.cache= +false;if(b.cache===false&&h==="GET"){var n=c.now(),s=b.url.replace(pb,"$1_="+n);b.url=s+(s===b.url?(ia.test(b.url)?"&":"?")+"_="+n:"")}if(b.data&&h==="GET")b.url+=(ia.test(b.url)?"&":"?")+b.data;b.global&&c.active++===0&&c.event.trigger("ajaxStart");n=(n=qb.exec(b.url))&&(n[1]&&n[1]!==location.protocol||n[2]!==location.host);if(b.dataType==="script"&&h==="GET"&&n){var v=u.getElementsByTagName("head")[0]||u.documentElement,B=u.createElement("script");if(b.scriptCharset)B.charset=b.scriptCharset;B.src= +b.url;if(!d){var D=false;B.onload=B.onreadystatechange=function(){if(!D&&(!this.readyState||this.readyState==="loaded"||this.readyState==="complete")){D=true;c.handleSuccess(b,w,e,f);c.handleComplete(b,w,e,f);B.onload=B.onreadystatechange=null;v&&B.parentNode&&v.removeChild(B)}}}v.insertBefore(B,v.firstChild);return A}var H=false,w=b.xhr();if(w){b.username?w.open(h,b.url,b.async,b.username,b.password):w.open(h,b.url,b.async);try{if(b.data!=null&&!k||a&&a.contentType)w.setRequestHeader("Content-Type", +b.contentType);if(b.ifModified){c.lastModified[b.url]&&w.setRequestHeader("If-Modified-Since",c.lastModified[b.url]);c.etag[b.url]&&w.setRequestHeader("If-None-Match",c.etag[b.url])}n||w.setRequestHeader("X-Requested-With","XMLHttpRequest");w.setRequestHeader("Accept",b.dataType&&b.accepts[b.dataType]?b.accepts[b.dataType]+", */*; q=0.01":b.accepts._default)}catch(G){}if(b.beforeSend&&b.beforeSend.call(b.context,w,b)===false){b.global&&c.active--===1&&c.event.trigger("ajaxStop");w.abort();return false}b.global&& +c.triggerGlobal(b,"ajaxSend",[w,b]);var M=w.onreadystatechange=function(m){if(!w||w.readyState===0||m==="abort"){H||c.handleComplete(b,w,e,f);H=true;if(w)w.onreadystatechange=c.noop}else if(!H&&w&&(w.readyState===4||m==="timeout")){H=true;w.onreadystatechange=c.noop;e=m==="timeout"?"timeout":!c.httpSuccess(w)?"error":b.ifModified&&c.httpNotModified(w,b.url)?"notmodified":"success";var p;if(e==="success")try{f=c.httpData(w,b.dataType,b)}catch(q){e="parsererror";p=q}if(e==="success"||e==="notmodified")d|| +c.handleSuccess(b,w,e,f);else c.handleError(b,w,e,p);d||c.handleComplete(b,w,e,f);m==="timeout"&&w.abort();if(b.async)w=null}};try{var g=w.abort;w.abort=function(){w&&g.call&&g.call(w);M("abort")}}catch(j){}b.async&&b.timeout>0&&setTimeout(function(){w&&!H&&M("timeout")},b.timeout);try{w.send(k||b.data==null?null:b.data)}catch(o){c.handleError(b,w,null,o);c.handleComplete(b,w,e,f)}b.async||M();return w}},param:function(a,b){var d=[],e=function(h,k){k=c.isFunction(k)?k():k;d[d.length]=encodeURIComponent(h)+ +"="+encodeURIComponent(k)};if(b===A)b=c.ajaxSettings.traditional;if(c.isArray(a)||a.jquery)c.each(a,function(){e(this.name,this.value)});else for(var f in a)ca(f,a[f],b,e);return d.join("&").replace(rb,"+")}});c.extend({active:0,lastModified:{},etag:{},handleError:function(a,b,d,e){a.error&&a.error.call(a.context,b,d,e);a.global&&c.triggerGlobal(a,"ajaxError",[b,a,e])},handleSuccess:function(a,b,d,e){a.success&&a.success.call(a.context,e,d,b);a.global&&c.triggerGlobal(a,"ajaxSuccess",[b,a])},handleComplete:function(a, +b,d){a.complete&&a.complete.call(a.context,b,d);a.global&&c.triggerGlobal(a,"ajaxComplete",[b,a]);a.global&&c.active--===1&&c.event.trigger("ajaxStop")},triggerGlobal:function(a,b,d){(a.context&&a.context.url==null?c(a.context):c.event).trigger(b,d)},httpSuccess:function(a){try{return!a.status&&location.protocol==="file:"||a.status>=200&&a.status<300||a.status===304||a.status===1223}catch(b){}return false},httpNotModified:function(a,b){var d=a.getResponseHeader("Last-Modified"),e=a.getResponseHeader("Etag"); +if(d)c.lastModified[b]=d;if(e)c.etag[b]=e;return a.status===304},httpData:function(a,b,d){var e=a.getResponseHeader("content-type")||"",f=b==="xml"||!b&&e.indexOf("xml")>=0;a=f?a.responseXML:a.responseText;f&&a.documentElement.nodeName==="parsererror"&&c.error("parsererror");if(d&&d.dataFilter)a=d.dataFilter(a,b);if(typeof a==="string")if(b==="json"||!b&&e.indexOf("json")>=0)a=c.parseJSON(a);else if(b==="script"||!b&&e.indexOf("javascript")>=0)c.globalEval(a);return a}});if(E.ActiveXObject)c.ajaxSettings.xhr= +function(){if(E.location.protocol!=="file:")try{return new E.XMLHttpRequest}catch(a){}try{return new E.ActiveXObject("Microsoft.XMLHTTP")}catch(b){}};c.support.ajax=!!c.ajaxSettings.xhr();var da={},tb=/^(?:toggle|show|hide)$/,ub=/^([+\-]=)?([\d+.\-]+)(.*)$/,aa,na=[["height","marginTop","marginBottom","paddingTop","paddingBottom"],["width","marginLeft","marginRight","paddingLeft","paddingRight"],["opacity"]];c.fn.extend({show:function(a,b,d){if(a||a===0)return this.animate(S("show",3),a,b,d);else{a= +0;for(b=this.length;a=0;e--)if(d[e].elem===this){b&&d[e](true);d.splice(e,1)}});b||this.dequeue();return this}});c.each({slideDown:S("show",1),slideUp:S("hide",1),slideToggle:S("toggle",1),fadeIn:{opacity:"show"},fadeOut:{opacity:"hide"}},function(a,b){c.fn[a]=function(d,e,f){return this.animate(b, +d,e,f)}});c.extend({speed:function(a,b,d){var e=a&&typeof a==="object"?c.extend({},a):{complete:d||!d&&b||c.isFunction(a)&&a,duration:a,easing:d&&b||b&&!c.isFunction(b)&&b};e.duration=c.fx.off?0:typeof e.duration==="number"?e.duration:e.duration in c.fx.speeds?c.fx.speeds[e.duration]:c.fx.speeds._default;e.old=e.complete;e.complete=function(){e.queue!==false&&c(this).dequeue();c.isFunction(e.old)&&e.old.call(this)};return e},easing:{linear:function(a,b,d,e){return d+e*a},swing:function(a,b,d,e){return(-Math.cos(a* +Math.PI)/2+0.5)*e+d}},timers:[],fx:function(a,b,d){this.options=b;this.elem=a;this.prop=d;if(!b.orig)b.orig={}}});c.fx.prototype={update:function(){this.options.step&&this.options.step.call(this.elem,this.now,this);(c.fx.step[this.prop]||c.fx.step._default)(this)},cur:function(){if(this.elem[this.prop]!=null&&(!this.elem.style||this.elem.style[this.prop]==null))return this.elem[this.prop];var a=parseFloat(c.css(this.elem,this.prop));return a&&a>-1E4?a:0},custom:function(a,b,d){function e(h){return f.step(h)} +this.startTime=c.now();this.start=a;this.end=b;this.unit=d||this.unit||"px";this.now=this.start;this.pos=this.state=0;var f=this;a=c.fx;e.elem=this.elem;if(e()&&c.timers.push(e)&&!aa)aa=setInterval(a.tick,a.interval)},show:function(){this.options.orig[this.prop]=c.style(this.elem,this.prop);this.options.show=true;this.custom(this.prop==="width"||this.prop==="height"?1:0,this.cur());c(this.elem).show()},hide:function(){this.options.orig[this.prop]=c.style(this.elem,this.prop);this.options.hide=true; +this.custom(this.cur(),0)},step:function(a){var b=c.now(),d=true;if(a||b>=this.options.duration+this.startTime){this.now=this.end;this.pos=this.state=1;this.update();this.options.curAnim[this.prop]=true;for(var e in this.options.curAnim)if(this.options.curAnim[e]!==true)d=false;if(d){if(this.options.overflow!=null&&!c.support.shrinkWrapBlocks){var f=this.elem,h=this.options;c.each(["","X","Y"],function(l,n){f.style["overflow"+n]=h.overflow[l]})}this.options.hide&&c(this.elem).hide();if(this.options.hide|| +this.options.show)for(var k in this.options.curAnim)c.style(this.elem,k,this.options.orig[k]);this.options.complete.call(this.elem)}return false}else{a=b-this.startTime;this.state=a/this.options.duration;b=this.options.easing||(c.easing.swing?"swing":"linear");this.pos=c.easing[this.options.specialEasing&&this.options.specialEasing[this.prop]||b](this.state,a,0,1,this.options.duration);this.now=this.start+(this.end-this.start)*this.pos;this.update()}return true}};c.extend(c.fx,{tick:function(){for(var a= +c.timers,b=0;b-1;e={};var s={};if(n)s=f.position();k=n?s.top:parseInt(k,10)||0;l=n?s.left:parseInt(l,10)||0;if(c.isFunction(b))b=b.call(a,d,h);if(b.top!=null)e.top=b.top-h.top+k;if(b.left!=null)e.left=b.left-h.left+l;"using"in b?b.using.call(a, +e):f.css(e)}};c.fn.extend({position:function(){if(!this[0])return null;var a=this[0],b=this.offsetParent(),d=this.offset(),e=Fa.test(b[0].nodeName)?{top:0,left:0}:b.offset();d.top-=parseFloat(c.css(a,"marginTop"))||0;d.left-=parseFloat(c.css(a,"marginLeft"))||0;e.top+=parseFloat(c.css(b[0],"borderTopWidth"))||0;e.left+=parseFloat(c.css(b[0],"borderLeftWidth"))||0;return{top:d.top-e.top,left:d.left-e.left}},offsetParent:function(){return this.map(function(){for(var a=this.offsetParent||u.body;a&&!Fa.test(a.nodeName)&& +c.css(a,"position")==="static";)a=a.offsetParent;return a})}});c.each(["Left","Top"],function(a,b){var d="scroll"+b;c.fn[d]=function(e){var f=this[0],h;if(!f)return null;if(e!==A)return this.each(function(){if(h=ea(this))h.scrollTo(!a?e:c(h).scrollLeft(),a?e:c(h).scrollTop());else this[d]=e});else return(h=ea(f))?"pageXOffset"in h?h[a?"pageYOffset":"pageXOffset"]:c.support.boxModel&&h.document.documentElement[d]||h.document.body[d]:f[d]}});c.each(["Height","Width"],function(a,b){var d=b.toLowerCase(); +c.fn["inner"+b]=function(){return this[0]?parseFloat(c.css(this[0],d,"padding")):null};c.fn["outer"+b]=function(e){return this[0]?parseFloat(c.css(this[0],d,e?"margin":"border")):null};c.fn[d]=function(e){var f=this[0];if(!f)return e==null?null:this;if(c.isFunction(e))return this.each(function(h){var k=c(this);k[d](e.call(this,h,k[d]()))});return c.isWindow(f)?f.document.compatMode==="CSS1Compat"&&f.document.documentElement["client"+b]||f.document.body["client"+b]:f.nodeType===9?Math.max(f.documentElement["client"+ +b],f.body["scroll"+b],f.documentElement["scroll"+b],f.body["offset"+b],f.documentElement["offset"+b]):e===A?parseFloat(c.css(f,d)):this.css(d,typeof e==="string"?e:e+"px")}})})(window); + + +var Percona={ssl:false,host:"www.percona.com"}; +Percona.getRecentServerVersion=function(c){function f(){if(!(++h>1)){b=window.jQuery.noConflict(true);g(b)}}function g(i){var j=function(d){if(d(c).get(0))d.get("http"+(Percona.ssl?"s":"")+"://"+Percona.host+"/ajax/server-version/?callback=?",{},function(e){"object"==typeof e&&"string"==typeof e.recentServerVersion&&d(c).text(" "+e.recentServerVersion)},"jsonp")};i(document).ready(function(){j(b)})}"string"!=typeof c&&alert("Percona.getRecentServerVersion: missed or wrong selector!");var b;if(window.jQuery=== +undefined||window.jQuery.fn.jquery!=="1.4.2"){var a=document.createElement("script");a.setAttribute("type","text/javascript");a.setAttribute("src","http"+(Percona.ssl?"s":"")+"://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js");a.onload=f;a.onreadystatechange=function(){if(this.readyState=="complete"||this.readyState=="loaded")f()};(document.getElementsByTagName("head")[0]||document.documentElement).appendChild(a)}else{b=window.jQuery;g()}var h=0}; + + +window.jQuery(function(a){function k(b,c,d){var e=new Date;e.setDate(e.getDate()+d);document.cookie=b+"="+escape(c)+(d==null?"":";path=/;expires="+e.toUTCString())}function o(b){if(document.cookie.length>0){c_start=document.cookie.indexOf(b+"=");if(c_start!=-1){c_start=c_start+b.length+1;c_end=document.cookie.indexOf(";",c_start);if(c_end==-1)c_end=document.cookie.length;return unescape(document.cookie.substring(c_start,c_end))}}return""}function j(){a(".navi-dropdown").hide();a("#menu div").unbind("mouseover"); +a(".dropdown").unbind("mouseover");a(".dropdown").unbind("mouseout");a("#search-dropdown").hide();a("#searchlink-anchor").unbind("mouseover");a("#searchlink-anchor").unbind("mouseout");a("#search-dropdown").unbind("mouseover");a("#search-dropdown").unbind("mouseout")}function f(){if(NAVI.CloseTimer!=null){window.clearTimeout(NAVI.CloseTimer);NAVI.CloseTimer=null}}function g(){if(NAVI.CloseTimer==null)NAVI.CloseTimer=window.setTimeout(j,300)}function l(){a(".navi-dropdown").hide();a("#menu div").unbind("mouseover"); +a(".dropdown").unbind("mouseover");a(".dropdown").unbind("mouseout");a("#search-dropdown").hide();a("#searchlink-anchor").unbind("mouseover");a("#searchlink-anchor").unbind("mouseout");a("#search-dropdown").unbind("mouseover");a("#search-dropdown").unbind("mouseout")}function m(){if(SEARCH.CloseTimer!=null){window.clearTimeout(SEARCH.CloseTimer);SEARCH.CloseTimer=null}}a.ajaxSetup({type:"post",dataType:"json"});NAVI={};NAVI.CloseTimer=null;NAVI.Open=function(b,c){f();j();m();l();if("h"!=c){var d= +a("#navilink-span-"+b).offset();c=="r"?a("#navi-dropdown-"+b).css({position:"absolute",left:d.left+a("#navilink-span-"+b).width()+2-a("#navi-dropdown-"+b).width()+"px",top:d.top+32+"px"}):a("#navi-dropdown-"+b).css({position:"absolute",left:d.left+"px",top:d.top+32+"px"});a("#navi-dropdown-"+b).show();a("#navilink-span-"+b).bind("mouseover",f);a("#navilink-span-"+b).bind("mouseout",g);a("#navi-dropdown-"+b).bind("mouseover",f);a("#navi-dropdown-"+b).bind("mouseout",g)}};SUBNAVI={};SUBNAVI.Open=function(b){if(a("#sidesubnavi-"+ +b+":hidden").length){a(".sidesubnavi").hide();a("#sidesubnavi-"+b).show();return false}else return true};SEARCH={};SEARCH.CloseTimer=null;SEARCH.Open=function(){f();j();m();l();var b=a("#searchlink-anchor").offset();a("#search-dropdown").css({position:"absolute",left:b.left-a("#search-dropdown").width()+40+"px",top:b.top+36+"px"});a("#search-dropdown").show();a("#searchlink-anchor").bind("mouseover",f);a("#searchlink-anchor").bind("mouseout",g);a("#search-dropdown").bind("mouseover",f);a("#search-dropdown").bind("mouseout", +g);a("#search-input")[0].focus()};menuImg1=new Image;menuImg1.src="http://s1.percona.com/ui-dropdown-header-l.png";menuImg2=new Image;menuImg2.src="http://s2.percona.com/ui-dropdown-header-r.png";menuImg3=new Image;menuImg3.src="http://s3.percona.com/ui-dropdown-header-search.png";menuImg4=new Image;menuImg4.src="http://s0.percona.com/ui-dropdown-bg.png";menuImg5=new Image;menuImg5.src="http://s1.percona.com/ui-dropdown-footer.png";var p=function(b){var c={},d={},e=0;b(".mail_subst").each(function(h,i){d["msubst_"+h]=i;c["msubst_"+ +h]=i.title;e++});0!=e&&b.post("/ajax/mail-subst/",c,function(h){b.each(h,function(i,n){b(d[i]).attr("title","").html(''+n+"")})})};a(document).ready(function(b){b("input:text").change(function(){this.value=b.trim(this.value)});p(b)});DOWNLOADSIGNUP={url:null};DOWNLOADSIGNUP.openDialog=function(b){if(o("nodownloadsignup")=="1"||"undefined"==typeof a("#downloadsignup").dialog)return true;DOWNLOADSIGNUP.url=b;a("#downloadsignup").dialog({dialogClass:"downloadsignupdialog", +resizable:false,bgiframe:true,modal:true,width:"600px",buttons:{"Sign up":function(){if(a("#downloadsignup-name").val()=="")alert("Please enter at least your name and e-mail address. All other fields are optional.");else if(a("#downloadsignup-email").val()=="")alert("Please enter at least your name and e-mail address. All other fields are optional.");else{a(".ui-dialog-buttonpane").hide();a("#downloadsignup-form").hide();a("#downloadsignup-progress").show();a.ajax({url:"/ajax/subscribe/",data:{name:a("#downloadsignup-name").val(), +company:a("#downloadsignup-company").val(),email:a("#downloadsignup-email").val(),phone:a("#downloadsignup-phone").val(),city:a("#downloadsignup-city").val(),country:a("#downloadsignup-country").val(),inproduction:a("input[name=downloadsignup-inproduction]:checked").length?a("input[name=downloadsignup-inproduction]:checked").val():"",discover:a("input[name=downloadsignup-discover]:checked").length?a("input[name=downloadsignup-discover]:checked").val():"",subscribe:a("input[name=downloadsignup-subscribe]:checked").length, +salescontact:a("input[name=downloadsignup-salescontact]:checked").length,url:DOWNLOADSIGNUP.url},success:function(c){if(c.status=="1"){a("#downloadsignup").remove();a(this).dialog("close");k("nodownloadsignup","1",3650);window.location.href=DOWNLOADSIGNUP.url}else{a(".ui-dialog-buttonpane").show();a("#downloadsignup-form").show();a("#downloadsignup-progress").hide();c.error!=null?alert("ERROR: "+c.error):alert("Uh-oh, an unknown error saving data has occured.")}},error:function(){a(".ui-dialog-buttonpane").show(); +a("#downloadsignup-form").show();a("#downloadsignup-progress").hide();alert("Uh-oh, an unknown error sending data has occured.")}})}},"Not now, download only":function(){a(this).dialog("close")},"Download & don't ask me again":function(){k("nodownloadsignup","1",3650);a(this).dialog("close")}},close:function(){window.location.href=DOWNLOADSIGNUP.url}});a("#downloadsignup").dialog("open");return false};a(document).ready(function(){a("a.downloadsignup").click(function(){return DOWNLOADSIGNUP.openDialog(this.href)})}); +FRONTPAGEBOXES={};FRONTPAGEBOXES.select=function(b){a(".frontpage-boxes-selector-item").removeClass("selected");a("#boxes-select-"+b).addClass("selected");a(".frontpage-box").hide();a("#boxes-"+b).show()}}); + + +(function(a){function b(){el.offset();var c=a(window).scrollTop();c
' + ); + var sidebarbutton = $('#sidebarbutton'); + light_color = sidebarbutton.css('background-color'); + // find the height of the viewport to center the '<<' in the page + var viewport_height; + if (window.innerHeight) + viewport_height = window.innerHeight; + else + viewport_height = $(window).height(); + sidebarbutton.find('span').css({ + 'display': 'block', + 'margin-top': (viewport_height - sidebar.position().top - 20) / 2 + }); + + sidebarbutton.click(toggle_sidebar); + sidebarbutton.attr('title', _('Collapse sidebar')); + sidebarbutton.css({ + 'color': '#FFFFFF', + 'border-left': '1px solid ' + dark_color, + 'font-size': '1.2em', + 'cursor': 'pointer', + 'height': bodywrapper.height(), + 'padding-top': '1px', + 'margin-left': ssb_width_expanded - 12 + }); + + sidebarbutton.hover( + function () { + $(this).css('background-color', dark_color); + }, + function () { + $(this).css('background-color', light_color); + } + ); + } + + function set_position_from_cookie() { + if (!document.cookie) + return; + var items = document.cookie.split(';'); + for(var k=0; k`_. -See also "BUGS" for more information on filing bugs and getting help. +See also ``BUGS`` for more information on filing bugs and getting help. -*********** DESCRIPTION -*********** +=========== -pt-archiver is the tool I use to archive tables as described in -`http://tinyurl.com/mysql-archiving `_. The goal is a low-impact, forward-only -job to nibble old data out of the table without impacting OLTP queries much. +:program:`pt-archiver` is the tool I use to archive tables as described in +`http://tinyurl.com/mysql-archiving `_. + +The goal is a low-impact, forward-only job to nibble old data out of the table without impacting ``OLTP`` queries much. + You can insert the data into another table, which need not be on the same -server. You can also write it to a file in a format suitable for LOAD DATA -INFILE. Or you can do neither, in which case it's just an incremental DELETE. +server. You can also write it to a file in a format suitable for ``LOAD DATA +INFILE``. Or you can do neither, in which case it's just an incremental ``DELETE``. -pt-archiver is extensible via a plugin mechanism. You can inject your own -code to add advanced archiving logic that could be useful for archiving +:program:`pt-archiver` is extensible via a plugin mechanism. You can inject your own code to add advanced archiving logic that could be useful for archiving dependent data, applying complex business rules, or building a data warehouse during the archiving process. You need to choose values carefully for some options. The most important are -"--limit", "--retries", and "--txn-size". +:option:`--limit`, :option:`--retries`, and :option:`--txn-size`. The strategy is to find the first row(s), then scan some index forward-only to find more rows efficiently. Each subsequent query should not scan the entire table; it should seek into the index, then scan until it finds more archivable -rows. Specifying the index with the 'i' part of the "--source" argument can -be crucial for this; use "--dry-run" to examine the generated queries and be -sure to EXPLAIN them to see if they are efficient (most of the time you probably -want to scan the PRIMARY key, which is the default). Even better, profile -pt-archiver with pt-query-profiler and make sure it is not scanning the whole +rows. Specifying the index with the 'i' part of the :option:`--source` argument can be crucial for this; use :option:`--dry-run` to examine the generated queries and be sure to ``EXPLAIN`` them to see if they are efficient (most of the time you probably want to scan the ``PRIMARY`` key, which is the default). Even better, profile :program:`pt-archiver` with :program:`pt-query-profiler` and make sure it is not scanning the whole table every query. You can disable the seek-then-scan optimizations partially or wholly with -"--no-ascend" and "--ascend-first". Sometimes this may be more efficient -for multi-column keys. Be aware that pt-archiver is built to start at the -beginning of the index it chooses and scan it forward-only. This might result -in long table scans if you're trying to nibble from the end of the table by an -index other than the one it prefers. See "--source" and read the -documentation on the \ ``i``\ part if this applies to you. +:option:`--no-ascend` and :option:`--ascend-first`. Sometimes this may be more efficient for multi-column keys. Be aware that :program:`pt-archiver` is built to start at the beginning of the index it chooses and scan it forward-only. This might result in long table scans if you're trying to nibble from the end of the table by an index other than the one it prefers. See :option:`--source` and read the documentation on the \ ``i``\ part if this applies to you. -****** OUTPUT -****** +====== -If you specify "--progress", the output is a header row, plus status output -at intervals. Each row in the status output lists the current date and time, -how many seconds pt-archiver has been running, and how many rows it has +If you specify :option:`--progress`, the output is a header row, plus status output at intervals. Each row in the status output lists the current date and time, how many seconds :program:`pt-archiver`; has been running, and how many rows it has archived. -If you specify "--statistics", \ ``pt-archiver``\ outputs timing and other -information to help you identify which part of your archiving process takes the -most time. +If you specify :option:`--statistics`, \ ``pt-archiver``\ outputs timing and other information to help you identify which part of your archiving process takes the most time. -************** ERROR-HANDLING -************** +============== -pt-archiver tries to catch signals and exit gracefully; for example, if you -send it SIGTERM (Ctrl-C on UNIX-ish systems), it will catch the signal, print a -message about the signal, and exit fairly normally. It will not execute -"--analyze" or "--optimize", because these may take a long time to finish. -It will run all other code normally, including calling after_finish() on any -plugins (see "EXTENDING"). +:program:`pt-archiver` tries to catch signals and exit gracefully; for example, if you send it ``SIGTERM`` (``Ctrl-C`` on UNIX-ish systems), it will catch the signal, print a message about the signal, and exit fairly normally. It will not execute :option:`--analyze` or :option:`--optimize`, because these may take a long time to finish. It will run all other code normally, including calling ``after_finish()`` on any plugins (see "EXTENDING"). In other words, a signal, if caught, will break out of the main archiving loop and skip optimize/analyze. -******* OPTIONS -******* +======= -Specify at least one of "--dest", "--file", or "--purge". +Specify at least one of :option:`--dest`, :option:`--file`, or :option:`--purge`. -"--ignore" and "--replace" are mutually exclusive. + * :option:`--ignore` and :option:`--replace` are mutually exclusive. -"--txn-size" and "--commit-each" are mutually exclusive. + * :option:`--txn-size` and :option:`--commit-each` are mutually exclusive. -"--low-priority-insert" and "--delayed-insert" are mutually exclusive. + * :option:`--low-priority-insert` and :option:`--delayed-insert` are mutually exclusive. -"--share-lock" and "--for-update" are mutually exclusive. + * :option:`--share-lock` and :option:`--for-update` are mutually exclusive. -"--analyze" and "--optimize" are mutually exclusive. + * :option:`--analyze` and :option:`--optimize` are mutually exclusive. -"--no-ascend" and "--no-delete" are mutually exclusive. + * :option:`--no-ascend` and :option:`--no-delete` are mutually exclusive. DSN values in "--dest" default to values from "--source" if COPY is yes. ---analyze +.. option:: --analyze - type: string + * Type: + ``STRING`` - Run ANALYZE TABLE afterwards on "--source" and/or "--dest". + Run ANALYZE TABLE afterwards on "--source" and/or "--dest". - Runs ANALYZE TABLE after finishing. The argument is an arbitrary string. If it - contains the letter 's', the source will be analyzed. If it contains 'd', the - destination will be analyzed. You can specify either or both. For example, the - following will analyze both: + Runs ANALYZE TABLE after finishing. The argument is an arbitrary string. If it contains the letter 's', the source will be analyzed. If it contains 'd', the destination will be analyzed. You can specify either or both. For example, the following will analyze both: + + .. code-block:: perl - - .. code-block:: perl - - --analyze=ds - - - See `http://dev.mysql.com/doc/en/analyze-table.html `_ for details on ANALYZE + --analyze=ds + See `http://dev.mysql.com/doc/en/analyze-table.html `_ for details on ANALYZE TABLE. +.. option:: --ascend-first + + Ascend only first column of index. + + If you do want to use the ascending index optimization (see :option:`--no-ascend`), but do not want to incur the overhead of ascending a large multi-column index, you can use this option to tell pt-archiver to ascend only the leftmost column of the index. This can provide a significant performance boost over not ascending the index at all, while avoiding the cost of ascending the whole index. + + See "EXTENDING" for a discussion of how this interacts with plugins. + +.. option:: --ask-pass + + Prompt for a password when connecting to |MySQL|. + +.. option:: --buffer + + Buffer output to :option:`--file` and flush at commit. + + Disables autoflushing to :option:`--file` and flushes :option:`--file` to disk only when a transaction commits. This typically means the file is block-flushed by the operating system, so there may be some implicit flushes to disk between commits as well. The default is to flush :option:`--file` to disk after every row. + + The danger is that a crash might cause lost data. + + The performance increase I have seen from using :option:`--buffer` is around 5 to 15 percent. Your mileage may vary. ---ascend-first +.. option:: --bulk-delete - Ascend only first column of index. - - If you do want to use the ascending index optimization (see "--no-ascend"), - but do not want to incur the overhead of ascending a large multi-column index, - you can use this option to tell pt-archiver to ascend only the leftmost column - of the index. This can provide a significant performance boost over not - ascending the index at all, while avoiding the cost of ascending the whole - index. - - See "EXTENDING" for a discussion of how this interacts with plugins. - - - ---ask-pass - - Prompt for a password when connecting to MySQL. - - - ---buffer - - Buffer output to "--file" and flush at commit. - - Disables autoflushing to "--file" and flushes "--file" to disk only when a - transaction commits. This typically means the file is block-flushed by the - operating system, so there may be some implicit flushes to disk between - commits as well. The default is to flush "--file" to disk after every row. - - The danger is that a crash might cause lost data. - - The performance increase I have seen from using "--buffer" is around 5 to 15 - percent. Your mileage may vary. - - - ---bulk-delete - - Delete each chunk with a single statement (implies "--commit-each"). - - Delete each chunk of rows in bulk with a single \ ``DELETE``\ statement. The + Delete each chunk with a single statement (implies :option:`--commit-each`). + + Delete each chunk of rows in bulk with a single ``DELETE`` statement. The statement deletes every row between the first and last row of the chunk, - inclusive. It implies "--commit-each", since it would be a bad idea to - \ ``INSERT``\ rows one at a time and commit them before the bulk \ ``DELETE``\ . + inclusive. It implies :option:`--commit-each`, since it would be a bad idea to + ``INSERT`` rows one at a time and commit them before the bulk ``DELETE``. - The normal method is to delete every row by its primary key. Bulk deletes might - be a lot faster. \ **They also might not be faster**\ if you have a complex - \ ``WHERE``\ clause. + The normal method is to delete every row by its primary key. Bulk deletes might be a lot faster. **They also might not be faster** if you have a complex + ``WHERE`` clause. - This option completely defers all \ ``DELETE``\ processing until the chunk of rows - is finished. If you have a plugin on the source, its \ ``before_delete``\ method - will not be called. Instead, its \ ``before_bulk_delete``\ method is called later. - - \ **WARNING**\ : if you have a plugin on the source that sometimes doesn't return - true from \ ``is_archivable()``\ , you should use this option only if you understand - what it does. If the plugin instructs \ ``pt-archiver``\ not to archive a row, - it will still be deleted by the bulk delete! + This option completely defers all ``DELETE`` processing until the chunk of rows is finished. If you have a plugin on the source, its ``before_delete`` method will not be called. Instead, its ``before_bulk_delete`` method is called later. + **WARNING**: if you have a plugin on the source that sometimes doesn't return + true from ``is_archivable()``, you should use this option only if you understand what it does. If the plugin instructs ``pt-archiver`` not to archive a row, it will still be deleted by the bulk delete! +.. option:: --[no]bulk-delete-limit + + Default: yes + + Add :option:`--limit` to :option:`--bulk-delete` statement. + + This is an advanced option and you should not disable it unless you know what + you are doing and why! By default, :option:`--bulk-delete` appends a "--limit" clause to the bulk delete SQL statement. In certain cases, this clause can be omitted by specifying ``--no-bulk-delete-limit``. :option:`--limit` must still be specified. ---[no]bulk-delete-limit +.. option:: --bulk-insert - default: yes + Insert each chunk with ``LOAD DATA INFILE`` (implies :option:`--bulk-delete` :option:`--commit-each`). - Add "--limit" to "--bulk-delete" statement. + Insert each chunk of rows with ``LOAD DATA LOCAL INFILE``. This may be much faster than inserting a row at a time with ``INSERT`` statements. It is implemented by creating a temporary file for each chunk of rows, and writing the rows to this file instead of inserting them. When the chunk is finished, it uploads the rows. - This is an advanced option and you should not disable it unless you know what - you are doing and why! By default, "--bulk-delete" appends a "--limit" - clause to the bulk delete SQL statement. In certain cases, this clause can be - omitted by specifying \ ``--no-bulk-delete-limit``\ . "--limit" must still be - specified. - - - ---bulk-insert - - Insert each chunk with LOAD DATA INFILE (implies "--bulk-delete" "--commit-each"). - - Insert each chunk of rows with \ ``LOAD DATA LOCAL INFILE``\ . This may be much - faster than inserting a row at a time with \ ``INSERT``\ statements. It is - implemented by creating a temporary file for each chunk of rows, and writing the - rows to this file instead of inserting them. When the chunk is finished, it - uploads the rows. - - To protect the safety of your data, this option forces bulk deletes to be used. - It would be unsafe to delete each row as it is found, before inserting the rows - into the destination first. Forcing bulk deletes guarantees that the deletion - waits until the insertion is successful. - - The "--low-priority-insert", "--replace", and "--ignore" options work + To protect the safety of your data, this option forces bulk deletes to be used. It would be unsafe to delete each row as it is found, before inserting the rows into the destination first. Forcing bulk deletes guarantees that the deletion waits until the insertion is successful. + + The "--low-priority-insert", "--replace", and "--ignore" options work with this option, but "--delayed-insert" does not. - +.. option:: --charset + + Short form: ``-A`; Type: string + + Default character set. If the value is ``utf8``, sets Perl's binmode on + ``STDOUT`` to ``utf8``, passes the ``mysql_enable_utf8`` option to ``DBD::mysql``, and runs ``SET NAMES UTF8`` after connecting to |MySQL|. Any other value sets binmode on ``STDOUT`` without the ``utf8`` layer, and runs ``SET NAMES`` after connecting to |MySQL|. + + See also :option:`--[no]check-charset`. + +.. option:: --[no]check-charset + + Default: yes + + Ensure connection and table character sets are the same. Disabling this check may cause text to be erroneously converted from one character set to another (usually from ``utf8`` to ``latin1``) which may cause data loss or mojibake. Disabling this check may be useful or necessary when character set conversions are intended. ---charset - - short form: -A; type: string - - Default character set. If the value is utf8, sets Perl's binmode on - STDOUT to utf8, passes the mysql_enable_utf8 option to DBD::mysql, and runs SET - NAMES UTF8 after connecting to MySQL. Any other value sets binmode on STDOUT - without the utf8 layer, and runs SET NAMES after connecting to MySQL. - - See also "--[no]check-charset". - +.. option:: --[no]check-columns + Default: yes + + Ensure :option:`--source` and :option:`--dest` have same columns. + + Enabled by default; causes :program:`pt-archiver` to check that the source and destination tables have the same columns. It does not check column order, data type, etc. + + It just checks that all columns in the source exist in the destination and vice versa. If there are any differences, :program:`pt-archiver` will exit with an error. + + To disable this check, specify :option:`--no-check-columns`. + +.. option:: --check-interval + + Type: time; Default: 1s + + How often to check for slave lag if :option:`--check-slave-lag` is given. ---[no]check-charset +.. option:: --check-slave-lag - default: yes + type: string - Ensure connection and table character sets are the same. Disabling this check - may cause text to be erroneously converted from one character set to another - (usually from utf8 to latin1) which may cause data loss or mojibake. Disabling - this check may be useful or necessary when character set conversions are - intended. + Pause archiving until the specified DSN's slave lag is less than :option:`--max-lag`. - - ---[no]check-columns - - default: yes - - Ensure "--source" and "--dest" have same columns. - - Enabled by default; causes pt-archiver to check that the source and destination - tables have the same columns. It does not check column order, data type, etc. - It just checks that all columns in the source exist in the destination and - vice versa. If there are any differences, pt-archiver will exit with an - error. - - To disable this check, specify --no-check-columns. - - - ---check-interval - - type: time; default: 1s - - How often to check for slave lag if "--check-slave-lag" is given. - - - ---check-slave-lag - - type: string - - Pause archiving until the specified DSN's slave lag is less than "--max-lag". - - - ---columns +.. option:: --columns short form: -c; type: array @@ -358,9 +272,7 @@ DSN values in "--dest" default to values from "--source" if COPY is yes. See also "--primary-key-only". - - ---commit-each +.. option:: --commit-each Commit each set of fetched and archived rows (disables "--txn-size"). @@ -379,27 +291,21 @@ DSN values in "--dest" default to values from "--source" if COPY is yes. more rows. It has held open a transaction for a very long time, only to determine it is finished anyway. You can use "--commit-each" to avoid this. - - ---config +.. option:: --config type: Array Read this comma-separated list of config files; if specified, this must be the first option on the command line. - - ---delayed-insert +.. option:: --delayed-insert Add the DELAYED modifier to INSERT statements. Adds the DELAYED modifier to INSERT or REPLACE statements. See `http://dev.mysql.com/doc/en/insert.html `_ for details. - - ---dest +.. option:: --dest type: DSN @@ -427,18 +333,14 @@ DSN values in "--dest" default to values from "--source" if COPY is yes. When pt-archiver connects to "--dest", host2, it will connect via the "--source", host1, socket defined in host1.cnf. - - ---dry-run +.. option:: --dry-run Print queries and exit without doing anything. Causes pt-archiver to exit after printing the filename and SQL statements it will use. - - ---file +.. option:: --file type: string @@ -446,8 +348,7 @@ DSN values in "--dest" default to values from "--source" if COPY is yes. Filename to write archived rows to. A subset of MySQL's DATE_FORMAT() formatting codes are allowed in the filename, as follows: - - + .. code-block:: perl %d Day of the month, numeric (01..31) @@ -459,8 +360,7 @@ DSN values in "--dest" default to values from "--source" if COPY is yes. You can use the following extra format codes too: - - + .. code-block:: perl %D Database name @@ -469,8 +369,7 @@ DSN values in "--dest" default to values from "--source" if COPY is yes. Example: - - .. code-block:: perl + .. code-block:: perl --file '/var/log/archive/%Y-%m-%d-%D.%t' @@ -484,17 +383,13 @@ DSN values in "--dest" default to values from "--source" if COPY is yes. If you want a column header at the top of the file, see "--header". The file is auto-flushed by default; see "--buffer". - - ---for-update +.. option:: --for-update Adds the FOR UPDATE modifier to SELECT statements. For details, see `http://dev.mysql.com/doc/en/innodb-locking-reads.html `_. - - ---header +.. option:: --header Print column header at top of "--file". @@ -502,39 +397,29 @@ DSN values in "--dest" default to values from "--source" if COPY is yes. file exists, does not write headers; this keeps the file loadable with LOAD DATA INFILE in case you append more output to it. - - ---help +.. option:: --help Show help and exit. - - ---high-priority-select +.. option:: --high-priority-select Adds the HIGH_PRIORITY modifier to SELECT statements. See `http://dev.mysql.com/doc/en/select.html `_ for details. - - ---host +.. option:: --host short form: -h; type: string Connect to host. - - ---ignore +.. option:: --ignore Use IGNORE for INSERT statements. Causes INSERTs into "--dest" to be INSERT IGNORE. - - ---limit +.. option:: --limit type: int; default: 1 @@ -547,34 +432,26 @@ DSN values in "--dest" default to values from "--source" if COPY is yes. storage engine, transaction isolation level, and options such as "--for-update". - - ---local +.. option:: --local Do not write OPTIMIZE or ANALYZE queries to binlog. Adds the NO_WRITE_TO_BINLOG modifier to ANALYZE and OPTIMIZE queries. See "--analyze" for details. - - ---low-priority-delete +.. option:: --low-priority-delete Adds the LOW_PRIORITY modifier to DELETE statements. See `http://dev.mysql.com/doc/en/delete.html `_ for details. - - ---low-priority-insert +.. option:: --low-priority-insert Adds the LOW_PRIORITY modifier to INSERT or REPLACE statements. See `http://dev.mysql.com/doc/en/insert.html `_ for details. - - ---max-lag +.. option:: --max-lag type: time; default: 1s @@ -588,9 +465,7 @@ DSN values in "--dest" default to values from "--source" if COPY is yes. This option may eliminate the need for "--sleep" or "--sleep-coef". - - ---no-ascend +.. option:: --no-ascend Do not use ascending index optimization. @@ -627,9 +502,7 @@ DSN values in "--dest" default to values from "--source" if COPY is yes. See also "--ascend-first". See "EXTENDING" for a discussion of how this interacts with plugins. - - ---no-delete +.. option:: --no-delete Do not delete archived rows. @@ -640,9 +513,7 @@ DSN values in "--dest" default to values from "--source" if COPY is yes. anyway, even though \ ``pt-archiver``\ will not execute the delete. See "EXTENDING" for more on plugins. - - ---optimize +.. option:: --optimize type: string @@ -653,16 +524,14 @@ DSN values in "--dest" default to values from "--source" if COPY is yes. TABLE. - ---password +.. option:: --password short form: -p; type: string Password to use when connecting. - ---pid +.. option:: --pid type: string @@ -671,9 +540,7 @@ DSN values in "--dest" default to values from "--source" if COPY is yes. exits. The program checks for the existence of the PID file when starting; if it exists and the process with the matching PID exists, the program exits. - - ---plugin +.. option:: --plugin type: string @@ -691,17 +558,13 @@ DSN values in "--dest" default to values from "--source" if COPY is yes. The \ ``statistics(\%stats, $time)``\ method gets a hashref of the statistics collected by the archiving job, and the time the whole job started. - - ---port +.. option:: --port short form: -P; type: int Port number to use for connection. - - ---primary-key-only +.. option:: --primary-key-only Primary key columns only. @@ -710,9 +573,7 @@ DSN values in "--dest" default to values from "--source" if COPY is yes. when only the primary key columns are needed for \ ``DELETE``\ statements. See also "--purge". - - ---progress +.. option:: --progress type: int @@ -720,9 +581,7 @@ DSN values in "--dest" default to values from "--source" if COPY is yes. Prints current time, elapsed time, and rows archived every X rows. - - ---purge +.. option:: --purge Purge instead of archiving; allows omitting "--file" and "--dest". @@ -733,9 +592,7 @@ DSN values in "--dest" default to values from "--source" if COPY is yes. columns with "--primary-key-only". This will prevent fetching all columns from the server for no reason. - - ---quick-delete +.. option:: --quick-delete Adds the QUICK modifier to DELETE statements. @@ -743,9 +600,7 @@ DSN values in "--dest" default to values from "--source" if COPY is yes. documentation, in some cases it may be faster to use DELETE QUICK followed by OPTIMIZE TABLE. You can use "--optimize" for this. - - ---quiet +.. option:: --quiet short form: -q @@ -754,15 +609,11 @@ DSN values in "--dest" default to values from "--source" if COPY is yes. Suppresses normal output, including the output of "--statistics", but doesn't suppress the output from "--why-quit". - - ---replace +.. option:: --replace Causes INSERTs into "--dest" to be written as REPLACE. - - ---retries +.. option:: --retries type: int; default: 1 @@ -783,9 +634,7 @@ DSN values in "--dest" default to values from "--source" if COPY is yes. At this time I have not written any code to handle errors with transactional storage engines other than InnoDB. Request that feature if you need it. - - ---run-time +.. option:: --run-time type: time @@ -793,9 +642,7 @@ DSN values in "--dest" default to values from "--source" if COPY is yes. Optional suffix s=seconds, m=minutes, h=hours, d=days; if no suffix, s is used. - - ---[no]safe-auto-increment +.. option:: --[no]safe-auto-increment default: yes @@ -810,9 +657,7 @@ DSN values in "--dest" default to values from "--source" if COPY is yes. as of the beginning of the archive or purge job. If new rows are inserted while pt-archiver is running, it will not see them. - - ---sentinel +.. option:: --sentinel type: string; default: /tmp/pt-archiver-sentinel @@ -823,9 +668,7 @@ DSN values in "--dest" default to values from "--source" if COPY is yes. might find this handy to stop cron jobs gracefully if necessary. See also "--stop". - - ---set-vars +.. option:: --set-vars type: string; default: wait_timeout=10000 @@ -834,23 +677,17 @@ DSN values in "--dest" default to values from "--source" if COPY is yes. Specify any variables you want to be set immediately after connecting to MySQL. These will be included in a \ ``SET``\ command. - - ---share-lock +.. option:: --share-lock Adds the LOCK IN SHARE MODE modifier to SELECT statements. See `http://dev.mysql.com/doc/en/innodb-locking-reads.html `_. - - ---skip-foreign-key-checks +.. option:: --skip-foreign-key-checks Disables foreign key checks with SET FOREIGN_KEY_CHECKS=0. - - ---sleep +.. option:: --sleep type: int @@ -863,9 +700,7 @@ DSN values in "--dest" default to values from "--source" if COPY is yes. If "--commit-each" is specified, committing and flushing happens before sleeping. - - ---sleep-coef +.. option:: --sleep-coef type: float @@ -878,17 +713,13 @@ DSN values in "--dest" default to values from "--source" if COPY is yes. varying amount of time between each SELECT, depending on how long the SELECTs are taking. - - ---socket +.. option:: --socket short form: -S; type: string Socket file to use for connection. - - ---source +.. option:: --source type: DSN @@ -896,8 +727,7 @@ DSN values in "--dest" default to values from "--source" if COPY is yes. See DSN OPTIONS for the syntax. Most options control how pt-archiver connects to MySQL, but there are some extended DSN options in this tool's syntax. The D, t, and i options select a table to archive: - - + .. code-block:: perl --source h=my_server,D=my_database,t=my_tbl @@ -949,9 +779,7 @@ DSN values in "--dest" default to values from "--source" if COPY is yes. When pt-archiver connects to "--dest", host2, it will connect via the "--source", host1, socket defined in host1.cnf. - - ---statistics +.. option:: --statistics Collect and print timing statistics. @@ -961,7 +789,6 @@ DSN values in "--dest" default to values from "--source" if COPY is yes. Unless you specify "--quiet", \ ``pt-archiver``\ prints the statistics when it exits. The statistics look like this: - .. code-block:: perl Started at 2008-07-18T07:18:53, ended at 2008-07-18T07:18:53 @@ -993,9 +820,7 @@ DSN values in "--dest" default to values from "--source" if COPY is yes. This option requires the standard Time::HiRes module, which is part of core Perl on reasonably new Perl releases. - - ---stop +.. option:: --stop Stop running instances by creating the sentinel file. @@ -1003,9 +828,7 @@ DSN values in "--dest" default to values from "--source" if COPY is yes. exit. This should have the effect of stopping all running instances which are watching the same sentinel file. - - ---txn-size +.. option:: --txn-size type: int; default: 1 @@ -1030,23 +853,17 @@ DSN values in "--dest" default to values from "--source" if COPY is yes. If you are not archiving from or to a transactional storage engine, you may want to disable transactions so pt-archiver doesn't try to commit. - - ---user +.. option:: --user short form: -u; type: string User for login if not current user. - - ---version +.. option:: --version Show version and exit. - - ---where +.. option:: --where type: string @@ -1065,9 +882,7 @@ DSN values in "--dest" default to values from "--source" if COPY is yes. For safety, "--where" is required. If you do not require a WHERE clause, use "--where" 1=1. - - ---why-quit +.. option:: --why-quit Print reason for exiting unless rows exhausted. @@ -1082,12 +897,8 @@ DSN values in "--dest" default to values from "--source" if COPY is yes. This output prints even if "--quiet" is given. That's so you can put \ ``pt-archiver``\ in a \ ``cron``\ job and get an email if there's an abnormal exit. - - - -*********** DSN OPTIONS -*********** +=========== These DSN options are used to create a DSN. Each option is given like @@ -1097,119 +908,94 @@ if the value contains whitespace it must be quoted. DSN options are comma-separated. See the percona-toolkit manpage for full details. -\* a + * ``a`` copy: no Database to USE when executing queries. - - -\* A + * ``A`` dsn: charset; copy: yes Default character set. - -\* b + * ``b`` copy: no If true, disable binlog with SQL_LOG_BIN. - -\* D + * ``D`` dsn: database; copy: yes Database that contains the table. - - -\* F + * ``F`` dsn: mysql_read_default_file; copy: yes Only read default options from the given file - - -\* h + * ``h`` dsn: host; copy: yes Connect to host. - -\* i + * ``i`` copy: yes Index to use. - - -\* m + * ``m`` copy: no Plugin module name. - - -\* p + * ``p`` dsn: password; copy: yes Password to use when connecting. - -\* P + * ``P`` dsn: port; copy: yes Port number to use for connection. - -\* S + * ``S`` dsn: mysql_socket; copy: yes Socket file to use for connection. - - -\* t + * ``t`` copy: yes Table to archive from/to. - - -\* u + * ``u`` dsn: user; copy: yes User for login if not current user. - - - -********* EXTENDING -********* +========= -pt-archiver is extensible by plugging in external Perl modules to handle some -logic and/or actions. You can specify a module for both the "--source" and -the "--dest", with the 'm' part of the specification. For example: +:program:`pt-archiver` is extensible by plugging in external Perl modules to handle some logic and/or actions. You can specify a module for both the "--source" and the "--dest", with the 'm' part of the specification. For example: .. code-block:: perl @@ -1217,16 +1003,15 @@ the "--dest", with the 'm' part of the specification. For example: --source D=test,t=test1,m=My::Module1 --dest m=My::Module2,t=test2 -This will cause pt-archiver to load the My::Module1 and My::Module2 packages, -create instances of them, and then make calls to them during the archiving -process. +This will cause pt-archiver to load the ``My::Module1`` and ``My::Module2`` packages, create instances of them, and then make calls to them during the archiving process. You can also specify a plugin with "--plugin". The module must provide this interface: +:: -new(dbh => $dbh, db => $db_name, tbl => $tbl_name) + new(dbh => $dbh, db => $db_name, tbl => $tbl_name) The plugin's constructor is passed a reference to the database handle, the database name, and table name. The plugin is created just after pt-archiver @@ -1234,9 +1019,9 @@ new(dbh => $dbh, db => $db_name, tbl => $tbl_name) This gives the plugin a chance to create and populate temporary tables, or do other setup work. +:: - -before_begin(cols => \@cols, allcols => \@allcols) + before_begin(cols => \@cols, allcols => \@allcols) This method is called just before pt-archiver begins iterating through rows and archiving them, but after it does all other setup work (examining table @@ -1251,16 +1036,13 @@ before_begin(cols => \@cols, allcols => \@allcols) columns for its own use. When subsequent plugin functions receive a row, it is the full row containing all the extra columns, if any, added to the end. - - -is_archivable(row => \@row) +:: - This method is called for each row to determine whether it is archivable. This - applies only to "--source". The argument is the row itself, as an arrayref. - If the method returns true, the row will be archived; otherwise it will be - skipped. + is_archivable(row => \@row) - Skipping a row adds complications for non-unique indexes. Normally +This method is called for each row to determine whether it is archivable. This applies only to "--source". The argument is the row itself, as an arrayref. If the method returns true, the row will be archived; otherwise it will be skipped. + +Skipping a row adds complications for non-unique indexes. Normally pt-archiver uses a WHERE clause designed to target the last processed row as the place to start the scan for the next SELECT statement. If you have skipped the row by returning false from is_archivable(), pt-archiver could get into @@ -1271,96 +1053,91 @@ is_archivable(row => \@row) indexes such as primary keys, but it may skip rows (leave holes) on non-unique indexes or when ascending only the first column of an index. - \ ``pt-archiver``\ will change the clause in the same way if you specify +\ ``pt-archiver``\ will change the clause in the same way if you specify "--no-delete", because again an infinite loop is possible. - If you specify the "--bulk-delete" option and return false from this method, - \ ``pt-archiver``\ may not do what you want. The row won't be archived, but it will - be deleted, since bulk deletes operate on ranges of rows and don't know which - rows the plugin selected to keep. +If you specify the "--bulk-delete" option and return false from this method, + \ ``pt-archiver``\ may not do what you want. The row won't be archived, but it will be deleted, since bulk deletes operate on ranges of rows and don't know which rows the plugin selected to keep. - If you specify the "--bulk-insert" option, this method's return value will +If you specify the "--bulk-insert" option, this method's return value will influence whether the row is written to the temporary file for the bulk insert, so bulk inserts will work as expected. However, bulk inserts require bulk deletes. +:: - -before_delete(row => \@row) + before_delete(row => \@row) - This method is called for each row just before it is deleted. This applies only +This method is called for each row just before it is deleted. This applies only to "--source". This is a good place for you to handle dependencies, such as deleting things that are foreign-keyed to the row you are about to delete. You could also use this to recursively archive all dependent tables. - This plugin method is called even if "--no-delete" is given, but not if +This plugin method is called even if "--no-delete" is given, but not if "--bulk-delete" is given. +:: - -before_bulk_delete(first_row => \@row, last_row => \@row) + before_bulk_delete(first_row => \@row, last_row => \@row) - This method is called just before a bulk delete is executed. It is similar to +This method is called just before a bulk delete is executed. It is similar to the \ ``before_delete``\ method, except its arguments are the first and last row of the range to be deleted. It is called even if "--no-delete" is given. +:: - -before_insert(row => \@row) + before_insert(row => \@row) - This method is called for each row just before it is inserted. This applies +This method is called for each row just before it is inserted. This applies only to "--dest". You could use this to insert the row into multiple tables, - perhaps with an ON DUPLICATE KEY UPDATE clause to build summary tables in a data - warehouse. + perhaps with an ON DUPLICATE KEY UPDATE clause to build summary tables in a data warehouse. - This method is not called if "--bulk-insert" is given. +This method is not called if "--bulk-insert" is given. +:: - -before_bulk_insert(first_row => \@row, last_row => \@row, filename => bulk_insert_filename) + before_bulk_insert(first_row => \@row, last_row => \@row, filename => bulk_insert_filename) This method is called just before a bulk insert is executed. It is similar to the \ ``before_insert``\ method, except its arguments are the first and last row of the range to be deleted. +:: - -custom_sth(row => \@row, sql => $sql) + custom_sth(row => \@row, sql => $sql) - This method is called just before inserting the row, but after +This method is called just before inserting the row, but after "before_insert()". It allows the plugin to specify different \ ``INSERT``\ statement if desired. The return value (if any) should be a DBI statement handle. The \ ``sql``\ parameter is the SQL text used to prepare the default \ ``INSERT``\ statement. This method is not called if you specify "--bulk-insert". - If no value is returned, the default \ ``INSERT``\ statement handle is used. +If no value is returned, the default \ ``INSERT``\ statement handle is used. - This method applies only to the plugin specified for "--dest", so if your +This method applies only to the plugin specified for "--dest", so if your plugin isn't doing what you expect, check that you've specified it for the destination and not the source. +:: - -custom_sth_bulk(first_row => \@row, last_row => \@row, sql => $sql, filename => $bulk_insert_filename) + custom_sth_bulk(first_row => \@row, last_row => \@row, sql => $sql, filename => $bulk_insert_filename) - If you've specified "--bulk-insert", this method is called just before the +If you've specified "--bulk-insert", this method is called just before the bulk insert, but after "before_bulk_insert()", and the arguments are different. - This method's return value etc is similar to the "custom_sth()" method. +This method's return value etc is similar to the "custom_sth()" method. +:: - -after_finish() + after_finish() - This method is called after pt-archiver exits the archiving loop, commits all +This method is called after pt-archiver exits the archiving loop, commits all database handles, closes "--file", and prints the final statistics, but before pt-archiver runs ANALYZE or OPTIMIZE (see "--analyze" and "--optimize"). - - If you specify a plugin for both "--source" and "--dest", pt-archiver constructs, calls before_begin(), and calls after_finish() on the two plugins in the order "--source", "--dest". @@ -1372,7 +1149,6 @@ that "--source" and "--dest" are separate handles. A sample module might look like this: - .. code-block:: perl package My::Module; @@ -1402,16 +1178,14 @@ A sample module might look like this: 1; - -*********** ENVIRONMENT -*********** +=========== -The environment variable \ ``PTDEBUG``\ enables verbose debugging output to STDERR. +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-archiver ... > FILE 2>&1 @@ -1421,60 +1195,43 @@ Be careful: debugging output is voluminous and can generate several megabytes of output. -******************* SYSTEM REQUIREMENTS -******************* +=================== -You need Perl, DBI, DBD::mysql, and some core packages that ought to be -installed in any reasonably new version of Perl. +You need ``Perl``, ``DBI``, ``DBD::mysql``, and some core packages that ought to be installed in any reasonably new version of Perl. -**** BUGS -**** +==== For a list of known bugs, see `http://www.percona.com/bugs/pt-archiver `_. 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.) +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 @@ -1486,35 +1243,25 @@ command line: 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 - -*************** ACKNOWLEDGMENTS -*************** - +=============== Andrew O'Brien - -********************* 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 @@ -1524,10 +1271,8 @@ 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 2007-2011 Baron Schwartz, 2011 Percona Inc. Feedback and improvements are welcome. @@ -1546,11 +1291,8 @@ You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. - -******* VERSION -******* +======= - -pt-archiver 1.0.1 + :program:`pt-archiver` 1.0.1 diff --git a/docs/user/source/pt-collect.rst b/docs/user/source/pt-collect.rst new file mode 100644 index 00000000..30674f1e --- /dev/null +++ b/docs/user/source/pt-collect.rst @@ -0,0 +1,125 @@ + +.. program:: pt-collect + +======================= + :program:`pt-collect` +======================= + +.. highlight:: perl + +NAME +==== + +:program:`pt-collect` - Collect information from a server for some period of time. + +SYNOPSIS +======== + +Usage +----- + +:: + + pt-collect -d -g -i -o -s [OPTIONS] [-- MYSQL-OPTIONS] + +:program:`pt-collect` tool gathers a variety of information about a system for a period of time. It is typically executed when the stalk tool detects a condition 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. + +:program:`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 +=========== + +:program:`pt-collect` creates a lock to ensure that only one instance runs at a time, and then saves a variety of performance and status data into files in the +configured directory. Files are named with a timestamp so they can be grouped together. The tool is MySQL-centric by default, and gathers quite a bit of diagnostic data that's useful for understanding the behavior of a MySQL database server. + +Options after \ ``--``\ are passed to \ ``mysql``\ and \ ``mysqladmin``\ . + +OPTIONS +======= + +.. option:: -d DESTINATION (required) + + Where to store the resulting data; must already exist. + +.. option:: -g (required) + + Collect GDB stack traces. + +.. option:: -i INTERVAL (required) + + How many seconds to collect data. + +.. option:: -o (required) + + Collect oprofile data; disables -s. + +.. option:: -s (required) + + Collect strace data. + +.. option:: -f PERCENT + + Exit if the disk is more than this percent full (default 100). + +.. option:: -m MEGABYTES + + Exit if there are less than this many megabytes free disk space (default 0). + +.. option:: -p PREFIX + + Store the data into files with this prefix (optional). + +.. option:: -t + + Collect tcpdump data. + +ENVIRONMENT +=========== + +This tool does not use any environment variables. + +SYSTEM REQUIREMENTS +=================== + +This tool requires Bash v3 or newer and assumes that these programs +are installed, in the PATH, and executable: sysctl, top, vmstat, iostat, +mpstat, lsof, mysql, mysqladmin, df, netstat, pidof, flock, and others +depending on what command-line options are specified. If some of those +programs are not available, the tool will still run but may print warnings. + +AUTHORS +======= + +Baron Schwartz + +COPYRIGHT, LICENSE, AND WARRANTY +================================ + +This program is copyright 2010-2011 Baron Schwartz, 2011 Percona Inc. +Feedback and improvements are welcome. + +VERSION +======= + +pt-collect 1.0.1 + diff --git a/docs/user/pt-config-diff.rst b/docs/user/source/pt-config-diff.rst similarity index 55% rename from docs/user/pt-config-diff.rst rename to docs/user/source/pt-config-diff.rst index c673c1cc..b0583291 100644 --- a/docs/user/pt-config-diff.rst +++ b/docs/user/source/pt-config-diff.rst @@ -1,59 +1,51 @@ +.. program:: pt-config-diff -############## -pt-config-diff -############## +=========================== + :program:`pt-config-diff` +=========================== .. highlight:: perl - -**** NAME -**** +==== -pt-config-diff - Diff MySQL configuration files and server variables. +:program:`pt-config-diff` - Diff MySQL configuration files and server variables. -******** SYNOPSIS -******** +======== +Usage +----- -Usage: pt-config-diff [OPTION...] CONFIG CONFIG [CONFIG...] +:: -pt-config-diff diffs MySQL configuration files and server variables. -CONFIG can be a filename or a DSN. At least two CONFIG sources must be given. -Like standard Unix diff, there is no output if there are no differences. + pt-config-diff [OPTION...] CONFIG CONFIG [CONFIG...] -Diff host1 config from SHOW VARIABLES against host2: +:program:`pt-config-diff` diffs |MySQL| configuration files and server variables. ``CONFIG`` can be a filename or a ``DSN``. At least two ``CONFIG`` sources must be given. Like standard Unix diff, there is no output if there are no differences. +Diff ``host1`` config from ``SHOW VARIABLES`` against ``host2``: .. code-block:: perl pt-config-diff h=host1 h=host2 - -Diff config from [mysqld] section in my.cnf against host1 config: - +Diff config from ``[mysqld]`` section in :file:`my.cnf` against ``host1`` config: .. code-block:: perl pt-config-diff /etc/my.cnf h=host1 - -Diff the [mysqld] section of two option files: - +Diff the ``[mysqld]`` section of two option files: .. code-block:: perl pt-config-diff /etc/my-small.cnf /etc/my-large.cnf - -***** 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 @@ -73,40 +65,27 @@ see a list of such issues at the following URL: See also "BUGS" for more information on filing bugs and getting help. -*********** DESCRIPTION -*********** +=========== +:program:`pt-config-diff` diffs MySQL configurations by examining the values of server system variables from two or more CONFIG sources specified on the command +line. A ``CONFIG`` source can be a ``DSN`` or a filename containing the output of \ ``mysqld --help --verbose``\ , \ ``my_print_defaults``\ , \ ``SHOW VARIABLES``\ , or an option file (e.g. ``my.cnf``). -pt-config-diff diffs MySQL configurations by examining the values of server -system variables from two or more CONFIG sources specified on the command -line. A CONFIG source can be a DSN or a filename containing the output of -\ ``mysqld --help --verbose``\ , \ ``my_print_defaults``\ , \ ``SHOW VARIABLES``\ , or -an option file (e.g. my.cnf). - -For each DSN CONFIG, pt-config-diff connects to MySQL and gets variables -and values by executing \ ``SHOW /\*!40103 GLOBAL\*/ VARIABLES``\ . This is -an "active config" because it shows what server values MySQL is +For each ``DSN CONFIG``, :program:`pt-config-diff` connects to MySQL and gets variables and values by executing \ ``SHOW /\*!40103 GLOBAL\*/ VARIABLES``\ . This is an "active config" because it shows what server values |MySQL| is actively (currently) running with. -Only variables that all CONFIG sources have are compared because if a +Only variables that all ``CONFIG`` sources have are compared because if a variable is not present then we cannot know or safely guess its value. -For example, if you compare an option file (e.g. my.cnf) to an active config -(i.e. SHOW VARIABLES from a DSN CONFIG), the option file will probably -only have a few variables, whereas the active config has every variable. -Only values of the variables present in both configs are compared. +For example, if you compare an option file (e.g. :file:`my.cnf`) to an active config (i.e. ``SHOW VARIABLES`` from a ``DSN CONFIG``), the option file will probably only have a few variables, whereas the active config has every variable. Only values of the variables present in both configs are compared. -Option file and DSN configs provide the best results. +Option file and ``DSN`` configs provide the best results. -****** OUTPUT -****** - +====== There is no output when there are no differences. When there are differences, -pt-config-diff prints a report to STDOUT that looks similar to the following: - +:program:`pt-config-diff` prints a report to ``STDOUT`` that looks similar to the following: .. code-block:: perl @@ -117,10 +96,9 @@ pt-config-diff prints a report to STDOUT that looks similar to the following: port 12345 12346 -Comparing MySQL variables is difficult because there are many variations and -subtleties across the many versions and distributions of MySQL. When a -comparison fails, the tool prints a warning to STDERR, such as the following: - +Comparing |MySQL| variables is difficult because there are many variations and +subtleties across the many versions and distributions of |MySQL|. When a +comparison fails, the tool prints a warning to ``STDERR``, such as the following: .. code-block:: perl @@ -131,32 +109,22 @@ comparison fails, the tool prints a warning to STDERR, such as the following: Please report these warnings so the comparison functions can be improved. - -*********** EXIT STATUS -*********** +=========== +:program:`pt-config-diff` exits with a zero exit status when there are no differences, and 1 if there are. -pt-config-diff exits with a zero exit status when there are no differences, and -1 if there are. - - -******* OPTIONS -******* - +======= This tool accepts additional command-line arguments. Refer to the "SYNOPSIS" and usage information for details. - ---ask-pass +.. option:: --ask-pass - Prompt for a password when connecting to MySQL. + Prompt for a password when connecting to MySQL. - - ---charset +.. option:: --charset short form: -A; type: string @@ -166,9 +134,7 @@ This tool accepts additional command-line arguments. Refer to the binmode on STDOUT without the utf8 layer, and runs SET NAMES after connecting to MySQL. - - ---config +.. option:: --config type: Array @@ -176,55 +142,41 @@ This tool accepts additional command-line arguments. Refer to the first option on the command line. (This option does not specify a CONFIG; it's equivalent to \ ``--defaults-file``\ .) - - ---daemonize +.. option:: --daemonize Fork to the background and detach from the shell. POSIX operating systems only. - - ---defaults-file +.. option:: --defaults-file short form: -F; type: string Only read mysql options from the given file. You must give an absolute pathname. - - ---help +.. option:: --help Show help and exit. - - ---host +.. option:: --host short form: -h; type: string Connect to host. - - ---ignore-variables +.. option:: --ignore-variables type: array Ignore, do not compare, these variables. - - ---password +.. option:: --password short form: -p; type: string Password to use for connection. - - ---pid +.. option:: --pid type: string @@ -234,17 +186,13 @@ This tool accepts additional command-line arguments. Refer to the PID file when starting; if it exists and the process with the matching PID exists, the program exits. - - ---port +.. option:: --port short form: -P; type: int Port number to use for connection. - - ---[no]report +.. option:: --[no]report default: yes @@ -252,9 +200,7 @@ This tool accepts additional command-line arguments. Refer to the if the given configs are different or not by examining the tool's exit status, then specify \ ``--no-report``\ to suppress the report. - - ---report-width +.. option:: --report-width type: int; default: 78 @@ -262,43 +208,32 @@ This tool accepts additional command-line arguments. Refer to the be long, or when comparing multiple configs, it may help to increase the report width so values are not truncated beyond readability. - - ---set-vars +.. option:: --set-vars type: string; default: wait_timeout=10000 Set these MySQL variables. Immediately after connecting to MySQL, this string will be appended to SET and executed. - - ---socket +.. option:: --socket short form: -S; type: string Socket file to use for connection. - - ---user +.. option:: --user short form: -u; type: string MySQL user if not current user. - - ---version +.. option:: --version Show version and exit. - - -*********** DSN OPTIONS -*********** +=========== These DSN options are used to create a DSN. Each option is given like @@ -307,81 +242,62 @@ same option. There cannot be whitespace before or after the \ ``=``\ and if the value contains whitespace it must be quoted. DSN options are comma-separated. See the percona-toolkit manpage for full details. - -\* A + * A dsn: charset; copy: yes Default character set. - - -\* D + * D dsn: database; copy: yes Default database. - - -\* F + * F dsn: mysql_read_default_file; copy: yes Only read default options from the given file - - -\* h + * h dsn: host; copy: yes Connect to host. - - -\* p + * p dsn: password; copy: yes Password to use when connecting. - - -\* P + * P dsn: port; copy: yes Port number to use for connection. - - -\* S + * S dsn: mysql_socket; copy: yes Socket file to use for connection. - - -\* u + * u dsn: user; copy: yes User for login if not current user. - - -*********** ENVIRONMENT -*********** +=========== +The environment variable \ ``PTDEBUG``\ enables verbose debugging output to ``STDERR``. -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-config-diff ... > FILE 2>&1 @@ -391,128 +307,37 @@ Be careful: debugging output is voluminous and can generate several megabytes of output. -******************* SYSTEM REQUIREMENTS -******************* - +=================== You need Perl, DBI, DBD::mysql, and some core packages that ought to be installed in any reasonably new version of Perl. -**** BUGS -**** - +==== For a list of known bugs, see `http://www.percona.com/bugs/pt-config-diff `_. -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 and Daniel Nichter -********************* -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 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 -******* - +======= pt-config-diff 1.0.1 diff --git a/docs/user/pt-deadlock-logger.rst b/docs/user/source/pt-deadlock-logger.rst similarity index 75% rename from docs/user/pt-deadlock-logger.rst rename to docs/user/source/pt-deadlock-logger.rst index 60cd6173..ef64eab4 100644 --- a/docs/user/pt-deadlock-logger.rst +++ b/docs/user/source/pt-deadlock-logger.rst @@ -1,27 +1,29 @@ +.. program:: pt-deadlock-logger -################## -pt-deadlock-logger -################## +=============================== + :program:`pt-deadlock-logger` +=============================== .. highlight:: perl - -**** NAME -**** +==== -pt-deadlock-logger - Extract and log MySQL deadlock information. +:program:`pt-deadlock-logger` - Extract and log MySQL deadlock information. -******** SYNOPSIS -******** +======== +Usage +----- -Usage: pt-deadlock-logger [OPTION...] SOURCE_DSN +:: -pt-deadlock-logger extracts and saves information about the most recent deadlock + pt-deadlock-logger [OPTION...] SOURCE_DSN + +:program:`pt-deadlock-logger` extracts and saves information about the most recent deadlock in a MySQL server. Print deadlocks on SOURCE_DSN: @@ -57,22 +59,15 @@ Daemonize and check for deadlocks on SOURCE_DSN every 30 seconds for 4 hours: pt-deadlock-logger SOURCE_DSN --dest D=test,t=deadlocks --daemonize --run-time 4h --interval 30s - - -***** 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-deadlock-logger is a read-only tool unless you specify a "--dest" table. -In some cases polling SHOW INNODB STATUS too rapidly can cause extra load on the -server. If you're using it on a production server under very heavy load, you -might want to set "--interval" to 30 seconds or more. +:program:`pt-deadlock-logger` is a read-only tool unless you specify a "--dest" table. In some cases polling ``SHOW INNODB STATUS`` too rapidly can cause extra load on the server. If you're using it on a production server under very heavy load, you might want to set "--interval" to 30 seconds or more. At the time of this release, we know of no bugs that could cause serious harm to users. @@ -82,18 +77,12 @@ 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-deadlock-logger `_. -See also "BUGS" for more information on filing bugs and getting help. +See also :ref:`bugs` for more information on filing bugs and getting help. - -*********** DESCRIPTION -*********** +=========== - -pt-deadlock-logger extracts deadlock data from a MySQL server. Currently only -InnoDB deadlock information is available. You can print the information to -standard output, store it in a database table, or both. If neither -"--print" nor "--dest" are given, then the deadlock information is +:program:`pt-deadlock-logger` extracts deadlock data from a MySQL server. Currently only InnoDB deadlock information is available. You can print the information to standard output, store it in a database table, or both. If neither "--print" nor "--dest" are given, then the deadlock information is printed by default. If only "--dest" is given, then the deadlock information is only stored. If both options are given, then the deadlock information is printed and stored. @@ -127,122 +116,83 @@ values from the source host, so you don't need to specify them in both places. \ ``pt-deadlock-logger``\ reads all normal MySQL option files, such as ~/.my.cnf, so you may not need to specify username, password and other common options at all. - -****** OUTPUT -****** - +====== You can choose which columns are output and/or saved to "--dest" with the "--columns" argument. The default columns are as follows: - -server + * ``server`` The (source) server on which the deadlock occurred. This might be useful if you're tracking deadlocks on many servers. - - -ts + * ``ts`` The date and time of the last detected deadlock. - - -thread + * ``thread`` The MySQL thread number, which is the same as the connection ID in SHOW FULL PROCESSLIST. - - -txn_id + * ``txn_id`` The InnoDB transaction ID, which InnoDB expresses as two unsigned integers. I have multiplied them out to be one number. - - -txn_time + * ``txn_time`` How long the transaction was active when the deadlock happened. - - -user + * ``user`` The connection's database username. - - -hostname + * ``hostname`` The connection's host. - - -ip + * ``ip`` The connection's IP address. If you specify "--numeric-ip", this is converted to an unsigned integer. - - -db + * ``db`` The database in which the deadlock occurred. - - -tbl + * ``tbl`` The table on which the deadlock occurred. - - -idx + * ``idx`` The index on which the deadlock occurred. - - -lock_type + * ``lock_type`` The lock type the transaction held on the lock that caused the deadlock. - - -lock_mode + * ``lock_mode`` The lock mode of the lock that caused the deadlock. - - -wait_hold + * ``wait_hold`` Whether the transaction was waiting for the lock or holding the lock. Usually you will see the two waited-for locks. - - -victim + * ``victim`` Whether the transaction was selected as the deadlock victim and rolled back. - - -query + * ``query`` The query that caused the deadlock. - - - -************************** INNODB CAVEATS AND DETAILS -************************** - +========================== InnoDB's output is hard to parse and sometimes there's no way to do it right. @@ -262,23 +212,17 @@ held lock, you're looking at the same lock, so of course you'd prefer to see both wait-for locks and get more information. If the two waited-for locks are not on the same table, more than two transactions were involved in the deadlock. - -******* OPTIONS -******* - +======= This tool accepts additional command-line arguments. Refer to the "SYNOPSIS" and usage information for details. - ---ask-pass +.. option:: --ask-pass Prompt for a password when connecting to MySQL. - - ---charset +.. option:: --charset short form: -A; type: string @@ -287,9 +231,7 @@ This tool accepts additional command-line arguments. Refer to the NAMES UTF8 after connecting to MySQL. Any other value sets binmode on STDOUT without the utf8 layer, and runs SET NAMES after connecting to MySQL. - - ---clear-deadlocks +.. option:: --clear-deadlocks type: string @@ -307,36 +249,28 @@ This tool accepts additional command-line arguments. Refer to the After creating the table and causing a small deadlock, the tool will drop the table again. - - ---[no]collapse +.. option:: --[no]collapse Collapse whitespace in queries to a single space. This might make it easier to inspect on the command line or in a query. By default, whitespace is collapsed when printing with "--print", but not modified when storing to "--dest". (That is, the default is different for each action). - - ---columns +.. option:: --columns type: hash Output only this comma-separated list of columns. See "OUTPUT" for more details on columns. - - ---config +.. option:: --config type: Array Read this comma-separated list of config files; if specified, this must be the first option on the command line. - - ---create-dest-table +.. option:: --create-dest-table Create the table specified by "--dest". @@ -344,24 +278,18 @@ This tool accepts additional command-line arguments. Refer to the causes pt-deadlock-logger to create the table automatically using the suggested table structure. - - ---daemonize +.. option:: --daemonize Fork to the background and detach from the shell. POSIX operating systems only. - - ---defaults-file +.. option:: --defaults-file short form: -F; type: string Only read mysql options from the given file. You must give an absolute pathname. - - ---dest +.. option:: --dest type: DSN @@ -377,7 +305,6 @@ This tool accepts additional command-line arguments. Refer to the The following MAGIC_dest_table is suggested if you want to store all the information pt-deadlock-logger can extract about deadlocks: - .. code-block:: perl CREATE TABLE deadlocks ( @@ -404,23 +331,17 @@ This tool accepts additional command-line arguments. Refer to the If you use "--columns", you can omit whichever columns you don't want to store. - - ---help +.. option:: --help Show help and exit. - - ---host +.. option:: --host short form: -h; type: string Connect to host. - - ---interval +.. option:: --interval type: time @@ -428,31 +349,23 @@ This tool accepts additional command-line arguments. Refer to the pt-deadlock-logger runs forever, checking for deadlocks at every interval. See also "--run-time". - - ---log +.. option:: --log type: string Print all output to this file when daemonized. - - ---numeric-ip +.. option:: --numeric-ip Express IP addresses as integers. - - ---password +.. option:: --password short form: -p; type: string Password to use when connecting. - - ---pid +.. option:: --pid type: string @@ -461,17 +374,13 @@ This tool accepts additional command-line arguments. Refer to the exits. The program checks for the existence of the PID file when starting; if it exists and the process with the matching PID exists, the program exits. - - ---port +.. option:: --port short form: -P; type: int Port number to use for connection. - - ---print +.. option:: --print Print results on standard output. See "OUTPUT" for more. By default, enables "--[no]collapse" unless you explicitly disable it. @@ -482,9 +391,7 @@ This tool accepts additional command-line arguments. Refer to the by "--columns") and if the current deadlock's fingerprint is different from the last deadlock's fingerprint, then it is printed. - - ---run-time +.. option:: --run-time type: time @@ -492,50 +399,36 @@ This tool accepts additional command-line arguments. Refer to the checks for deadlocks, and exits. If "--run-time" is specified but no "--interval" is specified, a default 1 second interval will be used. - - ---set-vars +.. option:: --set-vars type: string; default: wait_timeout=10000 Set these MySQL variables. Immediately after connecting to MySQL, this string will be appended to SET and executed. - - ---socket +.. option:: --socket short form: -S; type: string Socket file to use for connection. - - ---tab +.. option:: --tab Print tab-separated columns, instead of aligned. - - ---user +.. option:: .. option:: --user short form: -u; type: string User for login if not current user. - - ---version +.. option:: .. option:: --version Show version and exit. - - -*********** DSN OPTIONS -*********** - +=========== These DSN options are used to create a DSN. Each option is given like \ ``option=value``\ . The options are case-sensitive, so P and p are not the @@ -543,81 +436,60 @@ same option. There cannot be whitespace before or after the \ ``=``\ and if the value contains whitespace it must be quoted. DSN options are comma-separated. See the percona-toolkit manpage for full details. - -\* A + * A dsn: charset; copy: yes Default character set. - - -\* D + * D dsn: database; copy: yes Default database. - - -\* F + * F dsn: mysql_read_default_file; copy: yes Only read default options from the given file - - -\* h + * h dsn: host; copy: yes Connect to host. - - -\* p + * p dsn: password; copy: yes Password to use when connecting. - - -\* P + * P dsn: port; copy: yes Port number to use for connection. - - -\* S + * S dsn: mysql_socket; copy: yes Socket file to use for connection. - - -\* t + * t Table in which to store deadlock information. - - -\* u + * u dsn: user; copy: yes User for login if not current user. - - - -*********** ENVIRONMENT -*********** +=========== The environment variable \ ``PTDEBUG``\ enables verbose debugging output to STDERR. @@ -633,128 +505,31 @@ Be careful: debugging output is voluminous and can generate several megabytes of output. -******************* SYSTEM REQUIREMENTS -******************* - +=================== You need Perl, DBI, DBD::mysql, and some core packages that ought to be installed in any reasonably new version of Perl. - -**** BUGS -**** - +==== For a list of known bugs, see `http://www.percona.com/bugs/pt-deadlock-logger `_. 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 2007-2011 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 -******* - +======= pt-deadlock-logger 1.0.1 diff --git a/docs/user/pt-diskstats.rst b/docs/user/source/pt-diskstats.rst similarity index 56% rename from docs/user/pt-diskstats.rst rename to docs/user/source/pt-diskstats.rst index 0dc6f4a6..e1aa6654 100644 --- a/docs/user/pt-diskstats.rst +++ b/docs/user/source/pt-diskstats.rst @@ -1,41 +1,39 @@ +.. program:: pt-diskstats -############ -pt-diskstats -############ +========================= + :program:`pt-diskstats` +========================= .. highlight:: perl -**** NAME -**** +==== + +:program:`pt-diskstats` - Aggregate and summarize \ */proc/diskstats*\ . -pt-diskstats - Aggregate and summarize \ */proc/diskstats*\ . - - -******** SYNOPSIS -******** +======== +Usage +----- -Usage: pt-diskstats [OPTIONS] [FILES] +:: -pt-diskstats reads \ */proc/diskstats*\ periodically, or files with the -contents of \ */proc/diskstats*\ , aggregates the data, and prints it nicely. + pt-diskstats [OPTIONS] [FILES] +:program:`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. +:program:`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. @@ -45,20 +43,13 @@ 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. +See also :ref:`bugs` for more information on filing bugs and getting help. -*********** DESCRIPTION -*********** +=========== - -pt-diskstats tool is similar to iostat, but has some advantages. It separates -reads and writes, for example, and computes some things that iostat does in -either incorrect or confusing ways. It is also menu-driven and interactive -with several different ways to aggregate the data, and integrates well with -the pt-collect tool. These properties make it very convenient for quickly -drilling down into I/O performance at the desired level of granularity. +:program:`pt-diskstats` tool is similar to iostat, but has some advantages. It separates reads and writes, for example, and computes some things that iostat does in either incorrect or confusing ways. It is also menu-driven and interactive with several different ways to aggregate the data, and integrates well with the :program:`pt-collect` tool. These properties make it very convenient for quickly drilling down into I/O performance at the desired level of granularity. This program works in two main modes. One way is to process a file with saved disk statistics, which you specify on the command line. The other way is to @@ -74,7 +65,6 @@ shows which keys control the program. Files should have this format: - .. code-block:: perl @@ -83,78 +73,56 @@ Files should have this format: ... et cetera TS <-- must end with a TS line. - See `http://aspersa.googlecode.com/svn/html/diskstats.html `_ for a detailed example of using the tool. - -****** OUTPUT -****** +====== The columns are as follows: - -#ts + * ``#ts`` The number of seconds of samples in the line. If there is only one, then the timestamp itself is shown, without the {curly braces}. - - -device + * ``device`` The device name. If there is more than one device, then instead the number of devices aggregated into the line is shown, in {curly braces}. - - -rd_mb_s + * ``rd_mb_s`` The number of megabytes read per second, average, during the sampled interval. - - -rd_cnc + * ``rd_cnc`` The average concurrency of the read operations, as computed by Little's Law (a.k.a. queueing theory). - - -rd_rt + * ``rd_rt`` The average response time of the read operations, in milliseconds. - - -wr_mb_s + * ``wr_mb_s`` Megabytes written per second, average. - - -wr_cnc + * ``wr_cnc`` Write concurrency, similar to read concurrency. - - -wr_rt + * ``wr_rt`` Write response time, similar to read response time. - - -busy + * ``busy`` The fraction of time that the device had at least one request in progress; this is what iostat calls %util (which is a misleading name). - - -in_prg + * ``in_prg`` The number of requests that were in progress. Unlike the read and write concurrencies, which are averages that are generated from reliable numbers, @@ -162,229 +130,101 @@ in_prg represent a spike of requests, rather than the true long-term average. - In addition to the above columns, there are a few columns that are hidden by default. If you press the 'c' key, and then press Enter, you will blank out the regular expression pattern that selects columns to display, and you will then see the extra columns: - -rd_s + * ``rd_s`` The number of reads per second. - - -rd_avkb + * ``rd_avkb`` The average size of the reads, in kilobytes. - - -rd_mrg + * ``rd_mrg`` The percentage of read requests that were merged together in the disk scheduler before reaching the device. - - -wr_s, wr_avgkb, and wr_mrg + * ``wr_s``, ``wr_avgkb``, and ``wr_mrg`` These are analogous to their \ ``rd_\*``\ cousins. - - -******* OPTIONS -******* - +======= Options must precede files on the command line. - --c COLS +.. option:: -c COLS - Awk regex of which columns to include (default cnc|rt|mb|busy|prg). + Awk regex of which columns to include (default ``cnc|rt|mb|busy|prg``). - - --d DEVICES +.. option:: -d DEVICES Awk regex of which devices to include. - - --g GROUPBY +.. option:: -g GROUPBY Group-by mode (default disk); specify one of the following: - - .. code-block:: perl + .. code-block:: perl disk - Each line of output shows one disk device. sample - Each line of output shows one sample of statistics. all - Each line of output shows one sample and one disk device. - - - --i INTERVAL + .. option:: -i INTERVAL In -g sample mode, include INTERVAL seconds per sample. - - --k KEEPFILE +.. option:: -k KEEPFILE File to save diskstats samples in (default /tmp/diskstats-samples). If a non-default filename is used, it will be saved for later analysis. - - --n SAMPLES +.. option:: -n SAMPLES When in interactive mode, stop after N samples. - - --s INTERVAL +.. option:: -s INTERVAL Sample /proc/diskstats every N seconds (default 1). - - -*********** ENVIRONMENT -*********** - +=========== This tool does not use any environment variables. - -******************* SYSTEM REQUIREMENTS -******************* - +=================== This tool requires Bash v3 or newer and the \ */proc*\ filesystem unless reading from files. - -**** BUGS -**** - +==== For a list of known bugs, see `http://www.percona.com/bugs/pt-diskstats `_. Please report bugs at `https://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-2011 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 -******* +======= - -pt-diskstats 1.0.1 +:program:`pt-diskstats` 1.0.1 diff --git a/docs/user/pt-duplicate-key-checker.rst b/docs/user/source/pt-duplicate-key-checker.rst similarity index 68% rename from docs/user/pt-duplicate-key-checker.rst rename to docs/user/source/pt-duplicate-key-checker.rst index f10fb45e..845a0d92 100644 --- a/docs/user/pt-duplicate-key-checker.rst +++ b/docs/user/source/pt-duplicate-key-checker.rst @@ -1,48 +1,41 @@ +.. program:: pt-duplicate-key-checker -######################## -pt-duplicate-key-checker -######################## +===================================== + :program:`pt-duplicate-key-checker` +===================================== .. highlight:: perl - -**** NAME -**** +==== +:program:`pt-duplicate-key-checker` - Find duplicate indexes and foreign keys on MySQL tables. -pt-duplicate-key-checker - Find duplicate indexes and foreign keys on MySQL tables. - - -******** SYNOPSIS -******** +======== +Usage +----- -Usage: pt-duplicate-key-checker [OPTION...] [DSN] +:: -pt-duplicate-key-checker examines MySQL tables for duplicate or redundant -indexes and foreign keys. Connection options are read from MySQL option files. + pt-duplicate-key-checker [OPTION...] [DSN] +:program:`pt-duplicate-key-checker` examines |MySQL| tables for duplicate or redundant indexes and foreign keys. Connection options are read from MySQL option files. .. code-block:: perl pt-duplicate-key-checker --host host1 - - -***** 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-duplicate-key-checker is a read-only tool that executes SHOW CREATE TABLE and -related queries to inspect table structures, and thus is very low-risk. +:program:`pt-duplicate-key-checker` is a read-only tool that executes ``SHOW CREATE TABLE`` and related queries to inspect table structures, and thus is very low-risk. At the time of this release, there is an unconfirmed bug that causes the tool to crash. @@ -54,49 +47,37 @@ see a list of such issues at the following URL: See also "BUGS" for more information on filing bugs and getting help. - -*********** DESCRIPTION -*********** +=========== - -This program examines the output of SHOW CREATE TABLE on MySQL tables, and if -it finds indexes that cover the same columns as another index in the same +This program examines the output of ``SHOW CREATE TABLE`` on |MySQL| tables, and if it finds indexes that cover the same columns as another index in the same order, or cover an exact leftmost prefix of another index, it prints out the suspicious indexes. By default, indexes must be of the same type, so a BTREE index is not a duplicate of a FULLTEXT index, even if they have the same columns. You can override this. -It also looks for duplicate foreign keys. A duplicate foreign key covers the +It also looks for duplicate foreign keys. A duplicate foreign key covers the same columns as another in the same table, and references the same parent table. - -******* OPTIONS -******* - +======= This tool accepts additional command-line arguments. Refer to the "SYNOPSIS" and usage information for details. - ---all-structs +.. option:: --all-structs Compare indexes with different structs (BTREE, HASH, etc). By default this is disabled, because a BTREE index that covers the same columns as a FULLTEXT index is not really a duplicate, for example. - - ---ask-pass +.. option:: --ask-pass Prompt for a password when connecting to MySQL. - - ---charset +.. option:: --charset short form: -A; type: string @@ -105,9 +86,7 @@ This tool accepts additional command-line arguments. Refer to the NAMES UTF8 after connecting to MySQL. Any other value sets binmode on STDOUT without the utf8 layer, and runs SET NAMES after connecting to MySQL. - - ---[no]clustered +.. option:: --[no]clustered default: yes @@ -135,12 +114,10 @@ This tool accepts additional command-line arguments. Refer to the The use of such indexes is rather subtle. For example, suppose you have the following query: - .. code-block:: perl SELECT ... WHERE b=1 ORDER BY a; - This query will do a filesort if we remove the index on \ ``b,a``\ . But if we shorten the index on \ ``b,a``\ to just \ ``b``\ and also remove the ORDER BY, the query should return the same results. @@ -152,103 +129,77 @@ This tool accepts additional command-line arguments. Refer to the shortened clustered keys. Therefore, if you shorten any duplicate clustered keys, you should run the tool again. - - ---config +.. option:: --config type: Array Read this comma-separated list of config files; if specified, this must be the first option on the command line. - - ---databases +.. option:: --databases short form: -d; type: hash Check only this comma-separated list of databases. - - ---defaults-file +.. option:: --defaults-file short form: -F; type: string Only read mysql options from the given file. You must give an absolute pathname. - - ---engines +.. option:: --engines short form: -e; type: hash Check only tables whose storage engine is in this comma-separated list. - - ---help +.. option:: --help Show help and exit. - - ---host +.. option:: --host short form: -h; type: string Connect to host. - - ---ignore-databases +.. option:: --ignore-databases type: Hash Ignore this comma-separated list of databases. - - ---ignore-engines +.. option:: --ignore-engines type: Hash Ignore this comma-separated list of storage engines. - - ---ignore-order +.. option:: --ignore-order Ignore index order so KEY(a,b) duplicates KEY(b,a). - - ---ignore-tables +.. option:: --ignore-tables type: Hash Ignore this comma-separated list of tables. Table names may be qualified with the database name. - - ---key-types +.. option:: --key-types type: string; default: fk Check for duplicate f=foreign keys, k=keys or fk=both. - - ---password +.. option:: --password short form: -p; type: string Password to use when connecting. - - ---pid +.. option:: --pid type: string @@ -261,34 +212,26 @@ This tool accepts additional command-line arguments. Refer to the script overwrites the file with its own PID and starts; else, if the file contains no PID, then the script dies. - - ---port +.. option:: --port short form: -P; type: int Port number to use for connection. - - ---set-vars +.. option:: --set-vars type: string; default: wait_timeout=10000 Set these MySQL variables. Immediately after connecting to MySQL, this string will be appended to SET and executed. - - ---socket +.. option:: --socket short form: -S; type: string Socket file to use for connection. - - ---[no]sql +.. option:: --[no]sql default: yes @@ -298,17 +241,13 @@ This tool accepts additional command-line arguments. Refer to the To disable printing these statements, specify --nosql. - - ---[no]summary +.. option:: --[no]summary default: yes Print summary of indexes at end of output. - - ---tables +.. option:: --tables short form: -t; type: hash @@ -316,34 +255,24 @@ This tool accepts additional command-line arguments. Refer to the Table names may be qualified with the database name. - - ---user +.. option:: --user short form: -u; type: string User for login if not current user. - - ---verbose +.. option:: --verbose short form: -v Output all keys and/or foreign keys found, not just redundant ones. - - ---version +.. option:: --version Show version and exit. - - - -*********** DSN OPTIONS -*********** +=========== These DSN options are used to create a DSN. Each option is given like @@ -359,9 +288,7 @@ comma-separated. See the percona-toolkit manpage for full details. Default character set. - - -\* D + * ``D`` dsn: database; copy: yes @@ -369,7 +296,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* F + * ``F`` dsn: mysql_read_default_file; copy: yes @@ -377,187 +304,78 @@ comma-separated. See the percona-toolkit manpage for full details. -\* h + * ``h`` dsn: host; copy: yes Connect to host. - - -\* p + * ``p`` dsn: password; copy: yes Password to use when connecting. + * ``P`` - -\* P - dsn: port; copy: yes Port number to use for connection. - - -\* S + * ``S`` dsn: mysql_socket; copy: yes Socket file to use for connection. - - -\* u + * ``u`` dsn: user; copy: yes User for login if not current user. - - - -*********** ENVIRONMENT -*********** +=========== -The environment variable \ ``PTDEBUG``\ enables verbose debugging output to STDERR. +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-duplicate-key-checker ... > FILE 2>&1 - Be careful: debugging output is voluminous and can generate several megabytes of output. - -******************* SYSTEM REQUIREMENTS -******************* - +=================== You need Perl, DBI, DBD::mysql, and some core packages that ought to be installed in any reasonably new version of Perl. - -**** BUGS -**** - +==== For a list of known bugs, see `http://www.percona.com/bugs/pt-duplicate-key-checker `_. 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 and Daniel Nichter -********************* -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 2007-2011 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 -******* +======= - -pt-duplicate-key-checker 1.0.1 +:doc:`pt-duplicate-key-checker` 1.0.1 diff --git a/docs/user/pt-fifo-split.rst b/docs/user/source/pt-fifo-split.rst similarity index 52% rename from docs/user/pt-fifo-split.rst rename to docs/user/source/pt-fifo-split.rst index 0dba9cbc..dc358c9f 100644 --- a/docs/user/pt-fifo-split.rst +++ b/docs/user/source/pt-fifo-split.rst @@ -1,52 +1,46 @@ +.. program:: pt-fifo-split -############# -pt-fifo-split -############# +========================== + :program:`pt-fifo-split` +========================== .. highlight:: perl -**** NAME -**** +==== + +:program:`pt-fifo-split` - Split files and pipe lines to a fifo without really splitting. -pt-fifo-split - Split files and pipe lines to a fifo without really splitting. - - -******** SYNOPSIS -******** +======== +Usage +----- -Usage: pt-fifo-split [options] [FILE ...] +:: -pt-fifo-split splits FILE and pipes lines to a fifo. With no FILE, or when FILE -is -, read standard input. + pt-fifo-split [options] [FILE ...] + +:program:`pt-fifo-split` splits FILE and pipes lines to a fifo. With no FILE, or when FILE is -, read standard input. Read hugefile.txt in chunks of a million lines without physically splitting it: - .. code-block:: perl pt-fifo-split --lines 1000000 hugefile.txt while [ -e /tmp/pt-fifo-split ]; do cat /tmp/pt-fifo-split; done - - -***** 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-fifo-split creates and/or deletes the "--fifo" file. Otherwise, no other -files are modified, and it merely reads lines from the file given on the -command-line. It should be very low-risk. +:program:`pt-fifo-split` creates and/or deletes the "--fifo" file. Otherwise, no other files are modified, and it merely reads lines from the file given on the command-line. It should be very low-risk. At the time of this release, we know of no bugs that could cause serious harm to users. @@ -58,68 +52,48 @@ see a list of such issues at the following URL: See also "BUGS" for more information on filing bugs and getting help. - -*********** DESCRIPTION -*********** +=========== - -pt-fifo-split lets you read from a file as though it contains only some of the -lines in the file. When you read from it again, it contains the next set of -lines; when you have gone all the way through it, the file disappears. This -works only on Unix-like operating systems. +:program:`pt-fifo-split` lets you read from a file as though it contains only some of the lines in the file. When you read from it again, it contains the next set of lines; when you have gone all the way through it, the file disappears. This works only on Unix-like operating systems. You can specify multiple files on the command line. If you don't specify any, or if you use the special filename \ ``-``\ , lines are read from standard input. - -******* OPTIONS -******* - +======= This tool accepts additional command-line arguments. Refer to the "SYNOPSIS" and usage information for details. - ---config +.. option:: --config type: Array Read this comma-separated list of config files; if specified, this must be the first option on the command line. - - ---fifo +.. option:: --fifo type: string; default: /tmp/pt-fifo-split The name of the fifo from which the lines can be read. - - ---force +.. option:: --force Remove the fifo if it exists already, then create it again. - - ---help +.. option:: --help Show help and exit. - - ---lines +.. option:: --lines type: int; default: 1000 The number of lines to read in each chunk. - - ---offset +.. option:: --offset type: int; default: 0 @@ -128,9 +102,7 @@ This tool accepts additional command-line arguments. Refer to the 0). If 2, the first line is skipped, and the 2nd and subsequent lines are printed to the fifo. - - ---pid +.. option:: --pid type: string @@ -143,27 +115,18 @@ This tool accepts additional command-line arguments. Refer to the script overwrites the file with its own PID and starts; else, if the file contains no PID, then the script dies. - - ---statistics +.. option:: --statistics Print out statistics between chunks. The statistics are the number of chunks, the number of lines, elapsed time, and lines per second overall and during the last chunk. - - ---version +.. option:: --version Show version and exit. - - - -*********** 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: @@ -173,133 +136,36 @@ To enable debugging and capture all output to a file, run the tool like: PTDEBUG=1 pt-fifo-split ... > FILE 2>&1 - Be careful: debugging output is voluminous and can generate several megabytes of output. -******************* SYSTEM REQUIREMENTS -******************* - +=================== You need Perl, DBI, DBD::mysql, and some core packages that ought to be installed in any reasonably new version of Perl. - -**** BUGS -**** - +==== For a list of known bugs, see `http://www.percona.com/bugs/pt-fifo-split `_. 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 2007-2011 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 -******* +======= - -pt-fifo-split 1.0.1 +:program:`pt-fifo-split` 1.0.1 diff --git a/docs/user/pt-find.rst b/docs/user/source/pt-find.rst similarity index 68% rename from docs/user/pt-find.rst rename to docs/user/source/pt-find.rst index 860cf5c7..d38b1d8d 100644 --- a/docs/user/pt-find.rst +++ b/docs/user/source/pt-find.rst @@ -1,38 +1,38 @@ +.. program:: pt-find -####### -pt-find -####### +==================== + :program:`pt-find` +==================== .. highlight:: perl -**** NAME -**** +==== + +:program:`pt-find` - Find |MySQL| tables and execute actions, like GNU find. -pt-find - Find MySQL tables and execute actions, like GNU find. - - -******** SYNOPSIS -******** +======== +Usage +----- -Usage: pt-find [OPTION...] [DATABASE...] +:: -pt-find searches for MySQL tables and executes actions, like GNU find. The + pt-find [OPTION...] [DATABASE...] + +:program:`pt-find` searches for |MySQL| tables and executes actions, like GNU find. The default action is to print the database and table name. Find all tables created more than a day ago, which use the MyISAM engine, and print their names: - .. code-block:: perl pt-find --ctime +1 --engine MyISAM - Find InnoDB tables that haven't been updated in a month, and convert them to MyISAM storage engine (data warehousing, anyone?): @@ -66,7 +66,6 @@ Find tables more than five gigabytes in total size: pt-find --tablesize +5G - Find all tables and print their total data and index size, and sort largest tables first (sort is a different program, by the way). @@ -84,20 +83,15 @@ As above, but this time, insert the data back into the database for posterity: pt-find --noquote --exec "INSERT INTO sysdata.tblsize(db, tbl, size) VALUES('%D', '%N', %T)" - -***** 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-find only reads and prints information by default, but "--exec" and -"--exec-plus" can execute user-defined SQL. You should be as careful with it -as you are with any command-line tool that can execute queries against your +:program:`pt-find` only reads and prints information by default, but :option:`--exec` and :option:`--exec-plus` can execute user-defined SQL. You should be as careful with it as you are with any command-line tool that can execute queries against your database. At the time of this release, we know of no bugs that could cause serious harm to @@ -108,130 +102,95 @@ 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-find `_. -See also "BUGS" for more information on filing bugs and getting help. +See also :ref:`bugs` for more information on filing bugs and getting help. -*********** DESCRIPTION -*********** +=========== +:program:`pt-find` looks for |MySQL| tables that pass the tests you specify, and executes the actions you specify. The default action is to print the database and table +name to ``STDOUT``. -pt-find looks for MySQL tables that pass the tests you specify, and executes -the actions you specify. The default action is to print the database and table -name to STDOUT. +:program:`pt-find` is simpler than *GNU* :command:`find`. It doesn't allow you to specify complicated expressions on the command line. :program:`pt-find` uses ``SHOW TABLES`` when possible, and ``SHOW TABLE STATUS`` when needed. -pt-find is simpler than GNU find. It doesn't allow you to specify -complicated expressions on the command line. - -pt-find uses SHOW TABLES when possible, and SHOW TABLE STATUS when needed. - - -************ OPTION TYPES -************ - +============ There are three types of options: normal options, which determine some behavior or setting; tests, which determine whether a table should be included in the -list of tables found; and actions, which do something to the tables pt-find +list of tables found; and actions, which do something to the tables:program:`pt-find` finds. -pt-find uses standard Getopt::Long option parsing, so you should use double -dashes in front of long option names, unlike GNU find. +:program:`pt-find` uses standard ``Getopt::Long`` option parsing, so you should use double dashes in front of long option names, unlike ``GNU`` :command:`find`. - -******* OPTIONS -******* +======= +This tool accepts additional command-line arguments. Refer to the "SYNOPSIS" and usage information for details. -This tool accepts additional command-line arguments. Refer to the -"SYNOPSIS" and usage information for details. - - ---ask-pass +.. option:: --ask-pass - Prompt for a password when connecting to MySQL. + Prompt for a password when connecting to |MySQL|. - - ---case-insensitive +.. option:: --case-insensitive Specifies that all regular expression searches are case-insensitive. - - ---charset +.. option:: --charset short form: -A; type: string - Default character set. If the value is utf8, sets Perl's binmode on - STDOUT to utf8, passes the mysql_enable_utf8 option to DBD::mysql, and runs SET - NAMES UTF8 after connecting to MySQL. Any other value sets binmode on STDOUT - without the utf8 layer, and runs SET NAMES after connecting to MySQL. + Default character set. If the value is utf8, sets *Perl* 's binmode on + ``STDOUT`` to utf8, passes the mysql_enable_utf8 option to ``DBD::mysql``, and runs SET + NAMES UTF8 after connecting to |MySQL|. Any other value sets binmode on ``STDOUT`` + without the utf8 layer, and runs SET NAMES after connecting to |MySQL|. - - ---config +.. option:: --config type: Array Read this comma-separated list of config files; if specified, this must be the first option on the command line. - - ---day-start +.. option:: --day-start - Measure times (for "--mmin", etc) from the beginning of today rather than + Measure times (for :option:`--mmin`, etc) from the beginning of today rather than from the current time. - - ---defaults-file +.. option:: --defaults-file short form: -F; type: string Only read mysql options from the given file. You must give an absolute pathname. - - ---help +.. option:: --help Show help and exit. - - ---host +.. option:: --host short form: -h; type: string Connect to host. - - ---or +.. option:: --or Combine tests with OR, not AND. By default, tests are evaluated as though there were an AND between them. This option switches it to OR. - Option parsing is not implemented by pt-find itself, so you cannot specify + Option parsing is not implemented by:program:`pt-find` itself, so you cannot specify complicated expressions with parentheses and mixtures of OR and AND. - - ---password +.. option:: --password short form: -p; type: string Password to use when connecting. - - ---pid +.. option:: --pid type: string @@ -244,92 +203,75 @@ This tool accepts additional command-line arguments. Refer to the script overwrites the file with its own PID and starts; else, if the file contains no PID, then the script dies. - - ---port +.. option:: --port short form: -P; type: int Port number to use for connection. - - ---[no]quote +.. option:: --[no]quote default: yes - Quotes MySQL identifier names with MySQL's standard backtick character. + Quotes |MySQL| identifier names with |MySQL|'s standard backtick character. Quoting happens after tests are run, and before actions are run. - - ---set-vars +.. option:: --set-vars type: string; default: wait_timeout=10000 - Set these MySQL variables. Immediately after connecting to MySQL, this string + Set these |MySQL| variables. Immediately after connecting to |MySQL|, this string will be appended to SET and executed. - - ---socket +.. option:: --socket short form: -S; type: string Socket file to use for connection. - - ---user +.. option:: --user short form: -u; type: string User for login if not current user. - - ---version +.. option:: --version Show version and exit. - - TESTS ===== - -Most tests check some criterion against a column of SHOW TABLE STATUS output. +Most tests check some criterion against a column of ``SHOW TABLE STATUS`` output. Numeric arguments can be specified as +n for greater than n, -n for less than n, and n for exactly n. All numeric options can take an optional suffix multiplier of k, M or G (1_024, 1_048_576, and 1_073_741_824 respectively). All patterns -are Perl regular expressions (see 'man perlre') unless specified as SQL LIKE +are *Perl* regular expressions (see 'man perlre') unless specified as SQL LIKE patterns. -Dates and times are all measured relative to the same instant, when pt-find +Dates and times are all measured relative to the same instant, when:program:`pt-find` first asks the database server what time it is. All date and time manipulation is done in SQL, so if you say to find tables modified 5 days ago, that translates to SELECT DATE_SUB(CURRENT_TIMESTAMP, INTERVAL 5 DAY). If you -specify "--day-start", if course it's relative to CURRENT_DATE instead. +specify :option:`--day-start`, if course it's relative to CURRENT_DATE instead. However, table sizes and other metrics are not consistent at an instant in -time. It can take some time for MySQL to process all the SHOW queries, and -pt-find can't do anything about that. These measurements are as of the +time. It can take some time for |MySQL| to process all the SHOW queries, and:program:`pt-find` can't do anything about that. These measurements are as of the time they're taken. If you need some test that's not in this list, file a bug report and I'll -enhance pt-find for you. It's really easy. +enhance:program:`pt-find` for you. It's really easy. ---autoinc +.. option:: --autoinc type: string; group: Tests Table's next AUTO_INCREMENT is n. This tests the Auto_increment column. - ---avgrowlen +.. option:: --avgrowlen type: size; group: Tests @@ -337,40 +279,35 @@ enhance pt-find for you. It's really easy. The specified size can be "NULL" to test where Avg_row_length IS NULL. - ---checksum +.. option:: --checksum type: string; group: Tests Table checksum is n. This tests the Checksum column. - ---cmin +.. option:: --cmin type: size; group: Tests Table was created n minutes ago. This tests the Create_time column. - ---collation +.. option:: --collation type: string; group: Tests Table collation matches pattern. This tests the Collation column. - ---column-name +.. option:: --column-name type: string; group: Tests A column name in the table matches pattern. - ---column-type +.. option:: --column-type type: string; group: Tests @@ -380,28 +317,26 @@ enhance pt-find for you. It's really easy. timestamp, text, enum. - ---comment +.. option:: --comment type: string; group: Tests Table comment matches pattern. This tests the Comment column. - ---connection-id +.. option:: --connection-id type: string; group: Tests - Table name has nonexistent MySQL connection ID. This tests the table name for - a pattern. The argument to this test must be a Perl regular expression that + Table name has nonexistent |MySQL| connection ID. This tests the table name for + a pattern. The argument to this test must be a *Perl* regular expression that captures digits like this: (\d+). If the table name matches the pattern, - these captured digits are taken to be the MySQL connection ID of some process. + these captured digits are taken to be the |MySQL| connection ID of some process. If the connection doesn't exist according to SHOW FULL PROCESSLIST, the test - returns true. If the connection ID is greater than pt-find's own + returns true. If the connection ID is greater than:program:`pt-find`'s own connection ID, the test returns false for safety. - Why would you want to do this? If you use MySQL statement-based replication, + Why would you want to do this? If you use |MySQL| statement-based replication, you probably know the trouble temporary tables can cause. You might choose to work around this by creating real tables with unique names, instead of temporary tables. One way to do this is to append your connection ID to the @@ -412,40 +347,37 @@ enhance pt-find for you. It's really easy. is a candidate for removal. This is how I manage scratch tables, and that's why I included this test in - pt-find. +:program:`pt-find`. - The argument I use to "--connection-id" is "\D_(\d+)$". That finds tables + The argument I use to :option:`--connection-id" is "\D_(\d+)$`. That finds tables with a series of numbers at the end, preceded by an underscore and some non-number character (the latter criterion prevents me from examining tables with a date at the end, which people tend to do: baron_scratch_2007_05_07 for example). It's better to keep the scratch tables separate of course. - If you do this, make sure the user pt-find runs as has the PROCESS privilege! + If you do this, make sure the user:program:`pt-find` runs as has the PROCESS privilege! Otherwise it will only see connections from the same user, and might think some - tables are ready to remove when they're still in use. For safety, pt-find + tables are ready to remove when they're still in use. For safety,:program:`pt-find` checks this for you. - See also "--server-id". + See also :option:`--server-id`. - ---createopts +.. option:: --createopts type: string; group: Tests Table create option matches pattern. This tests the Create_options column. - ---ctime +.. option:: --ctime type: size; group: Tests Table was created n days ago. This tests the Create_time column. - ---datafree +.. option:: --datafree type: size; group: Tests @@ -453,8 +385,7 @@ enhance pt-find for you. It's really easy. The specified size can be "NULL" to test where Data_free IS NULL. - ---datasize +.. option:: --datasize type: size; group: Tests @@ -462,49 +393,43 @@ enhance pt-find for you. It's really easy. The specified size can be "NULL" to test where Data_length IS NULL. - ---dblike +.. option:: --dblike type: string; group: Tests Database name matches SQL LIKE pattern. - ---dbregex +.. option:: --dbregex type: string; group: Tests Database name matches this pattern. - ---empty +.. option:: --empty group: Tests Table has no rows. This tests the Rows column. - ---engine +.. option:: --engine type: string; group: Tests Table storage engine matches this pattern. This tests the Engine column, or in - earlier versions of MySQL, the Type column. + earlier versions of |MySQL|, the Type column. - ---function +.. option:: --function type: string; group: Tests Function definition matches pattern. - ---indexsize +.. option:: --indexsize type: size; group: Tests @@ -512,56 +437,49 @@ enhance pt-find for you. It's really easy. The specified size can be "NULL" to test where Index_length IS NULL. - ---kmin +.. option:: --kmin type: size; group: Tests Table was checked n minutes ago. This tests the Check_time column. - ---ktime +.. option:: --ktime type: size; group: Tests Table was checked n days ago. This tests the Check_time column. - ---mmin +.. option:: --mmin type: size; group: Tests Table was last modified n minutes ago. This tests the Update_time column. - ---mtime +.. option:: --mtime type: size; group: Tests Table was last modified n days ago. This tests the Update_time column. - ---procedure +.. option:: --procedure type: string; group: Tests Procedure definition matches pattern. - ---rowformat +.. option:: --rowformat type: string; group: Tests Table row format matches pattern. This tests the Row_format column. - ---rows +.. option:: --rows type: size; group: Tests @@ -569,13 +487,12 @@ enhance pt-find for you. It's really easy. The specified size can be "NULL" to test where Rows IS NULL. - ---server-id +.. option:: --server-id type: string; group: Tests Table name contains the server ID. If you create temporary tables with the - naming convention explained in "--connection-id", but also add the server ID of the + naming convention explained in :option:`--connection-id`, but also add the server ID of the server on which the tables are created, then you can use this pattern match to ensure tables are dropped only on the server they're created on. This prevents a table from being accidentally dropped on a slave while it's in use (provided @@ -589,8 +506,7 @@ enhance pt-find for you. It's really easy. the table won't be dropped on the slave. - ---tablesize +.. option:: --tablesize type: size; group: Tests @@ -598,89 +514,78 @@ enhance pt-find for you. It's really easy. Index_length columns. - ---tbllike +.. option:: --tbllike type: string; group: Tests Table name matches SQL LIKE pattern. - ---tblregex +.. option:: --tblregex type: string; group: Tests Table name matches this pattern. - ---tblversion +.. option:: --tblversion type: size; group: Tests Table version is n. This tests the Version column. - ---trigger +.. option:: --trigger type: string; group: Tests Trigger action statement matches pattern. - ---trigger-table +.. option:: --trigger-table type: string; group: Tests - "--trigger" is defined on table matching pattern. + :option:`--trigger` is defined on table matching pattern. - ---view +.. option:: --view type: string; group: Tests CREATE VIEW matches this pattern. - - ACTIONS ======= -The "--exec-plus" action happens after everything else, but otherwise actions +The :option:`--exec-plus` action happens after everything else, but otherwise actions happen in an indeterminate order. If you need determinism, file a bug report and I'll add this feature. - ---exec +.. option:: --exec type: string; group: Actions Execute this SQL with each item found. The SQL can contain escapes and - formatting directives (see "--printf"). + formatting directives (see :option:`--printf`). - ---exec-dsn +.. option:: --exec-dsn type: string; group: Actions - Specify a DSN in key-value format to use when executing SQL with "--exec" and - "--exec-plus". Any values not specified are inherited from command-line + Specify a DSN in key-value format to use when executing SQL with :option:`--exec` and + :option:`--exec-plus`. Any values not specified are inherited from command-line arguments. - ---exec-plus +.. option:: --exec-plus type: string; group: Actions - Execute this SQL with all items at once. This option is unlike "--exec". There + Execute this SQL with all items at once. This option is unlike :option:`--exec`. There are no escaping or formatting directives; there is only one special placeholder for the list of database and table names, %s. The list of tables found will be joined together with commas and substituted wherever you place %s. @@ -697,8 +602,7 @@ and I'll add this feature. totally cryptic. And it doesn't require me to write a command-line parser. - ---print +.. option:: --print group: Actions @@ -706,14 +610,13 @@ and I'll add this feature. action if no other action is specified. - ---printf +.. option:: --printf type: string; group: Actions Print format on the standard output, interpreting '\' escapes and '%' - directives. Escapes are backslashed characters, like \n and \t. Perl - interprets these, so you can use any escapes Perl knows about. Directives are + directives. Escapes are backslashed characters, like \n and \t. *Perl* + interprets these, so you can use any escapes *Perl* knows about. Directives are replaced by %s, and as of this writing, you can't add any special formatting instructions, like field widths or alignment (though I'm musing over ways to do that). @@ -734,7 +637,7 @@ and I'll add this feature. C Create_time D Database The database name in which the table lives d Data_length - E Engine In older versions of MySQL, this is Type + E Engine In older versions of |MySQL|, this is Type F Data_free f Innodb_free Parsed from the Comment field I Index_length @@ -750,14 +653,9 @@ and I'll add this feature. U Update_time V Version - - - - -*********** DSN OPTIONS -*********** +=========== These DSN options are used to create a DSN. Each option is given like @@ -767,7 +665,7 @@ if the value contains whitespace it must be quoted. DSN options are comma-separated. See the percona-toolkit manpage for full details. -\* A + * ``A`` dsn: charset; copy: yes @@ -775,203 +673,101 @@ comma-separated. See the percona-toolkit manpage for full details. -\* D + * ``D`` dsn: database; copy: yes Default database. - -\* F + * ``F`` dsn: mysql_read_default_file; copy: yes Only read default options from the given file - -\* h + * ``h`` dsn: host; copy: yes Connect to host. - -\* p + * ``p`` dsn: password; copy: yes Password to use when connecting. - -\* P + * ``p`` dsn: port; copy: yes Port number to use for connection. - -\* S + * ``S`` dsn: mysql_socket; copy: yes Socket file to use for connection. - -\* u + * ``u`` dsn: user; copy: yes User for login if not current user. - - -*********** ENVIRONMENT -*********** +=========== -The environment variable \ ``PTDEBUG``\ enables verbose debugging output to STDERR. +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-find ... > FILE 2>&1 + PTDEBUG=1: pt-find ... > FILE 2>&1 Be careful: debugging output is voluminous and can generate several megabytes of output. -******************* SYSTEM REQUIREMENTS -******************* +=================== -You need Perl, DBI, DBD::mysql, and some core packages that ought to be -installed in any reasonably new version of Perl. +You need *Perl* , ``DBI``, ``DBD::mysql``, and some core packages that ought to be +installed in any reasonably new version of *Perl* . -**** BUGS -**** +==== For a list of known bugs, see `http://www.percona.com/bugs/pt-find `_. 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 2007-2011 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 -******* +======= - -pt-find 1.0.1 +:program:`pt-find` 1.0.1 diff --git a/docs/user/pt-fk-error-logger.rst b/docs/user/source/pt-fk-error-logger.rst similarity index 56% rename from docs/user/pt-fk-error-logger.rst rename to docs/user/source/pt-fk-error-logger.rst index 7e8af47b..b72bd045 100644 --- a/docs/user/pt-fk-error-logger.rst +++ b/docs/user/source/pt-fk-error-logger.rst @@ -1,35 +1,36 @@ +.. program:: pt-fk-error-logger -################## -pt-fk-error-logger -################## +=============================== + :program:`pt-fk-error-logger` +=============================== .. highlight:: perl -**** NAME -**** +==== + +:program:`pt-fk-error-logger` - Extract and log |MySQL| foreign key errors. -pt-fk-error-logger - Extract and log MySQL foreign key errors. - - -******** SYNOPSIS -******** +======== -Usage: pt-fk-error-logger [OPTION...] SOURCE_DSN +Usage +----- -pt-fk-error-logger extracts and saves information about the most recent foreign -key errors in a MySQL server. +:: + + pt-fk-error-logger [OPTION...] SOURCE_DSN + +:program:`pt-fk-error-logger` extracts and saves information about the most recent foreign key errors in a |MySQL| server. Print foreign key errors on host1: - .. code-block:: perl - pt-fk-error-logger h=host1 + :program:`pt-fk-error-logger` h=host1 Save foreign key errors on host1 to db.foreign_key_errors table on host2: @@ -40,19 +41,15 @@ Save foreign key errors on host1 to db.foreign_key_errors table on host2: pt-fk-error-logger h=host1 --dest h=host1,D=db,t=foreign_key_errors - -***** 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-fk-error-logger is read-only unless you specify "--dest". It should be -very low-risk. +:program:`pt-fk-error-logger` is read-only unless you specify :option:`--dest`. It should be very low-risk. At the time of this release, we know of no bugs that could cause serious harm to users. @@ -62,57 +59,42 @@ 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-fk-error-logger `_. -See also "BUGS" for more information on filing bugs and getting help. +See also :ref:`bugs` for more information on filing bugs and getting help. - -*********** DESCRIPTION -*********** +=========== - -pt-fk-error-logger prints or saves the foreign key errors text from +:program:`pt-fk-error-logger` prints or saves the foreign key errors text from \ ``SHOW INNODB STATUS``\ . The errors are not parsed or interpreted in any way. Foreign key errors are uniquely identified by their timestamp. Only new (more recent) errors are printed or saved. - -****** OUTPUT -****** +====== +If :option:`--print` is given or no :option:`--dest` is given, then :program:`pt-fk-error-logger` prints the foreign key error text to ``STDOUT`` exactly as it appeared in ``SHOW INNODB STATUS``. -If "--print" is given or no "--dest" is given, then pt-fk-error-logger -prints the foreign key error text to STDOUT exactly as it appeared in -\ ``SHOW INNODB STATUS``\ . - - -******* OPTIONS -******* - +======= This tool accepts additional command-line arguments. Refer to the "SYNOPSIS" and usage information for details. - ---ask-pass +.. option:: --ask-pass - Prompt for a password when connecting to MySQL. + Prompt for a password when connecting to |MySQL|. - - ---charset +.. option:: --charset short form: -A; type: string - Default character set. If the value is utf8, sets Perl's binmode on - STDOUT to utf8, passes the mysql_enable_utf8 option to DBD::mysql, and runs SET - NAMES UTF8 after connecting to MySQL. Any other value sets binmode on STDOUT - without the utf8 layer, and runs SET NAMES after connecting to MySQL. + Default character set. If the value is utf8, sets *Perl* 's binmode on + ``STDOUT`` to utf8, passes the mysql_enable_utf8 option to ``DBD::mysql``, and runs SET + NAMES UTF8 after connecting to |MySQL|. Any other value sets binmode on ``STDOUT`` + without the utf8 layer, and runs SET NAMES after connecting to |MySQL|. - ---config +.. option:: --config type: Array @@ -120,14 +102,12 @@ This tool accepts additional command-line arguments. Refer to the first option on the command line. - ---daemonize +.. option:: --daemonize Fork to the background and detach from the shell. POSIX operating systems only. - ---defaults-file +.. option:: --defaults-file short form: -F; type: string @@ -135,8 +115,7 @@ This tool accepts additional command-line arguments. Refer to the pathname. - ---dest +.. option:: --dest type: DSN @@ -157,18 +136,16 @@ This tool accepts additional command-line arguments. Refer to the PRIMARY KEY (ts), ) - + The only information saved is the timestamp and the foreign key error text. - - ---help +.. option:: --help Show help and exit. ---host +.. option:: --host short form: -h; type: string @@ -176,7 +153,7 @@ This tool accepts additional command-line arguments. Refer to the ---interval +.. option:: --interval type: time; default: 0 @@ -184,7 +161,7 @@ This tool accepts additional command-line arguments. Refer to the ---log +.. option:: --log type: string @@ -192,7 +169,7 @@ This tool accepts additional command-line arguments. Refer to the ---password +.. option:: --password short form: -p; type: string @@ -200,7 +177,7 @@ This tool accepts additional command-line arguments. Refer to the ---pid +.. option:: --pid type: string @@ -211,7 +188,7 @@ This tool accepts additional command-line arguments. Refer to the ---port +.. option:: --port short form: -P; type: int @@ -219,13 +196,13 @@ This tool accepts additional command-line arguments. Refer to the ---print +.. option:: --print Print results on standard output. See "OUTPUT" for more. ---run-time +.. option:: --run-time type: time @@ -233,16 +210,16 @@ This tool accepts additional command-line arguments. Refer to the ---set-vars +.. option:: --set-vars type: string; default: wait_timeout=10000 - Set these MySQL variables. Immediately after connecting to MySQL, this string + Set these |MySQL| variables. Immediately after connecting to |MySQL|, this string will be appended to SET and executed. ---socket +.. option:: --socket short form: -S; type: string @@ -250,7 +227,7 @@ This tool accepts additional command-line arguments. Refer to the ---user +.. option:: --user short form: -u; type: string @@ -258,16 +235,15 @@ This tool accepts additional command-line arguments. Refer to the ---version +.. option:: --version Show version and exit. -*********** DSN OPTIONS -*********** +=========== These DSN options are used to create a DSN. Each option is given like @@ -277,7 +253,7 @@ if the value contains whitespace it must be quoted. DSN options are comma-separated. See the percona-toolkit manpage for full details. -\* A + * ``A`` dsn: charset; copy: yes @@ -285,7 +261,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* D + * ``D`` dsn: database; copy: yes @@ -293,7 +269,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* F + * ``F`` dsn: mysql_read_default_file; copy: yes @@ -301,7 +277,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* h + * ``h`` dsn: host; copy: yes @@ -309,7 +285,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* p + * ``p`` dsn: password; copy: yes @@ -317,7 +293,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* P + * ``p`` dsn: port; copy: yes @@ -325,7 +301,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* S + * ``S`` dsn: mysql_socket; copy: yes @@ -333,13 +309,12 @@ comma-separated. See the percona-toolkit manpage for full details. -\* t + * ``t`` Table in which to store foreign key errors. - -\* u + * ``u`` dsn: user; copy: yes @@ -347,13 +322,11 @@ comma-separated. See the percona-toolkit manpage for full details. - -*********** ENVIRONMENT -*********** +=========== -The environment variable \ ``PTDEBUG``\ enables verbose debugging output to STDERR. +The environment variable \ ``PTDEBUG``\ enables verbose debugging output to ``STDERR``. To enable debugging and capture all output to a file, run the tool like: @@ -366,128 +339,39 @@ Be careful: debugging output is voluminous and can generate several megabytes of output. -******************* SYSTEM REQUIREMENTS -******************* +=================== -You need Perl, DBI, DBD::mysql, and some core packages that ought to be -installed in any reasonably new version of Perl. +You need *Perl* , ``DBI``, ``DBD::mysql``, and some core packages that ought to be +installed in any reasonably new version of *Perl* . -**** BUGS -**** +==== For a list of known bugs, see `http://www.percona.com/bugs/pt-fk-error-logger `_. 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 -******* - +======= Daniel Nichter -********************* -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 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 -******* +======= - -pt-fk-error-logger 1.0.1 +:program:`pt-fk-error-logger` 1.0.1 diff --git a/docs/user/pt-heartbeat.rst b/docs/user/source/pt-heartbeat.rst similarity index 54% rename from docs/user/pt-heartbeat.rst rename to docs/user/source/pt-heartbeat.rst index 141813db..9998fd02 100644 --- a/docs/user/pt-heartbeat.rst +++ b/docs/user/source/pt-heartbeat.rst @@ -1,29 +1,31 @@ +.. program:: pt-heartbeat -############ -pt-heartbeat -############ +========================= + :program:`pt-heartbeat` +========================= .. highlight:: perl -**** NAME -**** +==== + +:program:`pt-heartbeat` - Monitor |MySQL| replication delay. -pt-heartbeat - Monitor MySQL replication delay. - - -******** SYNOPSIS -******** +======== -Usage: pt-heartbeat [OPTION...] [DSN] --update|--monitor|--check|--stop +Usage +----- -pt-heartbeat measures replication lag on a MySQL or PostgreSQL server. You can -use it to update a master or monitor a replica. If possible, MySQL connection -options are read from your .my.cnf file. +:: + + pt-heartbeat [OPTION...] [DSN] --update|--monitor|--check|--stop + +:program:`pt-heartbeat` measures replication lag on a |MySQL| or *PostgreSQL* server. You can use it to update a master or monitor a replica. If possible, |MySQL| connection +options are read from your :file:`.my.cnf` file. Start daemonized process to update test.heartbeat table on master: @@ -52,9 +54,8 @@ Check slave lag once and exit (using optional DSN to specify slave host): -***** RISKS -***** +===== The following section is included to inform users about the potential risks, @@ -62,8 +63,7 @@ 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-heartbeat merely reads and writes a single record in a table. It should be -very low-risk. +:program:`pt-heartbeat` merely reads and writes a single record in a table. It should be very low-risk. At the time of this release, we know of no bugs that could cause serious harm to users. @@ -73,85 +73,67 @@ 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-heartbeat `_. -See also "BUGS" for more information on filing bugs and getting help. +See also :ref:`bugs` for more information on filing bugs and getting help. -*********** DESCRIPTION -*********** +=========== - -pt-heartbeat is a two-part MySQL and PostgreSQL replication delay monitoring -system that measures delay by looking at actual replicated data. This +:program:`pt-heartbeat` is a two-part |MySQL| and *PostgreSQL* replication delay monitoring system that measures delay by looking at actual replicated data. This avoids reliance on the replication mechanism itself, which is unreliable. (For -example, \ ``SHOW SLAVE STATUS``\ on MySQL). +example, \ ``SHOW SLAVE STATUS``\ on |MySQL|). -The first part is an "--update" instance of pt-heartbeat that connects to -a master and updates a timestamp ("heartbeat record") every "--interval" -seconds. Since the heartbeat table may contain records from multiple -masters (see "MULTI-SLAVE HIERARCHY"), the server's ID (@@server_id) is +The first part is an :option:`--update` instance of:program:`pt-heartbeat` that connects to a master and updates a timestamp ("heartbeat record") every :option:`--interval` seconds. Since the heartbeat table may contain records from multiple masters (see "MULTI-SLAVE HIERARCHY"), the server's ID (@@server_id) is used to identify records. -The second part is a "--monitor" or "--check" instance of pt-heartbeat -that connects to a slave, examines the replicated heartbeat record from its -immediate master or the specified "--master-server-id", and computes the -difference from the current system time. If replication between the slave and -the master is delayed or broken, the computed difference will be greater than -zero and potentially increase if "--monitor" is specified. +The second part is a :option:`--monitor" or "--check` instance of :program:`pt-heartbeat` that connects to a slave, examines the replicated heartbeat record from its immediate master or the specified :option:`--master-server-id`, and computes the difference from the current system time. If replication between the slave and the master is delayed or broken, the computed difference will be greater than zero and potentially increase if :option:`--monitor` is specified. You must either manually create the heartbeat table on the master or use -"--create-table". See "--create-table" for the proper heartbeat +:option:`--create-table`. See :option:`--create-table` for the proper heartbeat table structure. The \ ``MEMORY``\ storage engine is suggested, but not -required of course, for MySQL. +required of course, for |MySQL|. The heartbeat table must contain a heartbeat row. By default, a heartbeat row is inserted if it doesn't exist. This feature can be disabled with the -"--[no]insert-heartbeat-row" option in case the database user does not +:option:`--[no]insert-heartbeat-row` option in case the database user does not have INSERT privileges. -pt-heartbeat depends only on the heartbeat record being replicated to the slave, -so it works regardless of the replication mechanism (built-in replication, a +:program:`pt-heartbeat` depends only on the heartbeat record being replicated to the slave, so it works regardless of the replication mechanism (built-in replication, a system such as Continuent Tungsten, etc). It works at any depth in the replication hierarchy; for example, it will reliably report how far a slave lags its master's master's master. And if replication is stopped, it will continue to work and report (accurately!) that the slave is falling further and further behind the master. -pt-heartbeat has a maximum resolution of 0.01 second. The clocks on the +:program:`pt-heartbeat` has a maximum resolution of 0.01 second. The clocks on the master and slave servers must be closely synchronized via NTP. By default, -"--update" checks happen on the edge of the second (e.g. 00:01) and -"--monitor" checks happen halfway between seconds (e.g. 00:01.5). -As long as the servers' clocks are closely synchronized and replication -events are propagating in less than half a second, pt-heartbeat will report -zero seconds of delay. +:option:`--update` checks happen on the edge of the second (e.g. 00:01) and +:option:`--monitor` checks happen halfway between seconds (e.g. 00:01.5). -pt-heartbeat will try to reconnect if the connection has an error, but will +As long as the servers' clocks are closely synchronized and replication events are propagating in less than half a second, :program:`pt-heartbeat` will report zero seconds of delay. + +:program:`pt-heartbeat` will try to reconnect if the connection has an error, but will not retry if it can't get a connection when it first starts. -The "--dbi-driver" option lets you use pt-heartbeat to monitor PostgreSQL -as well. It is reported to work well with Slony-1 replication. +The :option:`--dbi-driver` option lets you use :program:`pt-heartbeat` to monitor *PostgreSQL* as well. It is reported to work well with Slony-1 replication. -********************* MULTI-SLAVE HIERARCHY -********************* +===================== If the replication hierarchy has multiple slaves which are masters of -other slaves, like "master -> slave1 -> slave2", "--update" instances +other slaves, like "master -> slave1 -> slave2", :option:`--update` instances can be ran on the slaves as well as the master. The default heartbeat -table (see "--create-table") is keyed on the \ ``server_id``\ column, so +table (see :option:`--create-table`) is keyed on the \ ``server_id``\ column, so each server will update the row where \ ``server_id=@@server_id``\ . -For "--monitor" and "--check", if "--master-server-id" is not -specified, the tool tries to discover and use the slave's immediate master. -If this fails, or if you want monitor lag from another master, then you can -specify the "--master-server-id" to use. +For :option:`--monitor` and :option:`--check`, if :option:`--master-server-id` is not +specified, the tool tries to discover and use the slave's immediate master. If this fails, or if you want monitor lag from another master, then you can specify the :option:`--master-server-id` to use. For example, if the replication hierarchy is "master -> slave1 -> slave2" with corresponding server IDs 1, 2 and 3, you can: - .. code-block:: perl pt-heartbeat --daemonize -D test --update -h master @@ -174,78 +156,66 @@ Or check the replication delay from slave1 to slave2: pt-heartbeat -D test --master-server-id 2 --check slave2 -Stopping the "--update" instance one slave1 will not affect the instance +Stopping the :option:`--update` instance one slave1 will not affect the instance on master. -*********************** MASTER AND SLAVE STATUS -*********************** +======================= -The default heartbeat table (see "--create-table") has columns for saving +The default heartbeat table (see :option:`--create-table`) has columns for saving information from \ ``SHOW MASTER STATUS``\ and \ ``SHOW SLAVE STATUS``\ . These columns are optional. If any are present, their corresponding information will be saved. -******* OPTIONS -******* +======= -Specify at least one of "--stop", "--update", "--monitor", or "--check". +Specify at least one of :option:`--stop`, :option:`--update`, :option:`--monitor`, or :option:`--check`. -"--update", "--monitor", and "--check" are mutually exclusive. +:option:`--update`, :option:`--monitor`, and :option:`--check` are mutually exclusive. -"--daemonize" and "--check" are mutually exclusive. +:option:`--daemonize` and :option:`--check` are mutually exclusive. -This tool accepts additional command-line arguments. Refer to the -"SYNOPSIS" and usage information for details. +This tool accepts additional command-line arguments. Refer to the "SYNOPSIS" and usage information for details. - ---ask-pass +.. option:: --ask-pass - Prompt for a password when connecting to MySQL. + Prompt for a password when connecting to |MySQL|. - - ---charset +.. option:: --charset short form: -A; type: string - Default character set. If the value is utf8, sets Perl's binmode on STDOUT to + Default character set. If the value is utf8, sets *Perl* 's binmode on ``STDOUT`` to utf8, passes the mysql_enable_utf8 option to DBD::mysql, and runs SET NAMES UTF8 - after connecting to MySQL. Any other value sets binmode on STDOUT without the - utf8 layer, and runs SET NAMES after connecting to MySQL. + after connecting to |MySQL|. Any other value sets binmode on ``STDOUT`` without the + utf8 layer, and runs SET NAMES after connecting to |MySQL|. - - ---check +.. option:: --check - Check slave delay once and exit. If you also specify "--recurse", the + Check slave delay once and exit. If you also specify :option:`--recurse`, the tool will try to discover slave's of the given slave and check and print their lag, too. The hostname or IP and port for each slave is printed - before its delay. "--recurse" only works with MySQL. + before its delay. :option:`--recurse` only works with |MySQL|. - - ---config +.. option:: --config type: Array Read this comma-separated list of config files; if specified, this must be the first option on the command line. - - ---create-table +.. option:: --create-table - Create the heartbeat "--table" if it does not exist. + Create the heartbeat :option:`--table` if it does not exist. - This option causes the table specified by "--database" and "--table" to + This option causes the table specified by :option:`--database" and "--table` to be created with the following MAGIC_create_heartbeat table definition: - + .. code-block:: perl @@ -258,7 +228,7 @@ This tool accepts additional command-line arguments. Refer to the exec_master_log_pos bigint unsigned DEFAULT NULL -- SHOW SLAVE STATUS ); - + The heartbeat table requires at least one row. If you manually create the heartbeat table, then you must insert a row by doing: @@ -267,15 +237,15 @@ This tool accepts additional command-line arguments. Refer to the INSERT INTO heartbeat (ts, server_id) VALUES (NOW(), N); - + where \ ``N``\ is the server's ID; do not use @@server_id because it will replicate and slaves will insert their own server ID instead of the master's server ID. - This is done automatically by "--create-table". + This is done automatically by :option:`--create-table`. A legacy version of the heartbeat table is still supported: - + .. code-block:: perl CREATE TABLE heartbeat ( @@ -283,8 +253,8 @@ This tool accepts additional command-line arguments. Refer to the ts datetime NOT NULL ); - - Legacy tables do not support "--update" instances on each slave + + Legacy tables do not support :option:`--update` instances on each slave of a multi-slave hierarchy like "master -> slave1 -> slave2". To manually insert the one required row into a legacy table: @@ -299,30 +269,26 @@ This tool accepts additional command-line arguments. Refer to the See also "MULTI-SLAVE HIERARCHY". - ---daemonize +.. option:: --daemonize Fork to the background and detach from the shell. POSIX operating systems only. - ---database +.. option:: --database short form: -D; type: string The database to use for the connection. - ---dbi-driver +.. option:: --dbi-driver default: mysql; type: string Specify a driver for the connection; \ ``mysql``\ and \ ``Pg``\ are supported. - ---defaults-file +.. option:: --defaults-file short form: -F; type: string @@ -330,41 +296,37 @@ This tool accepts additional command-line arguments. Refer to the pathname. - ---file +.. option:: --file type: string - Print latest "--monitor" output to this file. + Print latest :option:`--monitor` output to this file. - When "--monitor" is given, prints output to the specified file instead of to - STDOUT. The file is opened, truncated, and closed every interval, so it will - only contain the most recent statistics. Useful when "--daemonize" is given. + When :option:`--monitor` is given, prints output to the specified file instead of to + ``STDOUT``. The file is opened, truncated, and closed every interval, so it will + only contain the most recent statistics. Useful when :option:`--daemonize` is given. - ---frames +.. option:: --frames type: string; default: 1m,5m,15m Timeframes for averages. Specifies the timeframes over which to calculate moving averages when - "--monitor" is given. Specify as a comma-separated list of numbers with + :option:`--monitor` is given. Specify as a comma-separated list of numbers with suffixes. The suffix can be s for seconds, m for minutes, h for hours, or d for days. The size of the largest frame determines the maximum memory usage, as up to the specified number of per-second samples are kept in memory to calculate the averages. You can specify as many timeframes as you like. - ---help +.. option:: --help Show help and exit. - ---host +.. option:: --host short form: -h; type: string @@ -372,34 +334,32 @@ This tool accepts additional command-line arguments. Refer to the ---[no]insert-heartbeat-row +.. option:: --[no]insert-heartbeat-row default: yes - Insert a heartbeat row in the "--table" if one doesn't exist. + Insert a heartbeat row in the :option:`--table` if one doesn't exist. - The heartbeat "--table" requires a heartbeat row, else there's nothing - to "--update", "--monitor", or "--check"! By default, the tool will - insert a heartbeat row if one is not already present. You can disable this + The heartbeat :option:`--table` requires a heartbeat row, else there's nothing + to :option:`--update`, :option:`--monitor`, or :option:`--check`! By default, the tool will insert a heartbeat row if one is not already present. You can disable this feature by specifying \ ``--no-insert-heartbeat-row``\ in case the database user does not have INSERT privileges. - ---interval +.. option:: --interval type: float; default: 1.0 - How often to update or check the heartbeat "--table". Updates and checks - begin on the first whole second then repeat every "--interval" seconds - for "--update" and every "--interval" plus "--skew" seconds for - "--monitor". + How often to update or check the heartbeat :option:`--table`. Updates and checks + begin on the first whole second then repeat every :option:`--interval` seconds + for :option:`--update` and every :option:`--interval` plus :option:`--skew` seconds for + :option:`--monitor`. - For example, if at 00:00.4 an "--update" instance is started at 0.5 second + For example, if at 00:00.4 an :option:`--update` instance is started at 0.5 second intervals, the first update happens at 00:01.0, the next at 00:01.5, etc. - If at 00:10.7 a "--monitor" instance is started at 0.05 second intervals - with the default 0.5 second "--skew", then the first check happens at - 00:11.5 (00:11.0 + 0.5) which will be "--skew" seconds after the last update + If at 00:10.7 a :option:`--monitor` instance is started at 0.05 second intervals + with the default 0.5 second :option:`--skew`, then the first check happens at + 00:11.5 (00:11.0 + 0.5) which will be :option:`--skew` seconds after the last update which, because the instances are checking at synchronized intervals, happened at 00:11.0. @@ -410,55 +370,48 @@ This tool accepts additional command-line arguments. Refer to the The minimum (fastest) interval is 0.01, and the maximum precision is two decimal places, so 0.015 will be rounded to 0.02. - If a legacy heartbeat table (see "--create-table") is used, then the + If a legacy heartbeat table (see :option:`--create-table`) is used, then the maximum precision is 1s because the \ ``ts``\ column is type \ ``datetime``\ . - - ---log +.. option:: --log type: string Print all output to this file when daemonized. - ---master-server-id +.. option:: --master-server-id type: string - Calculate delay from this master server ID for "--monitor" or "--check". - If not given, pt-heartbeat attempts to connect to the server's master and + Calculate delay from this master server ID for :option:`--monitor" or "--check`. + If not given,:program:`pt-heartbeat` attempts to connect to the server's master and determine its server id. - ---monitor +.. option:: --monitor Monitor slave delay continuously. - Specifies that pt-heartbeat should check the slave's delay every second and - report to STDOUT (or if "--file" is given, to the file instead). The output + Specifies that:program:`pt-heartbeat` should check the slave's delay every second and + report to ``STDOUT`` (or if :option:`--file` is given, to the file instead). The output is the current delay followed by moving averages over the timeframe given in - "--frames". For example, + :option:`--frames`. For example, .. code-block:: perl 5s [ 0.25s, 0.05s, 0.02s ] - - ---password +.. option:: --password short form: -p; type: string Password to use when connecting. - ---pid +.. option:: --pid type: string @@ -468,38 +421,34 @@ This tool accepts additional command-line arguments. Refer to the it exists and the process with the matching PID exists, the program exits. - ---port +.. option:: --port short form: -P; type: int Port number to use for connection. - ---print-master-server-id +.. option:: --print-master-server-id - Print the auto-detected or given "--master-server-id". If "--check" - or "--monitor" is specified, specifying this option will print the - auto-detected or given "--master-server-id" at the end of each line. + Print the auto-detected or given :option:`--master-server-id". If "--check` + or :option:`--monitor` is specified, specifying this option will print the + auto-detected or given :option:`--master-server-id` at the end of each line. - ---recurse +.. option:: --recurse type: int - Check slaves recursively to this depth in "--check" mode. + Check slaves recursively to this depth in :option:`--check` mode. Try to discover slave servers recursively, to the specified depth. After discovering servers, run the check on each one of them and print the hostname (if possible), followed by the slave delay. - This currently works only with MySQL. See "--recursion-method". + This currently works only with |MySQL|. See :option:`--recursion-method`. - ---recursion-method +.. option:: --recursion-method type: string @@ -507,7 +456,7 @@ This tool accepts additional command-line arguments. Refer to the Possible methods are: - + .. code-block:: perl METHOD USES @@ -518,24 +467,21 @@ This tool accepts additional command-line arguments. Refer to the The processlist method is preferred because SHOW SLAVE HOSTS is not reliable. However, the hosts method is required if the server uses a non-standard - port (not 3306). Usually pt-heartbeat does the right thing and finds + port (not 3306). Usually:program:`pt-heartbeat` does the right thing and finds the slaves, but you may give a preferred method and it will be used first. If it doesn't find any slaves, the other methods will be tried. ---replace +.. option:: --replace Use \ ``REPLACE``\ instead of \ ``UPDATE``\ for --update. - When running in "--update" mode, use \ ``REPLACE``\ instead of \ ``UPDATE``\ to set - the heartbeat table's timestamp. The \ ``REPLACE``\ statement is a MySQL extension - to SQL. This option is useful when you don't know whether the table contains + When running in :option:`--update` mode, use \ ``REPLACE``\ instead of \ ``UPDATE``\ to set the heartbeat table's timestamp. The \ ``REPLACE``\ statement is a |MySQL| extension to SQL. This option is useful when you don't know whether the table contains any rows or not. It must be used in conjunction with --update. - ---run-time +.. option:: --run-time type: time @@ -543,7 +489,7 @@ This tool accepts additional command-line arguments. Refer to the ---sentinel +.. option:: --sentinel type: string; default: /tmp/pt-heartbeat-sentinel @@ -551,16 +497,16 @@ This tool accepts additional command-line arguments. Refer to the ---set-vars +.. option:: --set-vars type: string; default: wait_timeout=10000 - Set these MySQL variables. Immediately after connecting to MySQL, this string + Set these |MySQL| variables. Immediately after connecting to |MySQL|, this string will be appended to SET and executed. ---skew +.. option:: --skew type: float; default: 0.5 @@ -576,7 +522,7 @@ This tool accepts additional command-line arguments. Refer to the ---socket +.. option:: --socket short form: -S; type: string @@ -584,75 +530,63 @@ This tool accepts additional command-line arguments. Refer to the ---stop +.. option:: --stop Stop running instances by creating the sentinel file. This should have the effect of stopping all running instances which are watching the same sentinel file. If none of - "--update", "--monitor" or "--check" is specified, \ ``pt-heartbeat``\ - will exit after creating the file. If one of these is specified, - \ ``pt-heartbeat``\ will wait the interval given by "--interval", then remove - the file and continue working. + :option:`--update`, :option:`--monitor` or :option:`--check` is specified, :program:`pt-heartbeat` will exit after creating the file. If one of these is specified, `:program:`pt-heartbeat` will wait the interval given by :option:`--interval`, then remove the file and continue working. You might find this handy to stop cron jobs gracefully if necessary, or to replace one running instance with another. For example, if you want to stop - and restart \ ``pt-heartbeat``\ every hour (just to make sure that it is restarted - every hour, in case of a server crash or some other problem), you could use a - \ ``crontab``\ line like this: + and restart :program:`pt-heartbeat` every hour (just to make sure that it is restarted + every hour, in case of a server crash or some other problem), you could use a \ ``crontab``\ line like this: .. code-block:: perl - 0 * * * * pt-heartbeat --update -D test --stop \ + 0 * * * *:program:`pt-heartbeat` --update -D test --stop \ --sentinel /tmp/pt-heartbeat-hourly - The non-default "--sentinel" will make sure the hourly \ ``cron``\ job stops + The non-default :option:`--sentinel` will make sure the hourly \ ``cron``\ job stops only instances previously started with the same options (that is, from the same \ ``cron``\ job). - See also "--sentinel". + See also :option:`--sentinel`. - ---table +.. option:: --table type: string; default: heartbeat The table to use for the heartbeat. - Don't specify database.table; use "--database" to specify the database. + Don't specify database.table; use :option:`--database` to specify the database. - See "--create-table". + See :option:`--create-table`. - ---update +.. option:: --update Update a master's heartbeat. - ---user +.. option:: --user short form: -u; type: string User for login if not current user. - ---version +.. option:: --version Show version and exit. - - -*********** DSN OPTIONS -*********** - +=========== These DSN options are used to create a DSN. Each option is given like \ ``option=value``\ . The options are case-sensitive, so P and p are not the @@ -661,63 +595,56 @@ if the value contains whitespace it must be quoted. DSN options are comma-separated. See the percona-toolkit manpage for full details. -\* A + * ``A`` dsn: charset; copy: yes Default character set. - -\* D + * ``D`` dsn: database; copy: yes Default database. - -\* F + * ``F`` dsn: mysql_read_default_file; copy: yes Only read default options from the given file - -\* h + * ``h`` dsn: host; copy: yes Connect to host. - -\* p + * ``p`` dsn: password; copy: yes Password to use when connecting. - -\* P + * ``p`` dsn: port; copy: yes Port number to use for connection. - -\* S + * ``S`` dsn: mysql_socket; copy: yes Socket file to use for connection. - -\* u + * ``u`` dsn: user; copy: yes @@ -725,13 +652,11 @@ comma-separated. See the percona-toolkit manpage for full details. - -*********** ENVIRONMENT -*********** +=========== -The environment variable \ ``PTDEBUG``\ enables verbose debugging output to STDERR. +The environment variable \ ``PTDEBUG``\ enables verbose debugging output to ``STDERR``. To enable debugging and capture all output to a file, run the tool like: @@ -744,131 +669,37 @@ Be careful: debugging output is voluminous and can generate several megabytes of output. -******************* SYSTEM REQUIREMENTS -******************* +=================== -You need Perl, DBI, DBD::mysql, and some core packages that ought to be -installed in any reasonably new version of Perl. +You need *Perl* , ``DBI``, ``DBD::mysql``, and some core packages that ought to be +installed in any reasonably new version of *Perl* . -**** BUGS -**** +==== For a list of known bugs, see `http://www.percona.com/bugs/pt-heartbeat `_. 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 -******* +======= + +*Proven Scaling LLC*, *SixApart Ltd*, *Baron Schwartz*, and *Daniel Nichter* -Proven Scaling LLC, SixApart Ltd, Baron Schwartz, and Daniel Nichter - - -********************* -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 2006 Proven Scaling LLC and Six Apart Ltd, -2007-2011 Percona Inc. -Feedback and improvements are welcome. +2007-2011 Percona Inc. Feedback and improvements are welcome. -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 -******* +======= - -pt-heartbeat 1.0.1 +:program:`pt-heartbeat` 1.0.1 diff --git a/docs/user/pt-index-usage.rst b/docs/user/source/pt-index-usage.rst similarity index 71% rename from docs/user/pt-index-usage.rst rename to docs/user/source/pt-index-usage.rst index fc438df6..fd0f6697 100644 --- a/docs/user/pt-index-usage.rst +++ b/docs/user/source/pt-index-usage.rst @@ -1,27 +1,30 @@ +.. program:: pt-index-usage -############## -pt-index-usage -############## +=========================== + :program:`pt-index-usage` +=========================== .. highlight:: perl -**** NAME -**** +==== + + :program:`pt-index-usage` - Read queries from a log and analyze how they use indexes. -pt-index-usage - Read queries from a log and analyze how they use indexes. - - -******** SYNOPSIS -******** +======== -Usage: pt-index-usage [OPTION...] [FILE...] +Usage +----- -pt-index-usage reads queries from logs and analyzes how they use indexes. +:: + + pt-index-usage [OPTION...] [FILE...] + + :program:`pt-index-usage` reads queries from logs and analyzes how they use indexes. Analyze queries in slow.log and print reports: @@ -40,9 +43,8 @@ Disable reports and save results to mk database for later analysis: -***** RISKS -***** +===== The following section is included to inform users about the potential risks, @@ -50,7 +52,7 @@ 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. -This tool is read-only unless you use "--save-results-database". It reads a +This tool is read-only unless you use :option:`--save-results-database`. It reads a log of queries and EXPLAIN them. It also gathers information about all tables in all databases. It should be very low-risk. @@ -62,21 +64,20 @@ 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-index-usage `_. -See also "BUGS" for more information on filing bugs and getting help. +See also :ref:`bugs` for more information on filing bugs and getting help. -*********** DESCRIPTION -*********** +=========== -This tool connects to a MySQL database server, reads through a query log, and -uses EXPLAIN to ask MySQL how it will use each query. When it is finished, it +This tool connects to a |MySQL| database server, reads through a query log, and +uses EXPLAIN to ask |MySQL| how it will use each query. When it is finished, it prints out a report on indexes that the queries didn't use. -The query log needs to be in MySQL's slow query log format. If you need to +The query log needs to be in |MySQL|'s slow query log format. If you need to input a different format, you can use pt-query-digest to translate the -formats. If you don't specify a filename, the tool reads from STDIN. +formats. If you don't specify a filename, the tool reads from ``STDIN``. The tool runs two stages. In the first stage, the tool takes inventory of all the tables and indexes in your database, so it can compare the existing indexes @@ -122,50 +123,44 @@ query parsing. So please submit your test cases based on the errors the tool prints! -****** OUTPUT -****** - +====== After it reads all the events in the log, the tool prints out DROP statements for every index that was not used. It skips indexes for tables that were never accessed by any queries in the log, to avoid false-positive results. -If you don't specify "--quiet", the tool also outputs warnings about +If you don't specify :option:`--quiet`, the tool also outputs warnings about statements that cannot be EXPLAINed and similar. These go to standard error. -Progress reports are enabled by default (see "--progress"). These also go to +Progress reports are enabled by default (see :option:`--progress`). These also go to standard error. -******* OPTIONS -******* - +======= This tool accepts additional command-line arguments. Refer to the "SYNOPSIS" and usage information for details. ---ask-pass +.. option:: --ask-pass - Prompt for a password when connecting to MySQL. + Prompt for a password when connecting to |MySQL|. - ---charset +.. option:: --charset short form: -A; type: string - Default character set. If the value is utf8, sets Perl's binmode on - STDOUT to utf8, passes the mysql_enable_utf8 option to DBD::mysql, and - runs SET NAMES UTF8 after connecting to MySQL. Any other value sets - binmode on STDOUT without the utf8 layer, and runs SET NAMES after - connecting to MySQL. + Default character set. If the value is utf8, sets *Perl* 's binmode on + ``STDOUT`` to utf8, passes the mysql_enable_utf8 option to ``DBD::mysql``, and + runs SET NAMES UTF8 after connecting to |MySQL|. Any other value sets + binmode on ``STDOUT`` without the utf8 layer, and runs SET NAMES after + connecting to |MySQL|. - ---config +.. option:: --config type: Array @@ -173,68 +168,60 @@ This tool accepts additional command-line arguments. Refer to the first option on the command line. - ---create-save-results-database +.. option:: --create-save-results-database - Create the "--save-results-database" if it does not exist. + Create the :option:`--save-results-database` if it does not exist. - If the "--save-results-database" already exists and this option is + If the :option:`--save-results-database` already exists and this option is specified, the database is used and the necessary tables are created if they do not already exist. - ---[no]create-views +.. option:: --[no]create-views - Create views for "--save-results-database" example queries. + Create views for :option:`--save-results-database` example queries. Several example queries are given for querying the tables in the - "--save-results-database". These example queries are, by default, created + :option:`--save-results-database`. These example queries are, by default, created as views. Specifying \ ``--no-create-views``\ prevents these views from being created. - ---database +.. option:: --database short form: -D; type: string The database to use for the connection. - ---databases +.. option:: --databases short form: -d; type: hash Only get tables and indexes from this comma-separated list of databases. - ---databases-regex +.. option:: --databases-regex type: string - Only get tables and indexes from database whose names match this Perl regex. + Only get tables and indexes from database whose names match this *Perl* regex. - ---defaults-file +.. option:: --defaults-file short form: -F; type: string Only read mysql options from the given file. You must give an absolute pathname. - ---drop +.. option:: --drop type: Hash; default: non-unique Suggest dropping only these types of unused indexes. - By default pt-index-usage will only suggest to drop unused secondary indexes, - not primary or unique indexes. You can specify which types of unused indexes + By default :program:`pt-index-usage` will only suggest to drop unused secondary indexes, not primary or unique indexes. You can specify which types of unused indexes the tool suggests to drop: primary, unique, non-unique, all. A separate \ ``ALTER TABLE``\ statement for each type is printed. So if you @@ -242,45 +229,39 @@ This tool accepts additional command-line arguments. Refer to the the \ ``ALTER TABLE ... DROP``\ for each will be printed on separate lines. - ---empty-save-results-tables +.. option:: --empty-save-results-tables - Drop and re-create all pre-existing tables in the "--save-results-database". + Drop and re-create all pre-existing tables in the :option:`--save-results-database`. This allows information from previous runs to be removed before the current run. - ---help +.. option:: --help Show help and exit. - ---host +.. option:: --host short form: -h; type: string Connect to host. - ---ignore-databases +.. option:: --ignore-databases type: Hash Ignore this comma-separated list of databases. - ---ignore-databases-regex +.. option:: --ignore-databases-regex type: string - Ignore databases whose names match this Perl regex. + Ignore databases whose names match this *Perl* regex. - ---ignore-tables +.. option:: --ignore-tables type: Hash @@ -289,16 +270,15 @@ This tool accepts additional command-line arguments. Refer to the Table names may be qualified with the database name. - ---ignore-tables-regex +.. option:: --ignore-tables-regex type: string - Ignore tables whose names match the Perl regex. + Ignore tables whose names match the *Perl* regex. ---password +.. option:: --password short form: -p; type: string @@ -306,7 +286,7 @@ This tool accepts additional command-line arguments. Refer to the ---port +.. option:: --port short form: -P; type: int @@ -314,61 +294,56 @@ This tool accepts additional command-line arguments. Refer to the ---progress +.. option:: --progress type: array; default: time,30 - Print progress reports to STDERR. The value is a comma-separated list with two + Print progress reports to ``STDERR``. The value is a comma-separated list with two parts. The first part can be percentage, time, or iterations; the second part specifies how often an update should be printed, in percentage, seconds, or number of iterations. - ---quiet +.. option:: --quiet short form: -q - Do not print any warnings. Also disables "--progress". + Do not print any warnings. Also disables :option:`--progress`. - ---[no]report +.. option:: --[no]report default: yes - Print the reports for "--report-format". + Print the reports for :option:`--report-format`. You may want to disable the reports by specifying \ ``--no-report``\ if, for - example, you also specify "--save-results-database" and you only want + example, you also specify :option:`--save-results-database` and you only want to query the results tables later. - ---report-format +.. option:: --report-format type: Array; default: drop_unused_indexes Right now there is only one report: drop_unused_indexes. This report prints - SQL statements for dropping any unused indexes. See also "--drop". + SQL statements for dropping any unused indexes. See also :option:`--drop`. - See also "--[no]report". + See also :option:`--[no]report`. - ---save-results-database +.. option:: --save-results-database type: DSN Save results to tables in this database. Information about indexes, queries, tables and their usage is stored in several tables in the specified database. The tables are auto-created if they do not exist. If the database doesn't - exist, it can be auto-created with "--create-save-results-database". In this + exist, it can be auto-created with :option:`--create-save-results-database`. In this case the connection is initially created with no default database, then after the database is created, it is USE'ed. - pt-index-usage executes INSERT statements to save the results. Therefore, you - should be careful if you use this feature on a production server. It might + :program:`pt-index-usage` executes INSERT statements to save the results. Therefore, you should be careful if you use this feature on a production server. It might increase load, or cause trouble if you don't want the server to be written to, or so on. @@ -451,14 +426,13 @@ This tool accepts additional command-line arguments. Refer to the The following are some queries you can run against these tables to answer common - questions you might have. Each query is also created as a view (with MySQL - v5.0 and newer) if \ ``"--[no]create-views"``\ is true (it is by default). + questions you might have. Each query is also created as a view (with |MySQL| + v5.0 and newer) if :option:`--[no]create-views` is true (it is by default). The view names are the strings after the \ ``MAGIC_view_``\ prefix. Question: which queries sometimes use different indexes, and what fraction of the time is each index chosen? MAGIC_view_query_uses_several_indexes: - .. code-block:: perl SELECT iu.query_id, CONCAT_WS('.', iu.db, iu.tbl, iu.idx) AS idx, @@ -476,7 +450,6 @@ This tool accepts additional command-line arguments. Refer to the Question: which indexes have lots of alternatives, i.e. are chosen instead of other indexes, and for what queries? MAGIC_view_index_has_alternates: - .. code-block:: perl SELECT CONCAT_WS('.', db, tbl, idx) AS idx_chosen, @@ -490,7 +463,6 @@ This tool accepts additional command-line arguments. Refer to the Question: which indexes are considered as alternates for other indexes, and for what queries? MAGIC_view_index_alternates: - .. code-block:: perl SELECT CONCAT_WS('.', db, tbl, alt_idx) AS idx_considered, @@ -504,7 +476,6 @@ This tool accepts additional command-line arguments. Refer to the Question: which of those are never chosen by any queries, and are therefore superfluous? MAGIC_view_unused_index_alternates: - .. code-block:: perl SELECT CONCAT_WS('.', i.db, i.tbl, i.idx) AS idx, @@ -520,13 +491,11 @@ This tool accepts additional command-line arguments. Refer to the AND i.idx = alt.alt_idx WHERE i.cnt = 0; - Question: given a table, which indexes were used, by how many queries, with how many distinct fingerprints? Were there alternatives? Which indexes were not used? You can edit the following query's SELECT list to also see the query IDs in question. MAGIC_view_index_usage: - .. code-block:: perl SELECT i.idx, iu.usage_cnt, iu.usage_total, @@ -566,62 +535,51 @@ This tool accepts additional command-line arguments. Refer to the ) AS no_alt ON no_alt.db = i.db AND no_alt.tbl = i.tbl AND no_alt.idx = i.idx ORDER BY i.db, i.tbl, i.idx, no_alt.queries; - - ---set-vars +.. option:: --set-vars type: string; default: wait_timeout=10000 - Set these MySQL variables. Immediately after connecting to MySQL, this + Set these |MySQL| variables. Immediately after connecting to |MySQL|, this string will be appended to SET and executed. - ---socket +.. option:: --socket short form: -S; type: string Socket file to use for connection. - ---tables +.. option:: --tables short form: -t; type: hash Only get indexes from this comma-separated list of tables. - ---tables-regex +.. option:: --tables-regex type: string - Only get indexes from tables whose names match this Perl regex. + Only get indexes from tables whose names match this *Perl* regex. - ---user +.. option:: --user short form: -u; type: string User for login if not current user. - ---version +.. option:: --version Show version and exit. - - -*********** DSN OPTIONS -*********** - +=========== These DSN options are used to create a DSN. Each option is given like \ ``option=value``\ . The options are case-sensitive, so P and p are not the @@ -630,23 +588,21 @@ if the value contains whitespace it must be quoted. DSN options are comma-separated. See the percona-toolkit manpage for full details. -\* A + * ``A`` dsn: charset; copy: yes Default character set. - -\* D + * ``D`` dsn: database; copy: yes Database to connect to. - -\* F + * ``F`` dsn: mysql_read_default_file; copy: yes @@ -654,53 +610,46 @@ comma-separated. See the percona-toolkit manpage for full details. -\* h + * ``h`` dsn: host; copy: yes Connect to host. - -\* p + * ``p`` dsn: password; copy: yes Password to use when connecting. - -\* P + * ``p`` dsn: port; copy: yes Port number to use for connection. - -\* S + * ``S`` dsn: mysql_socket; copy: yes Socket file to use for connection. - -\* u + * ``u`` dsn: user; copy: yes User for login if not current user. - - -*********** ENVIRONMENT -*********** +=========== -The environment variable \ ``PTDEBUG``\ enables verbose debugging output to STDERR. +The environment variable \ ``PTDEBUG``\ enables verbose debugging output to ``STDERR``. To enable debugging and capture all output to a file, run the tool like: @@ -713,128 +662,35 @@ Be careful: debugging output is voluminous and can generate several megabytes of output. -******************* SYSTEM REQUIREMENTS -******************* +=================== -You need Perl, DBI, DBD::mysql, and some core packages that ought to be -installed in any reasonably new version of Perl. +You need *Perl* , ``DBI``, ``DBD::mysql``, and some core packages that ought to be +installed in any reasonably new version of *Perl* . -**** BUGS -**** +==== For a list of known bugs, see `http://www.percona.com/bugs/pt-index-usage `_. 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* and *Daniel Nichter* -Baron Schwartz and Daniel Nichter - - -********************* -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-2011 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 -******* +======= - -pt-index-usage 1.0.1 + :program:`pt-index-usage` 1.0.1 diff --git a/docs/user/pt-kill.rst b/docs/user/source/pt-kill.rst similarity index 58% rename from docs/user/pt-kill.rst rename to docs/user/source/pt-kill.rst index 463f9837..64f0570a 100644 --- a/docs/user/pt-kill.rst +++ b/docs/user/source/pt-kill.rst @@ -1,30 +1,30 @@ +.. program:: pt-kill -####### -pt-kill -####### +==================== + :program:`pt-kill` +==================== .. highlight:: perl -**** NAME -**** +==== + + :program:`pt-kill` - Kill |MySQL| queries that match certain criteria. -pt-kill - Kill MySQL queries that match certain criteria. - - -******** SYNOPSIS -******** +======== -Usage: pt-kill [OPTION]... [FILE...] +Usage +----- -pt-kill kills MySQL connections. pt-kill connects to MySQL and gets queries -from SHOW PROCESSLIST if no FILE is given. Else, it reads queries from one -or more FILE which contains the output of SHOW PROCESSLIST. If FILE is -, -pt-kill reads from STDIN. +:: + + pt-kill [OPTION]... [FILE...] + +:program:`pt-kill` kills |MySQL| connections. :program:`pt-kill` connects to |MySQL| and gets queries from SHOW PROCESSLIST if no FILE is given. Else, it reads queries from one or more FILE which contains the output of SHOW PROCESSLIST. If FILE is -, :program:`pt-kill` reads from ``STDIN``. Kill queries running longer than 60s: @@ -67,9 +67,8 @@ See which queries in the processlist right now would match: -***** RISKS -***** +===== The following section is included to inform users about the potential risks, @@ -77,9 +76,8 @@ 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-kill is designed to kill queries if you use the "--kill" option is given, -and that might disrupt your database's users, of course. You should test with -the <"--print"> option, which is safe, if you're unsure what the tool will do. +:program:`pt-kill` is designed to kill queries if you use the :option:`--kill` option is given, and that might disrupt your database's users, of course. You should test with +the :option:`--print` option, which is safe, if you're unsure what the tool will do. At the time of this release, we know of no bugs that could cause serious harm to users. @@ -89,58 +87,49 @@ 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-kill `_. -See also "BUGS" for more information on filing bugs and getting help. +See also :ref:`bugs` for more information on filing bugs and getting help. -*********** DESCRIPTION -*********** +=========== - -pt-kill captures queries from SHOW PROCESSLIST, filters them, and then either -kills or prints them. This is also known as a "slow query sniper" in some +:program:`pt-kill` captures queries from SHOW PROCESSLIST, filters them, and then either kills or prints them. This is also known as a "slow query sniper" in some circles. The idea is to watch for queries that might be consuming too many resources, and kill them. -For brevity, we talk about killing queries, but they may just be printed -(or some other future action) depending on what options are given. +For brevity, we talk about killing queries, but they may just be printed (or some other future action) depending on what options are given. -Normally pt-kill connects to MySQL to get queries from SHOW PROCESSLIST. -Alternatively, it can read SHOW PROCESSLIST output from files. In this case, -pt-kill does not connect to MySQL and "--kill" has no effect. You should -use "--print" instead when reading files. The ability to read a file (or -- for STDIN) allows you to capture SHOW PROCESSLIST and test it later with -pt-kill to make sure that your matches kill the proper queries. There are a -lot of special rules to follow, such as "don't kill replication threads," -so be careful to not kill something important! +Normally :program:`pt-kill` connects to |MySQL| to get queries from SHOW PROCESSLIST. +Alternatively, it can read SHOW PROCESSLIST output from files. In this case, :program:`pt-kill` does not connect to |MySQL| and :option:`--kill` has no effect. You should use :option:`--print` instead when reading files. The ability to read a file (or +- for ``STDIN``) allows you to capture ``SHOW PROCESSLIST`` and test it later with :program:`pt-kill` to make sure that your matches kill the proper queries. There are a +lot of special rules to follow, such as "don't kill replication threads," so be careful to not kill something important! -Two important options to know are "--busy-time" and "--victims". +Two important options to know are :option:`--busy-time" and "--victims`. First, whereas most match/filter options match their corresponding value from -SHOW PROCESSLIST (e.g. "--match-command" matches a query's Command value), -the Time value is matched by "--busy-time". See also "--interval". +SHOW PROCESSLIST (e.g. :option:`--match-command` matches a query's Command value), +the Time value is matched by :option:`--busy-time". See also "--interval`. -Second, "--victims" controls which matching queries from each class are +Second, :option:`--victims` controls which matching queries from each class are killed. By default, the matching query with the highest Time value is killed (the oldest query). See the next section, "GROUP, MATCH AND KILL", for more details. Usually you need to specify at least one \ ``--match``\ option, else no -queries will match. Or, you can specify "--match-all" to match all queries +queries will match. Or, you can specify :option:`--match-all` to match all queries that aren't ignored by an \ ``--ignore``\ option. -pt-kill is a work in progress, and there is much more it could do. +:program:`pt-kill` is a work in progress, and there is much more it could do. -********************* GROUP, MATCH AND KILL -********************* +===================== Queries pass through several steps to determine which exactly will be killed (or printed--whatever action is specified). Understanding these steps will help you match precisely the queries you want. -The first step is grouping queries into classes. The "--group-by" option +The first step is grouping queries into classes. The :option:`--group-by` option controls grouping. By default, this option has no value so all queries are grouped into one, big default class. All types of matching and filtering (the next step) are applied per-class. Therefore, you may need to group @@ -149,29 +138,27 @@ queries in order to match/filter some classes but not others. The second step is matching. Matching implies filtering since if a query doesn't match some criteria, it is removed from its class. Matching happens for each class. First, queries are filtered from their -class by the various \ ``Query Matches``\ options like "--match-user". -Then, entire classes are filtered by the various \ ``Class Matches``\ options -like "--query-count". +class by the various ``Query Matches`` options like :option:`--match-user`. +Then, entire classes are filtered by the various ``Class Matches`` options +like :option:`--query-count`. The third step is victim selection, that is, which matching queries in each -class to kill. This is controlled by the "--victims" option. Although +class to kill. This is controlled by the :option:`--victims` option. Although many queries in a class may match, you may only want to kill the oldest query, or all queries, etc. The forth and final step is to take some action on all matching queries -from all classes. The \ ``Actions``\ options specify which actions will be +from all classes. The ``Actions`` options specify which actions will be taken. At this step, there are no more classes, just a single list of queries to kill, print, etc. -****** OUTPUT -****** +====== -If only "--kill" then there is no output. If only "--print" then a -timestamped KILL statement if printed for every query that would have -been killed, like: +If only :option:`--kill` then there is no output. If only :option:`--print` then a +timestamped KILL statement if printed for every query that would have been killed, like: .. code-block:: perl @@ -182,47 +169,42 @@ been killed, like: The line shows a timestamp, the query's Id (8), its Time (42 sec) and its Info (usually the query SQL). -If both "--kill" and "--print" are given, then matching queries are +If both :option:`--kill` and :option:`--print` are given, then matching queries are killed and a line for each like the one above is printed. -Any command executed by "--execute-command" is responsible for its own -output and logging. After being executed, pt-kill has no control or interaction -with the command. +Any command executed by :option:`--execute-command` is responsible for its own +output and logging. After being executed, :program:`pt-kill` has no control or interaction with the command. -******* OPTIONS -******* +======= +Specify at least one of :option:`--kill`, :option:`--kill-query`, :option:`--print`, :option:`--execute-command` or :option:`--stop`. -Specify at least one of "--kill", "--kill-query", "--print", "--execute-command" or "--stop". +:option:`--any-busy-time` and :option:`--each-busy-time` are mutually exclusive. -"--any-busy-time" and "--each-busy-time" are mutually exclusive. - -"--kill" and "--kill-query" are mutually exclusive. +:option:`--kill` and :option:`--kill-query` are mutually exclusive. This tool accepts additional command-line arguments. Refer to the "SYNOPSIS" and usage information for details. ---ask-pass +.. option:: --ask-pass - Prompt for a password when connecting to MySQL. + Prompt for a password when connecting to |MySQL|. - ---charset +.. option:: --charset short form: -A; type: string - Default character set. If the value is utf8, sets Perl's binmode on - STDOUT to utf8, passes the mysql_enable_utf8 option to DBD::mysql, and runs SET - NAMES UTF8 after connecting to MySQL. Any other value sets binmode on STDOUT - without the utf8 layer, and runs SET NAMES after connecting to MySQL. + Default character set. If the value is utf8, sets *Perl* 's binmode on + ``STDOUT`` to utf8, passes the mysql_enable_utf8 option to ``DBD::mysql``, and runs SET + NAMES UTF8 after connecting to |MySQL|. Any other value sets binmode on ``STDOUT`` + without the utf8 layer, and runs SET NAMES after connecting to |MySQL|. - ---config +.. option:: --config type: Array @@ -230,24 +212,20 @@ This tool accepts additional command-line arguments. Refer to the first option on the command line. - ---daemonize +.. option:: --daemonize Fork to the background and detach from the shell. POSIX operating systems only. - ---defaults-file +.. option:: --defaults-file short form: -F; type: string Only read mysql options from the given file. You must give an absolute pathname. - - ---group-by +.. option:: --group-by type: string @@ -261,61 +239,55 @@ This tool accepts additional command-line arguments. Refer to the similar queries, if any queries in the class match. For example, detecting cache stampedes (see \ ``all-but-oldest``\ under - "--victims" for an explanation of that term) requires that queries are + :option:`--victims` for an explanation of that term) requires that queries are grouped by the \ ``arg``\ attribute. This creates classes of identical queries (stripped of comments). So queries \ ``"SELECT c FROM t WHERE id=1"``\ and \ ``"SELECT c FROM t WHERE id=1"``\ are grouped into the same class, but query c<"SELECT c FROM t WHERE id=3"> is not identical to the first two - queries so it is grouped into another class. Then when "--victims" + queries so it is grouped into another class. Then when :option:`--victims` \ ``all-but-oldest``\ is specified, all but the oldest query in each class is killed for each class of queries that matches the match criteria. - ---help +.. option:: --help Show help and exit. - ---host +.. option:: --host short form: -h; type: string; default: localhost Connect to host. - ---interval +.. option:: --interval type: time - How often to check for queries to kill. If "--busy-time" is not given, + How often to check for queries to kill. If :option:`--busy-time` is not given, then the default interval is 30 seconds. Else the default is half as often - as "--busy-time". If both "--interval" and "--busy-time" are given, - then the explicit "--interval" value is used. + as :option:`--busy-time". If both "--interval" and "--busy-time` are given, + then the explicit :option:`--interval` value is used. - See also "--run-time". + See also :option:`--run-time`. - ---log +.. option:: --log type: string Print all output to this file when daemonized. - ---password +.. option:: --password short form: -p; type: string Password to use when connecting. - ---pid +.. option:: --pid type: string @@ -325,88 +297,78 @@ This tool accepts additional command-line arguments. Refer to the it exists and the process with the matching PID exists, the program exits. - ---port +.. option:: --port short form: -P; type: int Port number to use for connection. - ---run-time +.. option:: --run-time type: time - How long to run before exiting. By default pt-kill runs forever, or until - its process is killed or stopped by the creation of a "--sentinel" file. - If this option is specified, pt-kill runs for the specified amount of time - and sleeps "--interval" seconds between each check of the PROCESSLIST. + How long to run before exiting. By default :program:`pt-kill` runs forever, or until + its process is killed or stopped by the creation of a :option:`--sentinel` file. + If this option is specified, :program:`pt-kill` runs for the specified amount of time + and sleeps :option:`--interval` seconds between each check of the PROCESSLIST. - ---sentinel +.. option:: --sentinel type: string; default: /tmp/pt-kill-sentinel Exit if this file exists. - The presence of the file specified by "--sentinel" will cause all - running instances of pt-kill to exit. You might find this handy to stop cron - jobs gracefully if necessary. See also "--stop". + The presence of the file specified by :option:`--sentinel` will cause all + running instances of :program:`pt-kill` to exit. You might find this handy to stop cron + jobs gracefully if necessary. See also :option:`--stop`. - ---set-vars +.. option:: --set-vars type: string; default: wait_timeout=10000 - Set these MySQL variables. Immediately after connecting to MySQL, this string + Set these |MySQL| variables. Immediately after connecting to |MySQL|, this string will be appended to SET and executed. - ---socket +.. option:: --socket short form: -S; type: string Socket file to use for connection. - ---stop +.. option:: --stop - Stop running instances by creating the "--sentinel" file. + Stop running instances by creating the :option:`--sentinel` file. - Causes pt-kill to create the sentinel file specified by "--sentinel" and + Causes :program:`pt-kill` to create the sentinel file specified by :option:`--sentinel` and exit. This should have the effect of stopping all running instances which are watching the same sentinel file. - ---[no]strip-comments +.. option:: --[no]strip-comments default: yes Remove SQL comments from queries in the Info column of the PROCESSLIST. - ---user +.. option:: --user short form: -u; type: string User for login if not current user. - ---version +.. option:: --version Show version and exit. - ---victims +.. option:: --victims type: string; default: oldest @@ -415,7 +377,6 @@ This tool accepts additional command-line arguments. Refer to the queries in each class will be killed (or printed, etc.). The following values are possible: - oldest Only kill the single oldest query. This is to prevent killing queries that @@ -423,13 +384,11 @@ This tool accepts additional command-line arguments. Refer to the queries by Time and kills the one with the highest Time value. - all Kill all queries in the class. - all-but-oldest Kill all but the oldest query. This is the inverse of the \ ``oldest``\ value. @@ -440,10 +399,8 @@ This tool accepts additional command-line arguments. Refer to the query are killed so that it can complete and populate the cache. - - ---wait-after-kill +.. option:: --wait-after-kill type: time @@ -453,19 +410,18 @@ This tool accepts additional command-line arguments. Refer to the afterwards. - ---wait-before-kill +.. option:: --wait-before-kill type: time Wait before killing a query. The purpose of this is to give - "--execute-command" a chance to see the matching query and gather other - MySQL or system information before it's killed. + :option:`--execute-command` a chance to see the matching query and gather other + |MySQL| or system information before it's killed. QUERY MATCHES -============= +------------- These options filter queries from their classes. If a query does not @@ -478,7 +434,7 @@ a regex pattern like \ ``(?i-xsm:select)``\ . See also "GROUP, MATCH AND KILL". ---busy-time +.. option:: --busy-time type: time; group: Query Matches @@ -488,7 +444,7 @@ See also "GROUP, MATCH AND KILL". ---idle-time +.. option:: --idle-time type: time; group: Query Matches @@ -498,99 +454,97 @@ See also "GROUP, MATCH AND KILL". ---ignore-command +.. option:: --ignore-command type: string; group: Query Matches - Ignore queries whose Command matches this Perl regex. + Ignore queries whose Command matches this *Perl* regex. - See "--match-command". + See :option:`--match-command`. ---ignore-db +.. option:: --ignore-db type: string; group: Query Matches - Ignore queries whose db (database) matches this Perl regex. + Ignore queries whose db (database) matches this *Perl* regex. - See "--match-db". + See :option:`--match-db`. ---ignore-host +.. option:: --ignore-host type: string; group: Query Matches - Ignore queries whose Host matches this Perl regex. + Ignore queries whose Host matches this *Perl* regex. - See "--match-host". + See :option:`--match-host`. ---ignore-info +.. option:: --ignore-info type: string; group: Query Matches - Ignore queries whose Info (query) matches this Perl regex. + Ignore queries whose Info (query) matches this *Perl* regex. - See "--match-info". + See :option:`--match-info`. ---[no]ignore-self +.. option:: --[no]ignore-self default: yes; group: Query Matches - Don't kill pt-kill's own connection. + Don't kill :program:`pt-kill`'s own connection. ---ignore-state +.. option:: --ignore-state type: string; group: Query Matches; default: Locked - Ignore queries whose State matches this Perl regex. The default is to keep + Ignore queries whose State matches this *Perl* regex. The default is to keep threads from being killed if they are locked waiting for another thread. - See "--match-state". + See :option:`--match-state`. ---ignore-user +.. option:: --ignore-user type: string; group: Query Matches - Ignore queries whose user matches this Perl regex. + Ignore queries whose user matches this *Perl* regex. - See "--match-user". + See :option:`--match-user`. ---match-all +.. option:: --match-all group: Query Matches Match all queries that are not ignored. If no ignore options are specified, then every query matches (except replication threads, unless - "--replication-threads" is also specified). This option allows you to + :option:`--replication-threads` is also specified). This option allows you to specify negative matches, i.e. "match every query \ *except*\ ..." where the exceptions are defined by specifying various \ ``--ignore``\ options. - This option is \ *not*\ the same as "--victims" \ ``all``\ . This option matches - all queries within a class, whereas "--victims" \ ``all``\ specifies that all + This option is \ *not*\ the same as :option:`--victims` \ ``all``\ . This option matches + all queries within a class, whereas :option:`--victims` \ ``all``\ specifies that all matching queries in a class (however they matched) will be killed. Normally, however, the two are used together because if, for example, you specify - "--victims" \ ``oldest``\ , then although all queries may match, only the oldest - will be killed. + :option:`--victims` \ ``oldest``\ , then although all queries may match, only the oldest will be killed. - ---match-command +.. option:: --match-command type: string; group: Query Matches - Match only queries whose Command matches this Perl regex. + Match only queries whose Command matches this *Perl* regex. Common Command values are: @@ -617,41 +571,37 @@ See also "GROUP, MATCH AND KILL". list and description of Command values. - ---match-db +.. option:: --match-db type: string; group: Query Matches - Match only queries whose db (database) matches this Perl regex. + Match only queries whose db (database) matches this *Perl* regex. - ---match-host +.. option:: --match-host type: string; group: Query Matches - Match only queries whose Host matches this Perl regex. + Match only queries whose Host matches this *Perl* regex. The Host value often time includes the port like "host:port". - ---match-info +.. option:: --match-info type: string; group: Query Matches - Match only queries whose Info (query) matches this Perl regex. + Match only queries whose Info (query) matches this *Perl* regex. The Info column of the processlist shows the query that is being executed or NULL if no query is being executed. - ---match-state +.. option:: --match-state type: string; group: Query Matches - Match only queries whose State matches this Perl regex. + Match only queries whose State matches this *Perl* regex. Common State values are: @@ -675,18 +625,17 @@ See also "GROUP, MATCH AND KILL". See `http://dev.mysql.com/doc/refman/5.1/en/general-thread-states.html `_ for a full list and description of State values. - ---match-user +.. option:: --match-user type: string; group: Query Matches - Match only queries whose User matches this Perl regex. + Match only queries whose User matches this *Perl* regex. ---replication-threads +.. option:: --replication-threads group: Query Matches @@ -698,19 +647,18 @@ See also "GROUP, MATCH AND KILL". - CLASS MATCHES -============= +------------- These matches apply to entire query classes. Classes are created by specifying -the "--group-by" option, else all queries are members of a single, default +the :option:`--group-by` option, else all queries are members of a single, default class. See also "GROUP, MATCH AND KILL". ---any-busy-time +.. option:: --any-busy-time type: time; group: Class Matches @@ -719,11 +667,10 @@ See also "GROUP, MATCH AND KILL". only match if there's at least one query that has been running for greater than 10 seconds. - See "--each-busy-time" for more details. + See :option:`--each-busy-time` for more details. - ---each-busy-time +.. option:: --each-busy-time type: time; group: Class Matches @@ -732,108 +679,91 @@ See also "GROUP, MATCH AND KILL". only match if each and every query has been running for greater than 10 seconds. - See also "--any-busy-time" (to match a class if ANY query has been running - longer than the specified time) and "--busy-time". + See also :option:`--any-busy-time` (to match a class if ANY query has been running + longer than the specified time) and :option:`--busy-time`. - ---query-count +.. option:: --query-count type: int; group: Class Matches Match query class if it has at least this many queries. When queries are - grouped into classes by specifying "--group-by", this option causes matches - to apply only to classes with at least this many queries. If "--group-by" + grouped into classes by specifying :option:`--group-by`, this option causes matches + to apply only to classes with at least this many queries. If :option:`--group-by` is not specified then this option causes matches to apply only if there are at least this many queries in the entire SHOW PROCESSLIST. - ---verbose +.. option:: --verbose short form: -v - Print information to STDOUT about what is being done. - - + Print information to ``STDOUT`` about what is being done. ACTIONS -======= - +------- These actions are taken for every matching query from all classes. -The actions are taken in this order: "--print", "--execute-command", -"--kill"/"--kill-query". This order allows "--execute-command" -to see the output of "--print" and the query before -"--kill"/"--kill-query". This may be helpful because pt-kill does -not pass any information to "--execute-command". +The actions are taken in this order: :option:`--print`, :option:`--execute-command`, +:option:`--kill` / :option:`--kill-query`. This order allows :option:`--execute-command` to see the output of :option:`--print` and the query before +:option:`--kill` / :option:`--kill-query`. This may be helpful because :program:`pt-kill` does not pass any information to :option:`--execute-command`. See also "GROUP, MATCH AND KILL". - ---execute-command +.. option:: --execute-command type: string; group: Actions Execute this command when a query matches. - After the command is executed, pt-kill has no control over it, so the command + After the command is executed, :program:`pt-kill` has no control over it, so the command is responsible for its own info gathering, logging, interval, etc. The command is executed each time a query matches, so be careful that the command - behaves well when multiple instances are ran. No information from pt-kill is + behaves well when multiple instances are ran. No information from :program:`pt-kill` is passed to the command. - See also "--wait-before-kill". + See also :option:`--wait-before-kill`. - ---kill +.. option:: --kill group: Actions Kill the connection for matching queries. - This option makes pt-kill kill the connections (a.k.a. processes, threads) that - have matching queries. Use "--kill-query" if you only want to kill + This option makes :program:`pt-kill` kill the connections (a.k.a. processes, threads) that + have matching queries. Use :option:`--kill-query` if you only want to kill individual queries and not their connections. - Unless "--print" is also given, no other information is printed that shows - that pt-kill matched and killed a query. + Unless :option:`--print` is also given, no other information is printed that shows + that :program:`pt-kill` matched and killed a query. - See also "--wait-before-kill" and "--wait-after-kill". + See also :option:`--wait-before-kill` and :option:`--wait-after-kill`. - ---kill-query +.. option:: --kill-query group: Actions Kill matching queries. - This option makes pt-kill kill matching queries. This requires MySQL 5.0 or - newer. Unlike "--kill" which kills the connection for matching queries, + This option makes :program:`pt-kill` kill matching queries. This requires |MySQL| 5.0 or newer. Unlike :option:`--kill` which kills the connection for matching queries, this option only kills the query, not its connection. - - ---print +.. option:: --print group: Actions Print a KILL statement for matching queries; does not actually kill queries. If you just want to see which queries match and would be killed without - actually killing them, specify "--print". To both kill and print - matching queries, specify both "--kill" and "--print". + actually killing them, specify :option:`--print`. To both kill and print + matching queries, specify both :option:`--kill` and :option:`--print`. - - - -*********** DSN OPTIONS -*********** +=========== These DSN options are used to create a DSN. Each option is given like @@ -843,7 +773,7 @@ if the value contains whitespace it must be quoted. DSN options are comma-separated. See the percona-toolkit manpage for full details. -\* A + * ``A`` dsn: charset; copy: yes @@ -851,7 +781,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* D + * ``D`` dsn: database; copy: yes @@ -859,7 +789,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* F + * ``F`` dsn: mysql_read_default_file; copy: yes @@ -867,7 +797,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* h + * ``h`` dsn: host; copy: yes @@ -875,7 +805,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* p + * ``p`` dsn: password; copy: yes @@ -883,7 +813,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* P + * ``p`` dsn: port; copy: yes @@ -891,7 +821,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* S + * ``S`` dsn: mysql_socket; copy: yes @@ -899,21 +829,17 @@ comma-separated. See the percona-toolkit manpage for full details. -\* u + * ``u`` dsn: user; copy: yes User for login if not current user. - - -*********** ENVIRONMENT -*********** +=========== - -The environment variable \ ``PTDEBUG``\ enables verbose debugging output to STDERR. +The environment variable \ ``PTDEBUG``\ enables verbose debugging output to ``STDERR``. To enable debugging and capture all output to a file, run the tool like: @@ -926,128 +852,36 @@ Be careful: debugging output is voluminous and can generate several megabytes of output. -******************* SYSTEM REQUIREMENTS -******************* +=================== -You need Perl, DBI, DBD::mysql, and some core packages that ought to be -installed in any reasonably new version of Perl. +You need *Perl* , ``DBI``, ``DBD::mysql``, and some core packages that ought to be +installed in any reasonably new version of *Perl* . -**** BUGS -**** +==== For a list of known bugs, see `http://www.percona.com/bugs/pt-kill `_. 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* and *Daniel Nichter* -Baron Schwartz and Daniel Nichter - - -********************* -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 2009-2011 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 -******* +======= - -pt-kill 1.0.1 +:program:`pt-kill` 1.0.1 diff --git a/docs/user/pt-log-player.rst b/docs/user/source/pt-log-player.rst similarity index 61% rename from docs/user/pt-log-player.rst rename to docs/user/source/pt-log-player.rst index 60b4a666..4461cede 100644 --- a/docs/user/pt-log-player.rst +++ b/docs/user/source/pt-log-player.rst @@ -1,27 +1,30 @@ +.. program:: pt-log-player -############# -pt-log-player -############# +=============== + :program:`pt-log-player` +=============== .. highlight:: perl -**** NAME -**** +==== + + :program:`pt-log-player` - Replay |MySQL| query logs. -pt-log-player - Replay MySQL query logs. - - -******** SYNOPSIS -******** +======== -Usage: pt-log-player [OPTION...] [DSN] +Usage +----- -pt-log-player splits and plays slow log files. +:: + + pt-log-player [OPTION...] [DSN] + +:program:`pt-log-player` splits and plays slow log files. Split slow.log on Thread_id into 16 session files, save in ./sessions: @@ -48,9 +51,8 @@ Use pt-query-digest to summarize the results: -***** RISKS -***** +===== The following section is included to inform users about the potential risks, @@ -61,57 +63,52 @@ tools) and those created by bugs. This tool is meant to load a server as much as possible, for stress-testing purposes. It is not designed to be used on production servers. -At the time of this release there is a bug which causes pt-log-player to -exceed max open files during "--split". +At the time of this release there is a bug which causes :program:`pt-log-player` to +exceed max open files during :option:`--split`. 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-log-player `_. -See also "BUGS" for more information on filing bugs and getting help. +See also :ref:`bugs` for more information on filing bugs and getting help. -*********** DESCRIPTION -*********** +=========== - -pt-log-player does two things: it splits MySQL query logs into session files -and it plays (executes) queries in session files on a MySQL server. Only +:program:`pt-log-player` does two things: it splits |MySQL| query logs into session files and it plays (executes) queries in session files on a |MySQL| server. Only session files can be played; slow logs cannot be played directly without being split. A session is a group of queries from the slow log that all share a common attribute, usually Thread_id. The common attribute is specified with -"--split". Multiple sessions are saved into a single session file. -See "--session-files", "--max-sessions", "--base-file-name" and -"--base-dir". These session files are played with "--play". +:option:`--split`. Multiple sessions are saved into a single session file. +See :option:`--session-files`, :option:`--max-sessions`, :option:`--base-file-name` and +:option:`--base-dir`. These session files are played with :option:`--play`. -pt-log-player will "--play" session files in parallel using N number of -"--threads". (They're not technically threads, but we call them that +:program:`pt-log-player` will :option:`--play` session files in parallel using N number of :option:`--threads`. (They're not technically threads, but we call them that anyway.) Each thread will play all the sessions in its given session files. The sessions are played as fast as possible--there are no delays--because the goal is to stress-test and load-test the server. So be careful using this script on a production server! -Each "--play" thread writes its results to a separate file. These result +Each :option:`--play` thread writes its results to a separate file. These result files are in slow log format so they can be aggregated and summarized with -pt-query-digest. See "OUTPUT". +:program:`pt-query-digest`. See "OUTPUT". -****** OUTPUT -****** +====== -Both "--split" and "--play" have two outputs: status messages printed to -STDOUT to let you know what the script is doing, and session or result files -written to separate files saved in "--base-dir". You can suppress all -output to STDOUT for each with "--quiet", or increase output with -"--verbose". +Both :option:`--split` and :option:`--play` have two outputs: status messages printed to +``STDOUT`` to let you know what the script is doing, and session or result files +written to separate files saved in :option:`--base-dir`. You can suppress all +output to ``STDOUT`` for each with :option:`--quiet`, or increase output with +:option:`--verbose`. -The session files written by "--split" are simple text files containing +The session files written by :option:`--split` are simple text files containing queries grouped into sessions. For example: @@ -125,71 +122,68 @@ queries grouped into sessions. For example: The format of these session files is important: each query must be a single -line separated by a single blank line. And the "-- START SESSION" comment -tells pt-log-player where individual sessions begin and end so that "--play" -can correctly fake Thread_id in its result files. +line separated by a single blank line. And the ``-- START SESSION`` comment +tells :program:`pt-log-player` where individual sessions begin and end so that :option:`--play` can correctly fake Thread_id in its result files. -The result files written by "--play" are in slow log format with a minimal +The result files written by :option:`--play` are in slow log format with a minimal header: the only attributes printed are Thread_id, Query_time and Schema. -******* OPTIONS -******* +======= -Specify at least one of "--play", "--split" or "--split-random". +Specify at least one of :option:`--play`, :option:`--split` or :option:`--split-random`. -"--play" and "--split" are mutually exclusive. +:option:`--play` and :option:`--split` are mutually exclusive. This tool accepts additional command-line arguments. Refer to the "SYNOPSIS" and usage information for details. ---ask-pass +.. option:: --ask-pass group: Play - Prompt for a password when connecting to MySQL. + Prompt for a password when connecting to |MySQL|. ---base-dir +.. option:: --base-dir type: string; default: ./ - Base directory for "--split" session files and "--play" result file. + Base directory for :option:`--split` session files and :option:`--play` result file. - ---base-file-name +.. option:: --base-file-name type: string; default: session - Base file name for "--split" session files and "--play" result file. + Base file name for :option:`--split` session files and :option:`--play` result file. - Each "--split" session file will be saved as -N.txt, where + Each :option:`--split` session file will be saved as -N.txt, where N is a four digit, zero-padded session ID. For example: session-0003.txt. - Each "--play" result file will be saved as -results-PID.txt, + Each :option:`--play` result file will be saved as -results-PID.txt, where PID is the process ID of the executing thread. - All files are saved in "--base-dir". + All files are saved in :option:`--base-dir`. ---charset +.. option:: --charset short form: -A; type: string; group: Play - Default character set. If the value is utf8, sets Perl's binmode on STDOUT to - utf8, passes the mysql_enable_utf8 option to DBD::mysql, and runs SET NAMES UTF8 - after connecting to MySQL. Any other value sets binmode on STDOUT without the - utf8 layer, and runs SET NAMES after connecting to MySQL. + Default character set. If the value is utf8, sets *Perl* 's binmode on ``STDOUT`` to + utf8, passes the mysql_enable_utf8 option to ``DBD::mysql``, and runs SET NAMES UTF8 + after connecting to |MySQL|. Any other value sets binmode on ``STDOUT`` without the + utf8 layer, and runs SET NAMES after connecting to |MySQL|. ---config +.. option:: --config type: Array @@ -198,7 +192,7 @@ This tool accepts additional command-line arguments. Refer to the ---defaults-file +.. option:: --defaults-file short form: -F; type: string @@ -206,21 +200,21 @@ This tool accepts additional command-line arguments. Refer to the ---dry-run +.. option:: --dry-run Print which processes play which session files then exit. ---filter +.. option:: --filter type: string; group: Split - Discard "--split" events for which this Perl code doesn't return true. + Discard :option:`--split` events for which this *Perl* code doesn't return true. - This option only works with "--split". + This option only works with :option:`--split`. - This option allows you to inject Perl code into the tool to affect how the + This option allows you to inject *Perl* code into the tool to affect how the tool runs. Usually your code should examine \ ``$event``\ to decided whether or not to allow the event. \ ``$event``\ is a hashref of attributes and values of the event being filtered. Or, your code could add new attribute-value pairs @@ -230,7 +224,7 @@ This tool accepts additional command-line arguments. Refer to the There are two ways to supply your code: on the command line or in a file. If you supply your code on the command line, it is injected into the following - subroutine where \ ``$filter``\ is your code: + subroutine where ``$filter`` is your code: .. code-block:: perl @@ -259,7 +253,7 @@ This tool accepts additional command-line arguments. Refer to the The second way to supply your code is in a file. If your code is too complex to be expressed on the command line that results in valid syntax in the subroutine above, then you need to put the code in a file and give the file - name as the value to "--filter". The file should not contain a shebang + name as the value to :option:`--filter`. The file should not contain a shebang (\ ``#!/usr/bin/perl``\ ) line. The entire contents of the file is injected into the following subroutine: @@ -306,13 +300,13 @@ This tool accepts additional command-line arguments. Refer to the ---help +.. option:: --help Show help and exit. ---host +.. option:: --host short form: -h; type: string; group: Play @@ -320,7 +314,7 @@ This tool accepts additional command-line arguments. Refer to the ---iterations +.. option:: --iterations type: int; default: 1; group: Play @@ -328,13 +322,13 @@ This tool accepts additional command-line arguments. Refer to the ---max-sessions +.. option:: --max-sessions type: int; default: 5000000; group: Split - Maximum number of sessions to "--split". + Maximum number of sessions to :option:`--split`. - By default, \ ``pt-log-player``\ tries to split every session from the log file. + By default, \ ` :program:`pt-log-player```\ tries to split every session from the log file. For huge logs, however, this can result in millions of sessions. This option causes only the first N number of sessions to be saved. All sessions after this number are ignored, but sessions split before this number will @@ -343,7 +337,7 @@ This tool accepts additional command-line arguments. Refer to the ---only-select +.. option:: --only-select group: Play @@ -351,7 +345,7 @@ This tool accepts additional command-line arguments. Refer to the ---password +.. option:: --password short form: -p; type: string; group: Play @@ -359,7 +353,7 @@ This tool accepts additional command-line arguments. Refer to the ---pid +.. option:: --pid type: string @@ -374,19 +368,19 @@ This tool accepts additional command-line arguments. Refer to the ---play +.. option:: --play type: string; group: Play - Play (execute) session files created by "--split". + Play (execute) session files created by :option:`--split`. The argument to play must be a comma-separated list of session files - created by "--split" or a directory. If the argument is a directory, + created by :option:`--split` or a directory. If the argument is a directory, ALL files in that directory will be played. ---port +.. option:: --port short form: -P; type: int; group: Play @@ -394,43 +388,43 @@ This tool accepts additional command-line arguments. Refer to the ---print +.. option:: --print group: Play - Print queries instead of playing them; requires "--play". + Print queries instead of playing them; requires :option:`--play`. - You must also specify "--play" with "--print". Although the queries - will not be executed, "--play" is required to specify which session files to + You must also specify :option:`--play" with "--print`. Although the queries + will not be executed, :option:`--play` is required to specify which session files to read. ---quiet +.. option:: --quiet short form: -q - Do not print anything; disables "--verbose". + Do not print anything; disables :option:`--verbose`. ---[no]results +.. option:: --[no]results default: yes - Print "--play" results to files in "--base-dir". + Print :option:`--play` results to files in :option:`--base-dir`. ---session-files +.. option:: --session-files type: int; default: 8; group: Split - Number of session files to create with "--split". + Number of session files to create with :option:`--split`. The number of session files should either be equal to the number of - "--threads" you intend to "--play" or be an even multiple of - "--threads". This number is important for maximum performance because it: + :option:`--threads` you intend to :option:`--play` or be an even multiple of + :option:`--threads`. This number is important for maximum performance because it: .. code-block:: perl @@ -440,24 +434,24 @@ This tool accepts additional command-line arguments. Refer to the * avoids disk IO overhead by doing large sequential reads - You may want to increase this number beyond "--threads" if each session + You may want to increase this number beyond :option:`--threads` if each session file becomes too large. For example, splitting a 20G log into 8 sessions files may yield roughly eight 2G session files. - See also "--max-sessions". + See also :option:`--max-sessions`. ---set-vars +.. option:: --set-vars type: string; group: Play; default: wait_timeout=10000 - Set these MySQL variables. Immediately after connecting to MySQL, this string + Set these |MySQL| variables. Immediately after connecting to |MySQL|, this string will be appended to SET and executed. ---socket +.. option:: --socket short form: -S; type: string; group: Play @@ -465,7 +459,7 @@ This tool accepts additional command-line arguments. Refer to the ---split +.. option:: --split type: string; group: Split @@ -476,13 +470,13 @@ This tool accepts additional command-line arguments. Refer to the ---split-random +.. option:: --split-random group: Split Split log without an attribute, write queries round-robin to session files. - This option, if specified, overrides "--split" and causes the log to be + This option, if specified, overrides :option:`--split` and causes the log to be split query-by-query, writing each query to the next session file in round-robin style. If you don't care about "sessions" and just want to split a lot into N many session files and the relation or order of the queries does not matter, @@ -490,7 +484,7 @@ This tool accepts additional command-line arguments. Refer to the ---threads +.. option:: --threads type: int; default: 2; group: Play @@ -502,15 +496,15 @@ This tool accepts additional command-line arguments. Refer to the In any case, the default is at least 2, even when there's only a single processor. - See also "--session-files". + See also :option:`--session-files`. ---type +.. option:: --type type: string; group: Split - The type of log to "--split" (default slowlog). The permitted types are + The type of log to :option:`--split` (default slowlog). The permitted types are binlog @@ -534,13 +528,13 @@ This tool accepts additional command-line arguments. Refer to the slowlog - Split a log file in any variation of MySQL slow-log format. + Split a log file in any variation of |MySQL| slow-log format. ---user +.. option:: --user short form: -u; type: string; group: Play @@ -548,34 +542,33 @@ This tool accepts additional command-line arguments. Refer to the ---verbose +.. option:: --verbose short form: -v; cumulative: yes; default: 0 Increase verbosity; can be specified multiple times. - This option is disabled by "--quiet". + This option is disabled by :option:`--quiet`. ---version +.. option:: --version Show version and exit. ---[no]warnings +.. option:: --[no]warnings default: no; group: Play - Print warnings about SQL errors such as invalid queries to STDERR. + Print warnings about SQL errors such as invalid queries to ``STDERR``. -*********** DSN OPTIONS -*********** +=========== These DSN options are used to create a DSN. Each option is given like @@ -585,7 +578,7 @@ if the value contains whitespace it must be quoted. DSN options are comma-separated. See the percona-toolkit manpage for full details. -\* A + * ``A`` dsn: charset; copy: yes @@ -593,7 +586,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* D + * ``D`` dsn: database; copy: yes @@ -601,7 +594,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* F + * ``F`` dsn: mysql_read_default_file; copy: yes @@ -609,7 +602,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* h + * ``h`` dsn: host; copy: yes @@ -617,7 +610,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* p + * ``p`` dsn: password; copy: yes @@ -625,7 +618,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* P + * ``p`` dsn: port; copy: yes @@ -633,7 +626,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* S + * ``S`` dsn: mysql_socket; copy: yes @@ -641,7 +634,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* u + * ``u`` dsn: user; copy: yes @@ -650,12 +643,11 @@ comma-separated. See the percona-toolkit manpage for full details. -*********** ENVIRONMENT -*********** +=========== -The environment variable \ ``PTDEBUG``\ enables verbose debugging output to STDERR. +The environment variable \ ``PTDEBUG``\ enables verbose debugging output to ``STDERR``. To enable debugging and capture all output to a file, run the tool like: @@ -668,128 +660,38 @@ Be careful: debugging output is voluminous and can generate several megabytes of output. -******************* SYSTEM REQUIREMENTS -******************* +=================== -You need Perl, DBI, DBD::mysql, and some core packages that ought to be -installed in any reasonably new version of Perl. +You need *Perl* , ``DBI``, ``DBD::mysql``, and some core packages that ought to be +installed in any reasonably new version of *Perl* . -**** BUGS -**** +==== For a list of known bugs, see `http://www.percona.com/bugs/pt-log-player `_. 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 -******* +======= + +*Daniel Nichter* -Daniel Nichter - - -********************* -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 2008-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 -******* +======= - -pt-log-player 1.0.1 +:program:`pt-log-player` 1.0.1 diff --git a/docs/user/source/pt-mext.rst b/docs/user/source/pt-mext.rst new file mode 100644 index 00000000..9f481b45 --- /dev/null +++ b/docs/user/source/pt-mext.rst @@ -0,0 +1,130 @@ +.. program:: pt-mext + +==================== + :program:`pt-mext` +==================== + +.. highlight:: perl + + +NAME +==== + + :program:`pt-mext` - Look at many samples of |MySQL| \ ``SHOW GLOBAL STATUS``\ side-by-side. + + +SYNOPSIS +======== + + +Usage +----- + +:: + + pt-mext [OPTIONS] -- COMMAND + +:program:`pt-mext` columnizes repeated output from a program like mysqladmin extended. + +Get output from \ ``mysqladmin``\ : + + +.. code-block:: perl + + pt-mext -r -- mysqladmin ext -i10 -c3" + + +Get output from a file: + + +.. code-block:: perl + + 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. + +:program:`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 :ref:`bugs` for more information on filing bugs and getting help. + + +DESCRIPTION +=========== + +:program:`pt-mext` executes the \ ``COMMAND``\ you specify, and reads through the result one line at a time. It places each line into a temporary file. When it finds a +blank line, it assumes that a new sample of SHOW GLOBAL STATUS is starting, +and it creates a new temporary file. At the end of this process, it has a +number of temporary files. It joins the temporary files together side-by-side +and prints the result. If the "-r" option is given, it first subtracts +each sample from the one after it before printing results. + + +OPTIONS +======= + + + +-r + + Relative: subtract each column from the previous column. + + + + +ENVIRONMENT +=========== + + +This tool does not use any environment variables. + + +SYSTEM REQUIREMENTS +=================== + + +This tool requires the Bourne shell (\ */bin/sh*\ ) and the seq program. + + +BUGS +==== + + +For a list of known bugs, see `http://www.percona.com/bugs/pt-mext `_. + +Please report bugs at `https://bugs.launchpad.net/percona-toolkit `_. + + +AUTHORS +======= + + +*Baron Schwartz* + +COPYRIGHT, LICENSE, AND WARRANTY +================================ + +This program is copyright 2010 Baron Schwartz, 2011 Percona Inc. +Feedback and improvements are welcome. + + +VERSION +======= + +:program:`pt-mext` 1.0.1 + diff --git a/docs/user/source/pt-mysql-summary.rst b/docs/user/source/pt-mysql-summary.rst new file mode 100644 index 00000000..81d7f72c --- /dev/null +++ b/docs/user/source/pt-mysql-summary.rst @@ -0,0 +1,140 @@ +.. program:: pt-mysql-summary + +============================= + :program:`pt-mysql-summary` +============================= + +.. highlight:: perl + + +NAME +==== + + :program:`pt-mysql-summary` - Summarize |MySQL| information in a nice way. + + +SYNOPSIS +======== + + +Usage +----- + +:: + + pt-mysql-summary [MYSQL-OPTIONS] + +:program:`pt-mysql-summary` conveniently summarizes the status and configuration of a +|MySQL| database server so that you can learn about it at a glance. It is not +a tuning tool or diagnosis tool. It produces a report that is easy to diff +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. + + :program:`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 :ref:`bugs` for more information on filing bugs and getting help. + + +DESCRIPTION +=========== + +:program:`pt-mysql-summary` works by connecting to a |MySQL| database server and querying +it for status and configuration information. It saves these bits of data +into files in /tmp, and then formats them neatly with awk and other scripting +languages. + +To use, simply execute it. Optionally add the same command-line options +you would use to connect to |MySQL|, like \ ` pt-mysql-summary --user=foo``\ . + +The tool interacts minimally with the server upon which it runs. It assumes +that you'll run it on the same server you're inspecting, and therefore it +assumes that it will be able to find the my.cnf configuration file, for +example. However, it should degrade gracefully if this is not the case. +Note, however, that its output does not indicate which information comes from +the |MySQL| database and which comes from the host operating system, so it is +possible for confusing output to be generated if you run the tool on one +server and direct it to connect to a |MySQL| database server running on another +server. + + +Fuzzy-Rounding +============== + + +Many of the outputs from this tool are deliberately rounded to show their +magnitude but not the exact detail. This is called fuzzy-rounding. The idea +is that it doesn't matter whether a server is running 918 queries per second +or 921 queries per second; such a small variation is insignificant, and only +makes the output hard to compare to other servers. Fuzzy-rounding rounds in +larger increments as the input grows. It begins by rounding to the nearest 5, +then the nearest 10, nearest 25, and then repeats by a factor of 10 larger +(50, 100, 250), and so on, as the input grows. + + +OPTIONS +======= + + +This tool does not have any command-line options of its own. All options +are passed to \ ``mysql``\ . + + +ENVIRONMENT +=========== + + +This tool does not use any environment variables. + + +SYSTEM REQUIREMENTS +=================== + + +This tool requires Bash v3 or newer. + + +BUGS +==== + + +For a list of known bugs, see `http://www.percona.com/bugs/pt-mysql-summary `_. + +Please report bugs at `https://bugs.launchpad.net/percona-toolkit `_. + + +AUTHORS +======= + + +*Baron Schwartz* + + +COPYRIGHT +========= + +This program is copyright 2010-2011 Baron Schwartz, 2011 Percona Inc. +Feedback and improvements are welcome. + +VERSION +======= + +:program:`pt-mysql-summary` 1.0.1 + diff --git a/docs/user/pt-online-schema-change.rst b/docs/user/source/pt-online-schema-change.rst similarity index 70% rename from docs/user/pt-online-schema-change.rst rename to docs/user/source/pt-online-schema-change.rst index 8d5bc653..7cc788e3 100644 --- a/docs/user/pt-online-schema-change.rst +++ b/docs/user/source/pt-online-schema-change.rst @@ -1,42 +1,44 @@ +.. program:: pt-online-schema-change -####################### -pt-online-schema-change -####################### +==================================== + :program:`pt-online-schema-change` +==================================== .. highlight:: perl -**** NAME -**** +==== + + :program:`pt-online-schema-change` - Perform online, non-blocking table schema changes. -pt-online-schema-change - Perform online, non-blocking table schema changes. - - -******** SYNOPSIS -******** +======== -Usage: pt-online-schema-change [OPTION...] DSN +Usage +----- -pt-online-schema-change performs online, non-blocking schema changes to a table. -The table to change must be specified in the DSN \ ``t``\ part, like \ ``t=my_table``\ . +:: + + pt-online-schema-change [OPTION...] DSN + +:program:`pt-online-schema-change` performs online, non-blocking schema changes to a table. + +The table to change must be specified in the DSN \ ``t``\ part, like \ ``t=my_table``. The table can be database-qualified, or the database can be specified with the -"--database" option. - -Change the table's engine to InnoDB: +:option:`--database` option. +Change the table's engine to |InnoDB|: .. code-block:: perl pt-online-schema-change \ h=127.1,t=db.tbl \ - --alter "ENGINE=InnoDB" \ + --alter "ENGINE=|InnoDB|" \ --drop-tmp-table - Rebuild but do not alter the table, and keep the temporary table: @@ -58,9 +60,8 @@ Add column to parent table, update child table foreign key constraints: -***** RISKS -***** +===== The following section is included to inform users about the potential risks, @@ -68,7 +69,7 @@ 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-online-schema-change reads, writes, alters and drops tables. Although +:program:`pt-online-schema-change` reads, writes, alters and drops tables. Although it is tested, do not use it in production until you have thoroughly tested it in your environment! @@ -82,23 +83,22 @@ 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-online-schema-change `_. -See also "BUGS" for more information on filing bugs and getting help. +See also :ref:`bugs` for more information on filing bugs and getting help. -*********** DESCRIPTION -*********** +=========== +:program:`pt-online-schema-change` performs online, non-blocking schema changes to tables. -pt-online-schema-change performs online, non-blocking schema changes to tables. Only one table can be altered at a time because triggers are used to capture and synchronize changes between the table and the temporary table that will take its place once it has been altered. Since triggers are used, this -tool only works with MySQL 5.0.2 and newer. +tool only works with |MySQL| 5.0.2 and newer. The table to alter is specified by the DSN \ ``t``\ part on the command line, as shown in the "SYNOPSIS" examples. A database must also be specified -either by the DSN \ ``D``\ part or by the "--database" option. +either by the DSN \ ``D``\ part or by the :option:`--database` option. If you're using replication, read "REPLICATION" or else you may break replication. Performing an online schema change in a replication environment @@ -115,14 +115,14 @@ table; this part can take awhile. When done copying rows, the two tables are swapped by using \ ``RENAME TABLE``\ . At this point there are two copies of the table: the old table which used to be the original table, and the new table which used to be the temporary table but now has the same name -as the original table. If "--drop-old-table" is specified, then the +as the original table. If :option:`--drop-old-table` is specified, then the old table is dropped. For example, if you alter table \ ``foo``\ , the tool will create table \ ``__tmp_foo``\ , alter it, define triggers on \ ``foo``\ , and then copy rows from \ ``foo``\ to \ ``__tmp_foo``\ . Once all rows are copied, \ ``foo``\ is renamed to \ ``__old_foo``\ and \ ``__tmp_foo``\ is renamed to \ ``foo``\ . -If "--drop-old-table" is specified, then \ ``__old_foo``\ is dropped. +If :option:`--drop-old-table` is specified, then \ ``__old_foo``\ is dropped. The tool preforms the following steps: @@ -162,7 +162,6 @@ employs synchronous triggers (Shlomi's method), \ ``INSERT-SELECT``\ , and Here are options related to each phase: - .. code-block:: perl 1. --[no]create-tmp-table, --alter, --tmp-table @@ -173,45 +172,42 @@ Here are options related to each phase: 6. --drop-old-table -Options "--check-tables-and-exit" and "--print" are helpful to see what +Options :option:`--check-tables-and-exit` and :option:`--print` are helpful to see what the tool might do before actually doing it. -*********** REPLICATION -*********** +=========== In brief: update slaves first if columns are added or removed. Certain ALTER changes like ENGINE may not affect replication. -****** OUTPUT -****** +====== -Output to STDOUT is very verbose and should tell you everything that the -tool is doing. Warnings, errors, and "--progress" are printed to STDERR. +Output to ``STDOUT`` is very verbose and should tell you everything that the +tool is doing. Warnings, errors, and :option:`--progress` are printed to ``STDERR``. -******* OPTIONS -******* +======= This tool accepts additional command-line arguments. Refer to the "SYNOPSIS" and usage information for details. ---alter +.. option:: --alter type: string Semicolon-separated list of \ ``ALTER TABLE``\ statements to apply to the new table. The statements should not contain \ ``ALTER TABLE``\ , just what would follow that - clause. For example, if you want to \ ``ALTER TABLE ENGINE=InnoDB``\ , the value - would be \ ``ENGINE=InnoDB``\ . + clause. For example, if you want to \ ``ALTER TABLE ENGINE=|InnoDB|``\ , the value + would be \ ``ENGINE=|InnoDB|``\ . The value can also be a filename which contains statements, one per line with no blank lines and no trailing semicolons. Each statement will be @@ -219,44 +215,44 @@ This tool accepts additional command-line arguments. Refer to the ---ask-pass +.. option:: --ask-pass - Prompt for a password when connecting to MySQL. + Prompt for a password when connecting to |MySQL|. ---bin-log +.. option:: --bin-log Allow binary logging (\ ``SET SQL_LOG_BIN=1``\ ). By default binary logging is - turned off because in most cases the "--tmp-table" does not need to + turned off because in most cases the :option:`--tmp-table` does not need to be replicated. Also, performing an online schema change in a replication environment requires careful planning else replication may be broken; see "REPLICATION". ---charset +.. option:: --charset short form: -A; type: string - Default character set. If the value is utf8, sets Perl's binmode on - STDOUT to utf8, passes the mysql_enable_utf8 option to DBD::mysql, and runs SET - NAMES UTF8 after connecting to MySQL. Any other value sets binmode on STDOUT - without the utf8 layer, and runs SET NAMES after connecting to MySQL. + Default character set. If the value is utf8, sets *Perl* 's binmode on + ``STDOUT`` to utf8, passes the mysql_enable_utf8 option to ``DBD::mysql``, and runs SET + NAMES UTF8 after connecting to |MySQL|. Any other value sets binmode on ``STDOUT`` + without the utf8 layer, and runs SET NAMES after connecting to |MySQL|. ---check-tables-and-exit +.. option:: --check-tables-and-exit Check that the table can be altered then exit; do not alter the table. If you just want to see that the tool can/will work for the given table, specify this option. Even if all checks pass, the tool may still encounter - problems if, for example, one of the "--alter" statements uses + problems if, for example, one of the :option:`--alter` statements uses incorrect syntax. ---child-tables +.. option:: --child-tables type: string @@ -272,11 +268,11 @@ This tool accepts additional command-line arguments. Refer to the \ ``INFORMATION_SCHEMA``\ to auto-detect any foreign key constraints on the table. When specifying this option, you must also specify - "--update-foreign-keys-method". + :option:`--update-foreign-keys-method`. ---chunk-size +.. option:: --chunk-size type: string; default: 1000 @@ -286,7 +282,7 @@ This tool accepts additional command-line arguments. Refer to the ---cleanup-and-exit +.. option:: --cleanup-and-exit Cleanup and exit; do not alter the table. If a previous run fails, you may need to use this option to remove any temporary tables, triggers, @@ -294,7 +290,7 @@ This tool accepts additional command-line arguments. Refer to the ---config +.. option:: --config type: Array @@ -303,21 +299,21 @@ This tool accepts additional command-line arguments. Refer to the ---[no]create-tmp-table +.. option:: --[no]create-tmp-table default: yes - Create the "--tmp-table" with \ ``CREATE TABLE LIKE``\ . The temporary table - to which the "--alter" statements are applied is automatically created + Create the :option:`--tmp-table` with \ ``CREATE TABLE LIKE``\ . The temporary table + to which the :option:`--alter` statements are applied is automatically created by default with the name \ ``__tmp_TABLE``\ where \ ``TABLE``\ is the original table specified by the DSN on the command line. If you want to create the temporary table manually before running this tool, then you must specify - \ ``--no-create-tmp-table``\ \ **and**\ "--tmp-table" so the tool will use your + \ ``--no-create-tmp-table``\ \ **and**\ :option:`--tmp-table` so the tool will use your temporary table. ---database +.. option:: --database short form: -D; type: string @@ -326,7 +322,7 @@ This tool accepts additional command-line arguments. Refer to the ---defaults-file +.. option:: --defaults-file short form: -F; type: string @@ -335,20 +331,20 @@ This tool accepts additional command-line arguments. Refer to the ---drop-old-table +.. option:: --drop-old-table - Drop the original table after it's swapped with the "--tmp-table". - After the original table is renamed/swapped with the "--tmp-table" + Drop the original table after it's swapped with the :option:`--tmp-table`. + After the original table is renamed/swapped with the :option:`--tmp-table` it becomes the "old table". By default, the old table is not dropped because if there are problems with the "new table" (the temporary table swapped for the original table), then the old table can be restored. If altering a table with foreign key constraints, you may need to specify - this option depending on which "--update-foreign-keys-method" you choose. + this option depending on which :option:`--update-foreign-keys-method` you choose. ---[no]foreign-key-checks +.. option:: --[no]foreign-key-checks default: yes @@ -356,13 +352,13 @@ This tool accepts additional command-line arguments. Refer to the ---help +.. option:: --help Show help and exit. ---host +.. option:: --host short form: -h; type: string @@ -370,7 +366,7 @@ This tool accepts additional command-line arguments. Refer to the ---password +.. option:: --password short form: -p; type: string @@ -378,7 +374,7 @@ This tool accepts additional command-line arguments. Refer to the ---pid +.. option:: --pid type: string @@ -389,7 +385,7 @@ This tool accepts additional command-line arguments. Refer to the ---port +.. option:: --port short form: -P; type: int @@ -397,18 +393,18 @@ This tool accepts additional command-line arguments. Refer to the ---print +.. option:: --print - Print SQL statements to STDOUT instead of executing them. Specifying this + Print SQL statements to ``STDOUT`` instead of executing them. Specifying this option allows you to see most of the statements that the tool would execute. ---progress +.. option:: --progress type: array; default: time,30 - Print progress reports to STDERR while copying rows. + Print progress reports to ``STDERR`` while copying rows. The value is a comma-separated list with two parts. The first part can be percentage, time, or iterations; the second part specifies how often an update @@ -416,37 +412,37 @@ This tool accepts additional command-line arguments. Refer to the ---quiet +.. option:: --quiet short form: -q - Do not print messages to STDOUT. Errors and warnings are still printed to - STDERR. + Do not print messages to ``STDOUT``. Errors and warnings are still printed to + ``STDERR``. ---[no]rename-tables +.. option:: --[no]rename-tables default: yes - Rename/swap the original table and the "--tmp-table". This option + Rename/swap the original table and the :option:`--tmp-table`. This option essentially completes the online schema change process by making the temporary table with the new schema take the place of the original table. The original tables becomes the "old table" and is dropped if - "--drop-old-table" is specified. + :option:`--drop-old-table` is specified. ---set-vars +.. option:: --set-vars type: string; default: wait_timeout=10000 - Set these MySQL variables. Immediately after connecting to MySQL, this string + Set these |MySQL| variables. Immediately after connecting to |MySQL|, this string will be appended to SET and executed. ---sleep +.. option:: --sleep type: float; default: 0 @@ -455,7 +451,7 @@ This tool accepts additional command-line arguments. Refer to the ---socket +.. option:: --socket short form: -S; type: string @@ -463,7 +459,7 @@ This tool accepts additional command-line arguments. Refer to the ---tmp-table +.. option:: --tmp-table type: string @@ -480,22 +476,22 @@ This tool accepts additional command-line arguments. Refer to the ---update-foreign-keys-method +.. option:: --update-foreign-keys-method type: string - Method for updating foreign key constraints in "--child-tables". If - "--child-tables" is specified, the tool will need to ensure that foreign + Method for updating foreign key constraints in :option:`--child-tables`. If + :option:`--child-tables` is specified, the tool will need to ensure that foreign key constraints in those tables continue to reference the original table after it is renamed and/or dropped. This is necessary because when a parent - table is renamed, MySQL automatically updates all child table + table is renamed, |MySQL| automatically updates all child table foreign key constraints that reference the renamed table so that the rename does not break foreign key constraints. This poses a problem for this tool. For example: if the table being altered is \ ``foo``\ , then \ ``foo``\ is renamed - to \ ``__old_foo``\ when it is swapped with the "--tmp-table". + to \ ``__old_foo``\ when it is swapped with the :option:`--tmp-table`. Any foreign key references to \ ``foo``\ before it is swapped/renamed are renamed - automatically by MySQL to \ ``__old_foo``\ . We do not want this; we want those + automatically by |MySQL| to \ ``__old_foo``\ . We do not want this; we want those foreign key references to continue to reference \ ``foo``\ . There are currently two methods to solve this problem: @@ -504,7 +500,7 @@ This tool accepts additional command-line arguments. Refer to the rebuild_constraints Drop and re-add child table foreign key constraints to reference the new table. - (The new table is the temporary table after being renamed/swapped. To MySQL + (The new table is the temporary table after being renamed/swapped. To |MySQL| it's a new table because it does not know that it's a copy of the original table). This method parses foreign key constraints referencing the original table from all child tables, drops them, then re-adds them referencing the @@ -512,7 +508,7 @@ This tool accepts additional command-line arguments. Refer to the This method uses \ ``ALTER TABLE``\ which can by slow and blocking, but it is safer because the old table does not need to be dropped. So if there's a - problem with the new table and "--drop-old-table" was not specified, + problem with the new table and :option:`--drop-old-table` was not specified, then the original table can be restored. @@ -520,13 +516,13 @@ This tool accepts additional command-line arguments. Refer to the drop_old_table Disable foreign key checks (FOREIGN_KEY_CHECKS=0) then drop the original table. - This method bypasses MySQL's auto-renaming feature by disabling foreign key + This method bypasses |MySQL|'s auto-renaming feature by disabling foreign key checks, dropping the original table, then renaming the temporary table with the same name. Foreign key checks must be disabled to drop table because it is referenced by foreign key constraints. Since the original table is not renamed, - MySQL does not auto-rename references to it. Then the temporary table is + |MySQL| does not auto-rename references to it. Then the temporary table is renamed to the same name so child table references are maintained. - So this method requires "--drop-old-table". + So this method requires :option:`--drop-old-table`. This method is faster and does not block, but it is less safe for two reasons. One, for a very short time (between dropping the original table and renaming the @@ -539,7 +535,7 @@ This tool accepts additional command-line arguments. Refer to the ---user +.. option:: --user short form: -u; type: string @@ -547,16 +543,15 @@ This tool accepts additional command-line arguments. Refer to the ---version +.. option:: --version Show version and exit. -*********** DSN OPTIONS -*********** +=========== These DSN options are used to create a DSN. Each option is given like @@ -566,7 +561,7 @@ if the value contains whitespace it must be quoted. DSN options are comma-separated. See the percona-toolkit manpage for full details. -\* A + * ``A`` dsn: charset; copy: yes @@ -574,7 +569,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* D + * ``D`` dsn: database; copy: yes @@ -582,7 +577,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* F + * ``F`` dsn: mysql_read_default_file; copy: yes @@ -590,7 +585,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* h + * ``h`` dsn: host; copy: yes @@ -598,7 +593,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* p + * ``p`` dsn: password; copy: yes @@ -606,7 +601,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* P + * ``p`` dsn: port; copy: yes @@ -614,7 +609,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* S + * ``S`` dsn: mysql_socket; copy: yes @@ -622,7 +617,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* t + * ``t`` dsn: table; copy: no @@ -630,7 +625,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* u + * ``u`` dsn: user; copy: yes @@ -639,12 +634,11 @@ comma-separated. See the percona-toolkit manpage for full details. -*********** ENVIRONMENT -*********** +=========== -The environment variable \ ``PTDEBUG``\ enables verbose debugging output to STDERR. +The environment variable \ ``PTDEBUG``\ enables verbose debugging output to ``STDERR``. To enable debugging and capture all output to a file, run the tool like: @@ -657,91 +651,30 @@ Be careful: debugging output is voluminous and can generate several megabytes of output. -******************* SYSTEM REQUIREMENTS -******************* +=================== -You need Perl, DBI, DBD::mysql, and some core packages that ought to be -installed in any reasonably new version of Perl. +You need *Perl* , ``DBI``, ``DBD::mysql``, and some core packages that ought to be +installed in any reasonably new version of *Perl* . -**** BUGS -**** +==== For a list of known bugs, see `http://www.percona.com/bugs/pt-online-schema-change `_. 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* -Baron Schwartz - - -*************** ACKNOWLEDGMENTS -*************** +=============== The "online schema change" concept was first implemented by Shlomi Noach @@ -751,57 +684,25 @@ their version called \ ``OnlineSchemaChange.php``\ as explained by their blog post: `http://tinyurl.com/32zeb86 `_. Searching for "online schema change" will return other relevant pages about this concept. -This implementation, \ ``pt-online-schema-change``\ , is a hybrid of Shlomi's +This implementation, :program:`pt-online-schema-change`, is a hybrid of Shlomi's and Facebook's approach. Shlomi's code is a full-featured tool with command line options, documentation, etc., but its continued development/support is not assured. Facebook's tool has certain technical advantages, but it's not a full-featured tool; it's more a custom job by Facebook for Facebook. And -neither of those tools is tested. \ ``pt-online-schema-change``\ is a +neither of those tools is tested. :program:`pt-online-schema-change` is a full-featured, tested tool with stable development and support. -This tool was made possible by a generous client of Percona Inc. +This tool was made possible by a generous client of *Percona Inc*. - -********************* -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 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 -******* +======= - -pt-online-schema-change 1.0.1 +:program:`pt-online-schema-change` 1.0.1 diff --git a/docs/user/source/pt-pmp.rst b/docs/user/source/pt-pmp.rst new file mode 100644 index 00000000..bbcf48cd --- /dev/null +++ b/docs/user/source/pt-pmp.rst @@ -0,0 +1,153 @@ +.. program:: pt-pmp + +=================== + :program:`pt-pmp` +=================== + +.. highlight:: perl + + +NAME +==== + + :program:`pt-pmp` - Aggregate GDB stack traces for a selected program. + + +SYNOPSIS +======== + + +Usage +----- + +:: + + pt-pmp [OPTIONS] [FILES] + +:program:`pt-pmp` is a poor man's profiler, inspired by `http://poormansprofiler.org `_. + +It can create and summarize full stack traces of processes on Linux. +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. + +:program:`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 :ref:`bugs` for more information on filing bugs and getting help. + + +DESCRIPTION +=========== + +:program:`pt-pmp` performs two tasks: it gets a stack trace, and it summarizes the stack +trace. If a file is given on the command line, the tool skips the first step and just aggregates the file. + +To summarize the stack trace, the tool extracts the function name (symbol) +from each level of the stack, and combines them with commas. It does this +for each thread in the output. Afterwards, it sorts similar threads together +and counts how many of each one there are, then sorts them most-frequent first. + + +OPTIONS +======= + + +Options must precede files on the command line. + + +.. option:: -b BINARY + + Which binary to trace (default mysqld) + + + +.. option:: -i ITERATIONS + + How many traces to gather and aggregate (default 1) + + + +.. option:: -k KEEPFILE + + Keep the raw traces in this file after aggregation + + + +.. option:: -l NUMBER + + Aggregate only first NUMBER functions; 0=infinity (default 0) + + + +.. option:: -p PID + + Process ID of the process to trace; overrides -b + + + +.. option:: -s SLEEPTIME + + Number of seconds to sleep between iterations (default 0) + + + + +ENVIRONMENT +=========== + + +This tool does not use any environment variables. + + +SYSTEM REQUIREMENTS +=================== + + +This tool requires Bash v3 or newer. + + +BUGS +==== + + +For a list of known bugs, see `http://www.percona.com/bugs/pt-pmp `_. + +Please report bugs at `https://bugs.launchpad.net/percona-toolkit `_. + + +AUTHORS +======= + + +*Baron Schwartz*, based on a script by *Domas Mituzas* (`http://poormansprofiler.org/ `_) + + +COPYRIGHT, LICENSE, AND WARRANTY +================================ + +This program is copyright 2010-2011 *Baron Schwartz*, 2011 Percona Inc. +Feedback and improvements are welcome. + + +VERSION +======= + +:program:`pt-pmp` 1.0.1 + diff --git a/docs/user/pt-query-advisor.rst b/docs/user/source/pt-query-advisor.rst similarity index 70% rename from docs/user/pt-query-advisor.rst rename to docs/user/source/pt-query-advisor.rst index 30978494..02e61130 100644 --- a/docs/user/pt-query-advisor.rst +++ b/docs/user/source/pt-query-advisor.rst @@ -1,28 +1,31 @@ +.. program:: pt-query-advisor -################ -pt-query-advisor -################ +============================= + :program:`pt-query-advisor` +============================= .. highlight:: perl -**** NAME -**** +==== + + :program:`pt-query-advisor` - Analyze queries and advise on possible problems. -pt-query-advisor - Analyze queries and advise on possible problems. - - -******** SYNOPSIS -******** +======== -Usage: pt-query-advisor [OPTION...] [FILE] +Usage +----- -pt-query-advisor analyzes queries and advises on possible problems. -Queries are given either by specifying slowlog files, --query, or --review. +:: + + pt-query-advisor [OPTION...] [FILE] + +:program:`pt-query-advisor` analyzes queries and advises on possible problems. +Queries are given either by specifying slowlog files, :option:`--query`, or :option:`--review`. Analyze all queries in a slow log: @@ -40,7 +43,7 @@ Analyze all queires in a general log: pt-query-advisor --type genlog mysql.log -Get queries from tcpdump using pt-query-digest: +Get queries from :command:`tcpdump` using :program:`pt-query-digest`: .. code-block:: perl @@ -48,18 +51,15 @@ Get queries from tcpdump using pt-query-digest: pt-query-digest --type tcpdump.txt --print --no-report | pt-query-advisor - -***** 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-query-advisor simply reads queries and examines them, and is thus +:program:`pt-query-advisor` simply reads queries and examines them, and is thus very low risk. At the time of this release there is a bug that may cause an infinite (or @@ -70,27 +70,23 @@ 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-query-advisor `_. -See also "BUGS" for more information on filing bugs and getting help. +See also :ref:`bugs` for more information on filing bugs and getting help. -*********** DESCRIPTION -*********** +=========== - -pt-query-advisor examines queries and applies rules to them, trying to +:program:`pt-query-advisor` examines queries and applies rules to them, trying to find queries that look bad according to the rules. It reports on queries that match the rules, so you can find bad practices or hidden -problems in your SQL. By default, it accepts a MySQL slow query log +problems in your SQL. By default, it accepts a |MySQL| slow query log as input. -***** RULES -***** +===== - -These are the rules that pt-query-advisor will apply to the queries it +These are the rules that :program:`pt-query-advisor` will apply to the queries it examines. Each rule has three bits of information: an ID, a severity and a description. @@ -112,7 +108,7 @@ which is sort of a terse synopsis of the rule's meaning. At a higher verbosity, you'll see subsequent sentences. -ALI.001 + * ``ALI.001`` severity: note @@ -122,7 +118,7 @@ ALI.001 -ALI.002 + * ``ALI.002`` severity: warn @@ -133,7 +129,7 @@ ALI.002 -ALI.003 + * ``ALI.003`` severity: note @@ -142,7 +138,7 @@ ALI.003 -ARG.001 + * ``ARG.001`` severity: warn @@ -152,7 +148,7 @@ ARG.001 -ARG.002 + * ``ARG.002`` severity: note @@ -161,7 +157,7 @@ ARG.002 -CLA.001 + * ``CLA.001`` severity: warn @@ -169,7 +165,7 @@ CLA.001 -CLA.002 + * ``CLA.002`` severity: note @@ -178,7 +174,7 @@ CLA.002 -CLA.003 + * ``CLA.003`` severity: note @@ -188,7 +184,7 @@ CLA.003 -CLA.004 + * ``CLA.004`` severity: note @@ -198,7 +194,7 @@ CLA.004 -CLA.005 + * ``CLA.005`` severity: warn @@ -206,7 +202,7 @@ CLA.005 -CLA.006 + * ``CLA.006`` severity: warn @@ -214,17 +210,17 @@ CLA.006 -CLA.007 + * ``CLA.007`` severity: warn ORDER BY different directions prevents index from being used. All tables - in the ORDER BY clause must be either ASC or DESC, else MySQL cannot use + in the ORDER BY clause must be either ASC or DESC, else |MySQL| cannot use an index. -COL.001 + * ``COL.001`` severity: note @@ -234,7 +230,7 @@ COL.001 -COL.002 + * ``COL.002`` severity: note @@ -245,7 +241,7 @@ COL.002 -LIT.001 + * ``LIT.001`` severity: warn @@ -256,7 +252,7 @@ LIT.001 -LIT.002 + * ``LIT.002`` severity: warn @@ -265,7 +261,7 @@ LIT.002 -KWR.001 + * ``KWR.001`` severity: note @@ -276,17 +272,17 @@ KWR.001 -JOI.001 + * ``JOI.001`` severity: crit Mixing comma and ANSI joins. Mixing comma joins and ANSI joins is confusing to humans, and the behavior differs between some - MySQL versions. + |MySQL| versions. -JOI.002 + * ``JOI.002`` severity: crit @@ -295,7 +291,7 @@ JOI.002 -JOI.003 + * ``JOI.003`` severity: warn @@ -304,7 +300,7 @@ JOI.003 -JOI.004 + * ``JOI.004`` severity: warn @@ -316,7 +312,7 @@ JOI.004 -RES.001 + * ``RES.001`` severity: warn @@ -326,7 +322,7 @@ RES.001 -RES.002 + * ``RES.002`` severity: warn @@ -335,7 +331,7 @@ RES.002 -STA.001 + * ``STA.001`` severity: note @@ -343,49 +339,47 @@ STA.001 -SUB.001 + * ``SUB.001`` severity: crit - IN() and NOT IN() subqueries are poorly optimized. MySQL executes the subquery + IN() and NOT IN() subqueries are poorly optimized. |MySQL| executes the subquery as a dependent subquery for each row in the outer query. This is a frequent - cause of serious performance problems. This might change version 6.0 of MySQL, + cause of serious performance problems. This might change version 6.0 of |MySQL|, but for versions 5.1 and older, the query should be rewritten as a JOIN or a LEFT OUTER JOIN, respectively. - -******* OPTIONS -******* +======= -"--query" and "--review" are mutually exclusive. +:option:`--query` and :option:`--review` are mutually exclusive. This tool accepts additional command-line arguments. Refer to the "SYNOPSIS" and usage information for details. ---ask-pass +.. option:: --ask-pass - Prompt for a password when connecting to MySQL. + Prompt for a password when connecting to |MySQL|. ---charset +.. option:: --charset short form: -A; type: string - Default character set. If the value is utf8, sets Perl's binmode on - STDOUT to utf8, passes the mysql_enable_utf8 option to DBD::mysql, and - runs SET NAMES UTF8 after connecting to MySQL. Any other value sets - binmode on STDOUT without the utf8 layer, and runs SET NAMES after - connecting to MySQL. + Default character set. If the value is utf8, sets *Perl* 's binmode on + ``STDOUT`` to utf8, passes the mysql_enable_utf8 option to ``DBD::mysql``, and + runs SET NAMES UTF8 after connecting to |MySQL|. Any other value sets + binmode on ``STDOUT`` without the utf8 layer, and runs SET NAMES after + connecting to |MySQL|. ---config +.. option:: --config type: Array @@ -394,7 +388,7 @@ This tool accepts additional command-line arguments. Refer to the ---[no]continue-on-error +.. option:: --[no]continue-on-error default: yes @@ -402,24 +396,24 @@ This tool accepts additional command-line arguments. Refer to the ---daemonize +.. option:: --daemonize Fork to the background and detach from the shell. POSIX operating systems only. ---database +.. option:: --database short form: -D; type: string Connect to this database. This is also used as the default database - for "--[no]show-create-table" if a query does not use database-qualified + for :option:`--[no]show-create-table` if a query does not use database-qualified tables. ---defaults-file +.. option:: --defaults-file short form: -F; type: string @@ -428,7 +422,7 @@ This tool accepts additional command-line arguments. Refer to the ---group-by +.. option:: --group-by type: string; default: rule_id @@ -446,13 +440,13 @@ This tool accepts additional command-line arguments. Refer to the ---help +.. option:: --help Show help and exit. ---host +.. option:: --host short form: -h; type: string @@ -460,7 +454,7 @@ This tool accepts additional command-line arguments. Refer to the ---ignore-rules +.. option:: --ignore-rules type: hash @@ -471,7 +465,7 @@ This tool accepts additional command-line arguments. Refer to the ---password +.. option:: --password short form: -p; type: string @@ -479,7 +473,7 @@ This tool accepts additional command-line arguments. Refer to the ---pid +.. option:: --pid type: string @@ -491,7 +485,7 @@ This tool accepts additional command-line arguments. Refer to the ---port +.. option:: --port short form: -P; type: int @@ -499,27 +493,27 @@ This tool accepts additional command-line arguments. Refer to the ---print-all +.. option:: --print-all Print all queries, even those that do not match any rules. With - "--group-by" \ ``none``\ , non-matching queries are printed in the main report - and profile. For other "--group-by" values, non-matching queries are only + :option:`--group-by` \ ``none``\ , non-matching queries are printed in the main report + and profile. For other :option:`--group-by` values, non-matching queries are only printed in the profile. Non-matching queries have zeros for \ ``NOTE``\ , \ ``WARN``\ and \ ``CRIT``\ in the profile. ---query +.. option:: --query type: string - Analyze this single query and ignore files and STDIN. This option + Analyze this single query and ignore files and ``STDIN``. This option allows you to supply a single query on the command line. Any files also specified on the command line are ignored. ---report-format +.. option:: --report-format type: string; default: compact @@ -530,7 +524,7 @@ This tool accepts additional command-line arguments. Refer to the ---review +.. option:: --review type: DSN @@ -538,7 +532,7 @@ This tool accepts additional command-line arguments. Refer to the ---sample +.. option:: --sample type: int; default: 1 @@ -546,22 +540,22 @@ This tool accepts additional command-line arguments. Refer to the ---set-vars +.. option:: --set-vars type: string; default: wait_timeout=10000 - Set these MySQL variables. Immediately after connecting to MySQL, this string + Set these |MySQL| variables. Immediately after connecting to |MySQL|, this string will be appended to SET and executed. ---[no]show-create-table +.. option:: --[no]show-create-table default: yes Get \ ``SHOW CREATE TABLE``\ for each query's table. - If host connection options are given (like "--host", "--port", etc.) + If host connection options are given (like :option:`--host", "--port`, etc.) then the tool will also get \ ``SHOW CREATE TABLE``\ for each query. This information is needed for some rules like JOI.004. If this option is disabled by specifying \ ``--no-show-create-table``\ then some rules may not @@ -569,7 +563,7 @@ This tool accepts additional command-line arguments. Refer to the ---socket +.. option:: --socket short form: -S; type: string @@ -577,7 +571,7 @@ This tool accepts additional command-line arguments. Refer to the ---type +.. option:: --type type: Array @@ -586,7 +580,7 @@ This tool accepts additional command-line arguments. Refer to the ---user +.. option:: --user short form: -u; type: string @@ -594,35 +588,34 @@ This tool accepts additional command-line arguments. Refer to the ---verbose +.. option:: --verbose short form: -v; cumulative: yes; default: 1 Increase verbosity of output. At the default level of verbosity, the program prints only the first sentence of each rule's description. At higher levels, the program prints more of the description. See also - "--report-format". + :option:`--report-format`. ---version +.. option:: --version Show version and exit. ---where +.. option:: --where type: string - Apply this WHERE clause to the SELECT query on the "--review" table. + Apply this WHERE clause to the SELECT query on the :option:`--review` table. -*********** DSN OPTIONS -*********** +=========== These DSN options are used to create a DSN. Each option is given like @@ -632,7 +625,7 @@ if the value contains whitespace it must be quoted. DSN options are comma-separated. See the percona-toolkit manpage for full details. -\* A + * ``A`` dsn: charset; copy: yes @@ -640,7 +633,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* D + * ``D`` dsn: database; copy: yes @@ -648,7 +641,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* F + * ``F`` dsn: mysql_read_default_file; copy: yes @@ -656,7 +649,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* h + * ``h`` dsn: host; copy: yes @@ -664,7 +657,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* p + * ``p`` dsn: password; copy: yes @@ -672,7 +665,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* P + * ``p`` dsn: port; copy: yes @@ -680,7 +673,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* S + * ``S`` dsn: mysql_socket; copy: yes @@ -688,13 +681,13 @@ comma-separated. See the percona-toolkit manpage for full details. -\* t + * ``t`` Table to use as the query review table. -\* u + * ``u`` dsn: user; copy: yes @@ -703,12 +696,11 @@ comma-separated. See the percona-toolkit manpage for full details. -*********** ENVIRONMENT -*********** +=========== -The environment variable \ ``PTDEBUG``\ enables verbose debugging output to STDERR. +The environment variable \ ``PTDEBUG``\ enables verbose debugging output to ``STDERR``. To enable debugging and capture all output to a file, run the tool like: @@ -721,128 +713,39 @@ Be careful: debugging output is voluminous and can generate several megabytes of output. -******************* SYSTEM REQUIREMENTS -******************* +=================== -You need Perl, DBI, DBD::mysql, and some core packages that ought to be -installed in any reasonably new version of Perl. +You need *Perl* , ``DBI``, ``DBD::mysql``, and some core packages that ought to be +installed in any reasonably new version of *Perl* . -**** BUGS -**** +==== For a list of known bugs, see `http://www.percona.com/bugs/pt-query-advisor `_. 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 and Daniel Nichter +*Baron Schwartz* and *Daniel Nichter* -********************* -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-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 -******* +======= - -pt-query-advisor 1.0.1 +:program:`pt-query-advisor` 1.0.1 diff --git a/docs/user/pt-query-digest.rst b/docs/user/source/pt-query-digest.rst similarity index 72% rename from docs/user/pt-query-digest.rst rename to docs/user/source/pt-query-digest.rst index 24a4566f..8cfc0ece 100644 --- a/docs/user/pt-query-digest.rst +++ b/docs/user/source/pt-query-digest.rst @@ -1,27 +1,30 @@ +.. program:: pt-query-digest -############### -pt-query-digest -############### +============================ + :program:`pt-query-digest` +============================ .. highlight:: perl -**** NAME -**** +==== + + :program:`pt-query-digest` - Analyze query execution logs and generate a query report, filter, replay, or transform queries for |MySQL|, *PostgreSQL*, :command:`memcached`, and more. -pt-query-digest - Analyze query execution logs and generate a query report, filter, replay, or transform queries for MySQL, PostgreSQL, memcached, and more. - - -******** SYNOPSIS -******** +======== -Usage: pt-query-digest [OPTION...] [FILE] +Usage +----- -pt-query-digest parses and analyzes MySQL log files. With no FILE, or when +:: + + pt-query-digest [OPTION...] [FILE] + +:program:`pt-query-digest` parses and analyzes |MySQL| log files. With no FILE, or when FILE is -, it read standard input. Analyze, aggregate, and report on a slow query log: @@ -32,8 +35,8 @@ Analyze, aggregate, and report on a slow query log: pt-query-digest /path/to/slow.log -Review a slow log, saving results to the test.query_review table in a MySQL -server running on host1. See "--review" for more on reviewing queries: +Review a slow log, saving results to the test.query_review table in a |MySQL| +server running on host1. See :option:`--review` for more on reviewing queries: .. code-block:: perl @@ -51,7 +54,7 @@ server, then use the timings from replaying them to analyze their performance: --filter '$event->{fingerprint} =~ m/^select/' -Print the structure of events so you can construct a complex "--filter": +Print the structure of events so you can construct a complex :option:`--filter`: .. code-block:: perl @@ -78,9 +81,8 @@ you don't need the default report: -***** RISKS -***** +===== The following section is included to inform users about the potential risks, @@ -88,15 +90,15 @@ 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. -By default pt-query-digest merely collects and aggregates data from the files +By default :program:`pt-query-digest` merely collects and aggregates data from the files specified. It is designed to be as efficient as possible, but depending on the input you give it, it can use a lot of CPU and memory. Practically speaking, it is safe to run even on production systems, but you might want to monitor it until you are satisfied that the input you give it does not cause undue load. -Various options will cause pt-query-digest to insert data into tables, execute -SQL queries, and so on. These include the "--execute" option and -"--review". +Various options will cause :program:`pt-query-digest` to insert data into tables, execute +SQL queries, and so on. These include the :option:`--execute` option and +:option:`--review`. At the time of this release, we know of no bugs that could cause serious harm to users. @@ -106,35 +108,31 @@ 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-query-digest `_. -See also "BUGS" for more information on filing bugs and getting help. +See also :ref:`bugs` for more information on filing bugs and getting help. -*********** DESCRIPTION -*********** +=========== - -\ ``pt-query-digest``\ is a framework for doing things with events from a query +:program:`pt-query-digest` is a framework for doing things with events from a query source such as the slow query log or PROCESSLIST. By default it acts as a very sophisticated log analysis tool. You can group and sort queries in many different ways simultaneously and find the most expensive queries, or create a timeline of queries in the log, for example. It can also do a "query review," -which means to save a sample of each type of query into a MySQL table so you can +which means to save a sample of each type of query into a |MySQL| table so you can easily see whether you've reviewed and analyzed a query before. The benefit of this is that you can keep track of changes to your server's queries and avoid repeated work. You can also save other information with the queries, such as comments, issue numbers in your ticketing system, and so on. -Note that this is a work in \*very\* active progress and you should expect +Note that this is a work in *very* active progress and you should expect incompatible changes in the future. -********** ATTRIBUTES -********** +========== - -pt-query-digest works on events, which are a collection of key/value pairs +:program:`pt-query-digest` works on events, which are a collection of key/value pairs called attributes. You'll recognize most of the attributes right away: Query_time, Lock_time, and so on. You can just look at a slow log and see them. However, there are some that don't exist in the slow log, and slow logs @@ -144,7 +142,7 @@ server with the Percona patches). For a full list of attributes, see `http://code.google.com/p/maatkit/wiki/EventAttributes `_. -With creative use of "--filter", you can create new attributes derived +With creative use of :option:`--filter`, you can create new attributes derived from existing attributes. For example, to create an attribute called \ ``Row_ratio``\ for examining the ratio of \ ``Rows_sent``\ to \ ``Rows_examined``\ , specify a filter like: @@ -165,38 +163,36 @@ automatically appears in the output: # Row ratio 1.00 0.00 1 0.50 1 0.71 0.50 -Attributes created this way can be specified for "--order-by" or any +Attributes created this way can be specified for :option:`--order-by` or any option that requires an attribute. -memcached -========= +:command:`memcached` +-------------------- -memcached events have additional attributes related to the memcached protocol: -cmd, key, res (result) and val. Also, boolean attributes are created for +:command:`memcached` events have additional attributes related to the memcached protocol: cmd, key, res (result) and val. Also, boolean attributes are created for the various commands, misses and errors: Memc_CMD where CMD is a memcached command (get, set, delete, etc.), Memc_error and Memc_miss. These attributes are no different from slow log attributes, so you can use them -with "--[no]report", "--group-by", in a "--filter", etc. +with :option:`--[no]report`, :option:`--group-by`, in a :option:`--filter`, etc. These attributes and more are documented at `http://code.google.com/p/maatkit/wiki/EventAttributes `_. -****** OUTPUT -****** +====== -The default output is a query analysis report. The "--[no]report" option +The default output is a query analysis report. The :option:`--[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" or "--review". +:option:`--print` or :option:`--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 +all have the same value for the :option:`--group-by` attribute which is "fingerprint" by default. (See "ATTRIBUTES".) A fingerprint is an abstracted version of the query text with literals removed, whitespace collapsed, and so forth. The report is formatted so it's easy to paste into @@ -204,7 +200,7 @@ emails without wrapping, and all non-query lines begin with a comment, so you can save it to a .sql file and open it in your favorite syntax-highlighting text editor. There is a response-time profile at the beginning. -The output described here is controlled by "--report-format". +The output described here is controlled by :option:`--report-format`. That option allows you to specify what to print and in what order. The default output in the default order is described here. @@ -237,7 +233,7 @@ that follows. It contains the following columns: A final line whose rank is shown as MISC contains aggregate statistics on the queries that were not included in the report, due to options such as -"--limit" and "--outliers". For details on the variance-to-mean ratio, +:option:`--limit` and :option:`--outliers`. For details on the variance-to-mean ratio, please see http://en.wikipedia.org/wiki/Index_of_dispersion. Next, the detailed query report is printed. Each query appears in a paragraph. @@ -250,18 +246,18 @@ commentary. # Query 2: 0.01 QPS, 0.02x conc, ID 0xFDEA8D2993C9CAF3 at byte 160665 - This line identifies the sequential number of the query in the sort order -specified by "--order-by". Then there's the queries per second, and the +specified by :option:`--order-by`. Then there's the queries per second, and the approximate concurrency for this query (calculated as a function of the timespan and total Query_time). Next there's a query ID. This ID is a hex version of -the query's checksum in the database, if you're using "--review". You can +the query's checksum in the database, if you're using :option:`--review`. You can select the reviewed query's details from the database with a query like \ ``SELECT .... WHERE checksum=0xFDEA8D2993C9CAF3``\ . If you are investigating the report and want to print out every sample of a -particular query, then the following "--filter" may be helpful: -\ ``pt-query-digest slow-log.log --no-report --print --filter '$event-``\ {fingerprint} +particular query, then the following :option:`--filter` may be helpful: :: + + pt-query-digest slow-log.log --no-report --print --filter '$event-``\ {fingerprint} && make_checksum($event->{fingerprint}) eq "FDEA8D2993C9CAF3"'>. Notice that you must remove the 0x prefix from the checksum in order for this to work. @@ -335,7 +331,7 @@ goes into one of the "buckets" and is counted up. The buckets are powers of ten. The first bucket is all values in the "single microsecond range" -- that is, less than 10us. The second is "tens of microseconds," which is from 10us up to (but not including) 100us; and so on. The charted attribute can be -changed by specifying "--report-histogram" but is limited to time-based +changed by specifying :option:`--report-histogram` but is limited to time-based attributes. @@ -354,8 +350,7 @@ These are copy-and-paste-ready commands to do that. Finally, we see a sample of the queries in this class of query. This is not a random sample. It is the query that performed the worst, according to the sort -order given by "--order-by". You will normally see a commented \ ``# EXPLAIN``\ -line just before it, so you can copy-paste the query to examine its EXPLAIN +order given by :option:`--order-by`. You will normally see a commented \ ``# EXPLAIN``\ line just before it, so you can copy-paste the query to examine its EXPLAIN plan. But for non-SELECT queries that isn't possible to do, so the tool tries to transform the query into a roughly equivalent SELECT query, and adds that below. @@ -368,77 +363,60 @@ above, and something like the following: tail -c + /path/to/file | head -See also "--report-format". +See also :option:`--report-format`. SPARKLINES -========== +---------- The output also contains sparklines. Sparklines are "data-intense, -design-simple, word-sized graphics" (`http://en.wikipedia.org/wiki/Sparkline `_).There is a sparkline for "--report-histogram" and for "--explain". +design-simple, word-sized graphics" (`http://en.wikipedia.org/wiki/Sparkline `_).There is a sparkline for :option:`--report-histogram` and for :option:`--explain`. + See each of those options for details about interpreting their sparklines. - -************* QUERY REVIEWS -************* - +============= A "query review" is the process of storing all the query fingerprints analyzed. This has several benefits: -\* - - You can add meta-data to classes of queries, such as marking them for follow-up, + * You can add meta-data to classes of queries, such as marking them for follow-up, adding notes to queries, or marking them with an issue ID for your issue tracking system. -\* - - You can refer to the stored values on subsequent runs so you'll know whether + * You can refer to the stored values on subsequent runs so you'll know whether you've seen a query before. This can help you cut down on duplicated work. -\* - - You can store historical data such as the row count, query times, and generally + * You can store historical data such as the row count, query times, and generally anything you can see in the report. -To use this feature, you run pt-query-digest with the "--review" option. It -will store the fingerprints and other information into the table you specify. -Next time you run it with the same option, it will do the following: +To use this feature, you run :program:`pt-query-digest` with the :option:`--review` option. It will store the fingerprints and other information into the table you specify. Next time you run it with the same option, it will do the following: -\* - - It won't show you queries you've already reviewed. A query is considered to be + * It won't show you queries you've already reviewed. A query is considered to be already reviewed if you've set a value for the \ ``reviewed_by``\ column. (If you - want to see queries you've already reviewed, use the "--report-all" option.) + want to see queries you've already reviewed, use the :option:`--report-all` option.) -\* - - Queries that you've reviewed, and don't appear in the output, will cause gaps in + * Queries that you've reviewed, and don't appear in the output, will cause gaps in the query number sequence in the first line of each paragraph. And the value - you've specified for "--limit" will still be honored. So if you've reviewed all + you've specified for :option:`--limit` will still be honored. So if you've reviewed all queries in the top 10 and you ask for the top 10, you won't see anything in the output. -\* - - If you want to see the queries you've already reviewed, you can specify - "--report-all". Then you'll see the normal analysis output, but you'll also see - the information from the review table, just below the execution time graph. For + * If you want to see the queries you've already reviewed, you can specify + :option:`--report-all`. Then you'll see the normal analysis output, but you'll also see the information from the review table, just below the execution time graph. For example, @@ -457,16 +435,13 @@ Next time you run it with the same option, it will do the following: You can see how useful this meta-data is -- as you analyze your queries, you get your comments integrated right into the report. - If you add the "--review-history" option, it will also store information into + If you add the :option:`--review-history` option, it will also store information into a separate database table, so you can keep historical trending information on classes of queries. - - -************ FINGERPRINTS -************ +============ A query fingerprint is the abstracted form of a query, which makes it possible @@ -492,7 +467,7 @@ Both of those queries will fingerprint to Once the query's fingerprint is known, we can then talk about a query as though it represents all similar queries. -What \ ``pt-query-digest``\ does is analogous to a GROUP BY statement in SQL. (But +What :program:`pt-query-digest` does is analogous to a GROUP BY statement in SQL. (But note that "multiple columns" doesn't define a multi-column grouping; it defines multiple reports!) If your command-line looks like this, @@ -516,12 +491,11 @@ The corresponding pseudo-SQL looks like this: You can also use the value \ ``distill``\ , which is a kind of super-fingerprint. -See "--group-by" for more. +See :option:`--group-by` for more. -When parsing memcached input ("--type" memcached), the fingerprint is an +When parsing memcached input (:option:`--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, \ ``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 @@ -534,35 +508,25 @@ with a reproducible test case. Here is a list of transformations during fingerprinting, which might not be exhaustive: -\* - - Group all SELECT queries from mysqldump together, even if they are against + * Group all SELECT queries from mysqldump together, even if they are against different tables. Ditto for all of pt-table-checksum's checksum queries. -\* - - Shorten multi-value INSERT statements to a single VALUES() list. + * Shorten multi-value INSERT statements to a single VALUES() list. -\* - - Strip comments. + * Strip comments. -\* - - Abstract the databases in USE statements, so all USE statements are grouped + * Abstract the databases in USE statements, so all USE statements are grouped together. -\* - - Replace all literals, such as quoted strings. For efficiency, the code that + * Replace all literals, such as quoted strings. For efficiency, the code that replaces literal numbers is somewhat non-selective, and might replace some things as numbers when they really are not. Hexadecimal literals are also replaced. NULL is treated as a literal. Numbers embedded in identifiers are @@ -571,45 +535,35 @@ fingerprinting, which might not be exhaustive: -\* - - Collapse all whitespace into a single space. + * Collapse all whitespace into a single space. -\* - - Lowercase the entire query. + * Lowercase the entire query. -\* - - Replace all literals inside of IN() and VALUES() lists with a single + * Replace all literals inside of IN() and VALUES() lists with a single placeholder, regardless of cardinality. -\* - - Collapse multiple identical UNION queries into a single one. + * Collapse multiple identical UNION queries into a single one. -******* OPTIONS -******* +======= -DSN values in "--review-history" default to values in "--review" if COPY +DSN values in :option:`--review-history` default to values in :option:`--review` if COPY is yes. -This tool accepts additional command-line arguments. Refer to the -"SYNOPSIS" and usage information for details. +This tool accepts additional command-line arguments. Refer to the "SYNOPSIS" and usage information for details. ---apdex-threshold +.. option:: --apdex-threshold type: float; default: 1.0 @@ -624,20 +578,20 @@ This tool accepts additional command-line arguments. Refer to the ---ask-pass +.. option:: --ask-pass - Prompt for a password when connecting to MySQL. + Prompt for a password when connecting to |MySQL|. ---attribute-aliases +.. option:: --attribute-aliases type: array; default: db|Schema - List of attribute|alias,etc. + List of attribute / alias, etc. Certain attributes have multiple names, like db and Schema. If an event does - not have the primary attribute, pt-query-digest looks for an alias attribute. + not have the primary attribute, :program:`pt-query-digest` looks for an alias attribute. If it finds an alias, it creates the primary attribute with the alias attribute's value and removes the alias attribute. @@ -648,7 +602,7 @@ This tool accepts additional command-line arguments. Refer to the ---attribute-value-limit +.. option:: --attribute-value-limit type: int; default: 4294967296 @@ -660,7 +614,7 @@ This tool accepts additional command-line arguments. Refer to the ---aux-dsn +.. option:: --aux-dsn type: DSN @@ -679,36 +633,36 @@ This tool accepts additional command-line arguments. Refer to the ---charset +.. option:: --charset short form: -A; type: string - Default character set. If the value is utf8, sets Perl's binmode on - STDOUT to utf8, passes the mysql_enable_utf8 option to DBD::mysql, and - runs SET NAMES UTF8 after connecting to MySQL. Any other value sets - binmode on STDOUT without the utf8 layer, and runs SET NAMES after - connecting to MySQL. + Default character set. If the value is utf8, sets *Perl* 's binmode on + ``STDOUT``to utf8, passes the mysql_enable_utf8 option to ``DBD::mysql``, and + runs SET NAMES UTF8 after connecting to |MySQL|. Any other value sets + binmode on ``STDOUT``without the utf8 layer, and runs SET NAMES after + connecting to |MySQL|. ---check-attributes-limit +.. option:: --check-attributes-limit type: int; default: 1000 Stop checking for new attributes after this many events. - For better speed, pt-query-digest stops checking events for new attributes + For better speed, :program:`pt-query-digest` stops checking events for new attributes after a certain number of events. Any new attributes after this number will be ignored and will not be reported. One special case is new attributes for pre-existing query classes - (see "--group-by" about query classes). New attributes will not be added + (see :option:`--group-by` about query classes). New attributes will not be added to pre-existing query classes even if the attributes are detected before the - "--check-attributes-limit" limit. + :option:`--check-attributes-limit` limit. ---config +.. option:: --config type: Array @@ -717,7 +671,7 @@ This tool accepts additional command-line arguments. Refer to the ---[no]continue-on-error +.. option:: --[no]continue-on-error default: yes @@ -725,32 +679,32 @@ This tool accepts additional command-line arguments. Refer to the ---create-review-history-table +.. option:: --create-review-history-table - Create the "--review-history" table if it does not exist. + Create the :option:`--review-history` table if it does not exist. - This option causes the table specified by "--review-history" to be created + This option causes the table specified by :option:`--review-history` to be created with the default structure shown in the documentation for that option. ---create-review-table +.. option:: --create-review-table - Create the "--review" table if it does not exist. + Create the :option:`--review` table if it does not exist. - This option causes the table specified by "--review" to be created with the + This option causes the table specified by :option:`--review` to be created with the default structure shown in the documentation for that option. ---daemonize +.. option:: --daemonize Fork to the background and detach from the shell. POSIX operating systems only. ---defaults-file +.. option:: --defaults-file short form: -F; type: string @@ -758,11 +712,11 @@ This tool accepts additional command-line arguments. Refer to the ---embedded-attributes +.. option:: --embedded-attributes type: array - Two Perl regex patterns to capture pseudo-attributes embedded in queries. + Two *Perl* regex patterns to capture pseudo-attributes embedded in queries. Embedded attributes might be special attribute-value pairs that you've hidden in comments. The first regex should match the entire set of attributes (in @@ -777,7 +731,7 @@ This tool accepts additional command-line arguments. Refer to the SELECT * from users -- file: /login.php, line: 493; - You might run pt-query-digest with the following option: + You might run :program:`pt-query-digest` with the following option: .. code-block:: perl @@ -809,7 +763,7 @@ This tool accepts additional command-line arguments. Refer to the ---execute +.. option:: --execute type: DSN @@ -821,63 +775,62 @@ This tool accepts additional command-line arguments. Refer to the (from the log) is saved as the Exec_orig_time attribute. If unsuccessful, the callback returns false and terminates the chain. - If the connection fails, pt-query-digest tries to reconnect once per second. + If the connection fails, :program:`pt-query-digest` tries to reconnect once per second. - See also "--mirror" and "--execute-throttle". + See also :option:`--mirror` and :option:`--execute-throttle`. ---execute-throttle +.. option:: --execute-throttle type: array - Throttle values for "--execute". + Throttle values for :option:`--execute`. - By default "--execute" runs without any limitations or concerns for the - amount of time that it takes to execute the events. The "--execute-throttle" - allows you to limit the amount of time spent doing "--execute" relative + By default :option:`--execute` runs without any limitations or concerns for the + amount of time that it takes to execute the events. The :option:`--execute-throttle` + allows you to limit the amount of time spent doing :option:`--execute` relative to the other processes that handle events. This works by marking some events - with a \ ``Skip_exec``\ attribute when "--execute" begins to take too much time. - "--execute" will not execute an event if this attribute is true. This - indirectly decreases the time spent doing "--execute". + with a \ ``Skip_exec``\ attribute when :option:`--execute` begins to take too much time. + :option:`--execute` will not execute an event if this attribute is true. This + indirectly decreases the time spent doing :option:`--execute`. - The "--execute-throttle" option takes at least two comma-separated values: - max allowed "--execute" time as a percentage and a check interval time. An + The :option:`--execute-throttle` option takes at least two comma-separated values: + max allowed :option:`--execute` time as a percentage and a check interval time. An optional third value is a percentage step for increasing and decreasing the probability that an event will be marked \ ``Skip_exec``\ true. 5 (percent) is the default step. - For example: "--execute-throttle" \ ``70,60,10``\ . This will limit - "--execute" to 70% of total event processing time, checked every minute - (60 seconds) and probability stepped up and down by 10%. When "--execute" + For example: :option:`--execute-throttle` \ ``70,60,10``\ . This will limit + :option:`--execute` to 70% of total event processing time, checked every minute + (60 seconds) and probability stepped up and down by 10%. When :option:`--execute` exceeds 70%, the probability that events will be marked \ ``Skip_exec``\ true - increases by 10%. "--execute" time is checked again after another minute. + increases by 10%. :option:`--execute` time is checked again after another minute. If it's still above 70%, then the probability will increase another 10%. Or, if it's dropped below 70%, then the probability will decrease by 10%. ---expected-range +.. option:: --expected-range type: array; default: 5,10 Explain items when there are more or fewer than expected. Defines the number of items expected to be seen in the report given by - "--[no]report", as controlled by "--limit" and "--outliers". If - there are more or fewer items in the report, each one will explain why it was + :option:`--[no]report`, as controlled by :option:`--limit` and :option:`--outliers`. If there are more or fewer items in the report, each one will explain why it was included. ---explain +.. option:: --explain type: DSN Run EXPLAIN for the sample query with this DSN and print results. - This works only when "--group-by" includes fingerprint. It causes - pt-query-digest to run EXPLAIN and include the output into the report. For + This works only when :option:`--group-by` includes fingerprint. It causes + :program:`pt-query-digest` to run EXPLAIN and include the output into the report. For safety, queries that appear to have a subquery that EXPLAIN will execute won't be EXPLAINed. Those are typically "derived table" queries of the form @@ -892,7 +845,7 @@ This tool accepts additional command-line arguments. Refer to the profile. The full format appears at the end of each event report in vertical style - (\ ``\G``\ ) just like MySQL prints it. + (\ ``\G``\ ) just like |MySQL| prints it. The sparklines (see "SPARKLINES") are compact representations of the access type for each table and whether or not "Using temporary" or "Using @@ -932,15 +885,15 @@ This tool accepts additional command-line arguments. Refer to the ---filter +.. option:: --filter type: string - Discard events for which this Perl code doesn't return true. + Discard events for which this *Perl* code doesn't return true. - This option is a string of Perl code or a file containing Perl code that gets + This option is a string of *Perl* code or a file containing *Perl* code that gets compiled into a subroutine with one argument: $event. This is a hashref. - If the given value is a readable file, then pt-query-digest reads the entire + If the given value is a readable file, then :program:`pt-query-digest` reads the entire file and uses its contents as the code. The file should not contain a shebang (#!/usr/bin/perl) line. @@ -979,10 +932,10 @@ This tool accepts additional command-line arguments. Refer to the Then specify \ ``--filter filter.txt``\ to read the code from filter.txt. - If the filter code won't compile, pt-query-digest will die with an error. + If the filter code won't compile, :program:`pt-query-digest` will die with an error. If the filter code does compile, an error may still occur at runtime if the code tries to do something wrong (like pattern match an undefined value). - pt-query-digest does not provide any safeguards so code carefully! + :program:`pt-query-digest` does not provide any safeguards so code carefully! An example filter that discards everything but SELECT statements: @@ -1008,58 +961,58 @@ This tool accepts additional command-line arguments. Refer to the Here are more examples of filter code: - Host/IP matches domain.com + * Host/IP matches domain.com: :: - --filter '($event->{host} || $event->{ip} || "") =~ m/domain.com/' + --filter '($event->{host} || $event->{ip} || "") =~ m/domain.com/' - Sometimes MySQL logs the host where the IP is expected. Therefore, we + Sometimes |MySQL| logs the host where the IP is expected. Therefore, we check both. - User matches john + * User matches john: :: - --filter '($event->{user} || "") =~ m/john/' + --filter '($event->{user} || "") =~ m/john/' - More than 1 warning + * More than 1 warning: :: - --filter '($event->{Warning_count} || 0) > 1' + --filter '($event->{Warning_count} || 0) > 1' - Query does full table scan or full join + * Query does full table scan or full join: :: - --filter '(($event->{Full_scan} || "") eq "Yes") || (($event->{Full_join} || "") eq "Yes")' + --filter '(($event->{Full_scan} || "") eq "Yes") || (($event->{Full_join} || "") eq "Yes")' - Query was not served from query cache + * Query was not served from query cache: :: - --filter '($event->{QC_Hit} || "") eq "No"' + --filter '($event->{QC_Hit} || "") eq "No"' - Query is 1 MB or larger + * Query is 1 MB or larger: :: - --filter '$event->{bytes} >= 1_048_576' + --filter '$event->{bytes} >= 1_048_576' - Since "--filter" allows you to alter \ ``$event``\ , you can use it to do other + Since :option:`--filter` allows you to alter \ ``$event``\ , you can use it to do other things, like create new attributes. See "ATTRIBUTES" for an example. ---fingerprints +.. option:: --fingerprints Add query fingerprints to the standard query analysis report. This is mostly useful for debugging purposes. ---[no]for-explain +.. option:: --[no]for-explain default: yes @@ -1072,7 +1025,7 @@ This tool accepts additional command-line arguments. Refer to the ---group-by +.. option:: --group-by type: Array; default: fingerprint @@ -1084,20 +1037,19 @@ This tool accepts additional command-line arguments. Refer to the \ ``fingerprint``\ , groups similar, abstracted queries into classes; see below and see also "FINGERPRINTS". - A report is printed for each "--group-by" value (unless \ ``--no-report``\ is + A report is printed for each :option:`--group-by` value (unless \ ``--no-report``\ is given). Therefore, \ ``--group-by user,db``\ means "report on queries with the - same user and report on queries with the same db"--it does not mean "report + same user and report on queries with the same db:option:`--it does not mean `report on queries with the same user and db." See also "OUTPUT". Every value must have a corresponding value in the same position in - "--order-by". However, adding values to "--group-by" will automatically - add values to "--order-by", for your convenience. + :option:`--order-by`. However, adding values to :option:`--group-by` will automatically add values to :option:`--order-by`, for your convenience. There are several magical values that cause some extra data mining to happen before the grouping takes place: - fingerprint + * ``fingerprint`` This causes events to be fingerprinted to abstract queries into a canonical form, which is then used to group events together into a class. @@ -1105,7 +1057,7 @@ This tool accepts additional command-line arguments. Refer to the - tables + * ``tables`` This causes events to be inspected for what appear to be tables, and then aggregated by that. Note that a query that contains two or more tables @@ -1114,27 +1066,27 @@ This tool accepts additional command-line arguments. Refer to the - distill + * ``distill`` This is a sort of super-fingerprint that collapses queries down into a suggestion of what they do, such as \ ``INSERT SELECT table1 table2``\ . - If parsing memcached input ("--type" memcached), there are other + If parsing memcached input (:option:`--type` memcached), there are other attributes which you can group by: key_print (see memcached section in "FINGERPRINTS"), cmd, key, res and val (see memcached section in "ATTRIBUTES"). ---help +.. option:: --help Show help and exit. ---host +.. option:: --host short form: -h; type: string @@ -1142,21 +1094,21 @@ This tool accepts additional command-line arguments. Refer to the ---ignore-attributes +.. option:: --ignore-attributes type: array; default: arg, cmd, insert_id, ip, port, Thread_id, timestamp, exptime, flags, key, res, val, server_id, offset, end_log_pos, Xid - Do not aggregate these attributes when auto-detecting "--select". + Do not aggregate these attributes when auto-detecting :option:`--select`. - If you do not specify "--select" then pt-query-digest auto-detects and + If you do not specify :option:`--select` then :program:`pt-query-digest` auto-detects and aggregates every attribute that it finds in the slow log. Some attributes, however, should not be aggregated. This option allows you to specify a list - of attributes to ignore. This only works when no explicit "--select" is + of attributes to ignore. This only works when no explicit :option:`--select` is given. ---inherit-attributes +.. option:: --inherit-attributes type: array; default: db,ts @@ -1169,11 +1121,11 @@ This tool accepts additional command-line arguments. Refer to the Inheritance is usually desirable, but in some cases it might confuse things. If a query inherits a database that it doesn't actually use, then this could - confuse "--execute". + confuse :option:`--execute`. ---interval +.. option:: --interval type: float; default: .1 @@ -1181,21 +1133,21 @@ This tool accepts additional command-line arguments. Refer to the ---iterations +.. option:: --iterations type: int; default: 1 How many times to iterate through the collect-and-report cycle. If 0, iterate - to infinity. Each iteration runs for "--run-time" amount of time. An + to infinity. Each iteration runs for :option:`--run-time` amount of time. An iteration is usually determined by an amount of time and a report is printed - when that amount of time elapses. With "--run-time-mode" \ ``interval``\ , + when that amount of time elapses. With :option:`--run-time-mode` \ ``interval``\ , an interval is instead determined by the interval time you specify with - "--run-time". See "--run-time" and "--run-time-mode" for more + :option:`--run-time". See "--run-time" and "--run-time-mode` for more information. ---limit +.. option:: --limit type: Array; default: 95%:20 @@ -1208,14 +1160,14 @@ This tool accepts additional command-line arguments. Refer to the comes first. The value is actually a comma-separated array of values, one for each item in - "--group-by". If you don't specify a value for any of those items, the + :option:`--group-by`. If you don't specify a value for any of those items, the default is the top 95%. - See also "--outliers". + See also :option:`--outliers`. ---log +.. option:: --log type: string @@ -1223,14 +1175,14 @@ This tool accepts additional command-line arguments. Refer to the ---mirror +.. option:: --mirror type: float How often to check whether connections should be moved, depending on - \ ``read_only``\ . Requires "--processlist" and "--execute". + \ ``read_only``\ . Requires :option:`--processlist" and "--execute`. - This option causes pt-query-digest to check every N seconds whether it is reading + This option causes :program:`pt-query-digest` to check every N seconds whether it is reading from a read-write server and executing against a read-only server, which is a sensible way to set up two servers if you're doing something like master-master replication. The `http://code.google.com/p/mysql-master-master/ `_ master-master @@ -1239,17 +1191,17 @@ This tool accepts additional command-line arguments. Refer to the ---order-by +.. option:: --order-by type: Array; default: Query_time:sum Sort events by this attribute and aggregate function. This is a comma-separated list of order-by expressions, one for each - "--group-by" attribute. The default \ ``Query_time:sum``\ is used for - "--group-by" attributes without explicitly given "--order-by" attributes - (that is, if you specify more "--group-by" attributes than corresponding - "--order-by" attributes). The syntax is \ ``attribute:aggregate``\ . See + :option:`--group-by` attribute. The default \ ``Query_time:sum``\ is used for + :option:`--group-by" attributes without explicitly given "--order-by` attributes + (that is, if you specify more :option:`--group-by` attributes than corresponding + :option:`--order-by` attributes). The syntax is \ ``attribute:aggregate``\ . See "ATTRIBUTES" for valid attributes. Valid aggregates are: @@ -1273,18 +1225,16 @@ This tool accepts additional command-line arguments. Refer to the the same report wherein queries are sorted by the number of times they appear. - When parsing general logs ("--type" \ ``genlog``\ ), the default "--order-by" - becomes \ ``Query_time:cnt``\ . General logs do not report query times so only - the \ ``cnt``\ aggregate makes sense because all query times are zero. + When parsing general logs (:option:`--type` \ ``genlog``\ ), the default :option:`--order-by` becomes \ ``Query_time:cnt``\ . General logs do not report query times so only the \ ``cnt``\ aggregate makes sense because all query times are zero. If you specify an attribute that doesn't exist in the events, then - pt-query-digest falls back to the default \ ``Query_time:sum``\ and prints a notice + :program:`pt-query-digest` falls back to the default \ ``Query_time:sum``\ and prints a notice at the beginning of the report for each query class. You can create attributes - with "--filter" and order by them; see "ATTRIBUTES" for an example. + with :option:`--filter` and order by them; see "ATTRIBUTES" for an example. ---outliers +.. option:: --outliers type: array; default: Query_time:1:10 @@ -1295,7 +1245,7 @@ This tool accepts additional command-line arguments. Refer to the a number that is compared to the attribute's 95th percentile. The third is optional, and is compared to the attribute's cnt aggregate. Queries that pass this specification are added to the report, regardless of any limits you - specified in "--limit". + specified in :option:`--limit`. For example, to report queries whose 95th percentile Query_time is at least 60 seconds and which are seen at least 5 times, use the following argument: @@ -1306,11 +1256,11 @@ This tool accepts additional command-line arguments. Refer to the --outliers Query_time:60:5 - You can specify an --outliers option for each value in "--group-by". + You can specify an --outliers option for each value in :option:`--group-by`. ---password +.. option:: --password short form: -p; type: string @@ -1318,7 +1268,7 @@ This tool accepts additional command-line arguments. Refer to the ---pid +.. option:: --pid type: string @@ -1330,13 +1280,13 @@ This tool accepts additional command-line arguments. Refer to the ---pipeline-profile +.. option:: --pipeline-profile Print a profile of the pipeline processes. ---port +.. option:: --port short form: -P; type: int @@ -1344,18 +1294,18 @@ This tool accepts additional command-line arguments. Refer to the ---print +.. option:: --print - Print log events to STDOUT in standard slow-query-log format. + Print log events to ``STDOUT``in standard slow-query-log format. ---print-iterations +.. option:: --print-iterations - Print the start time for each "--iterations". + Print the start time for each :option:`--iterations`. This option causes a line like the following to be printed at the start - of each "--iterations" report: + of each :option:`--iterations` report: .. code-block:: perl @@ -1363,67 +1313,62 @@ This tool accepts additional command-line arguments. Refer to the # Iteration 2 started at 2009-11-24T14:39:48.345780 - This line will print even if \ ``--no-report``\ is specified. If \ ``--iterations 0``\ - is specified, each iteration number will be \ ``0``\ . + This line will print even if \ ``--no-report``\ is specified. If \ ``--iterations 0``\ is specified, each iteration number will be \ ``0``\ . ---processlist +.. option:: --processlist type: DSN - Poll this DSN's processlist for queries, with "--interval" sleep between. + Poll this DSN's processlist for queries, with :option:`--interval` sleep between. - If the connection fails, pt-query-digest tries to reopen it once per second. See - also "--mirror". + If the connection fails, :program:`pt-query-digest` tries to reopen it once per second. See + also :option:`--mirror`. ---progress +.. option:: --progress type: array; default: time,30 - Print progress reports to STDERR. The value is a comma-separated list with two + Print progress reports to ``STDERR``. The value is a comma-separated list with two parts. The first part can be percentage, time, or iterations; the second part specifies how often an update should be printed, in percentage, seconds, or number of iterations. - ---read-timeout +.. option:: --read-timeout type: time; default: 0 Wait this long for an event from the input; 0 to wait forever. This option sets the maximum time to wait for an event from the input. It - applies to all types of input except "--processlist". If an + applies to all types of input except :option:`--processlist`. If an event is not received after the specified time, the script stops reading the - input and prints its reports. If "--iterations" is 0 or greater than + input and prints its reports. If :option:`--iterations` is 0 or greater than 1, the next iteration will begin, else the script will exit. - This option requires the Perl POSIX module. + This option requires the *Perl* POSIX module. - ---[no]report +.. option:: --[no]report default: yes - Print out reports on the aggregate results from "--group-by". + Print out reports on the aggregate results from :option:`--group-by`. This is the standard slow-log analysis functionality. See "OUTPUT" for the description of what this does and what the results look like. - ---report-all +.. option:: --report-all Include all queries, even if they have already been reviewed. - ---report-format +.. option:: --report-format type: Array; default: rusage,date,hostname,files,header,profile,query_report,prepared @@ -1436,7 +1381,7 @@ This tool accepts additional command-line arguments. Refer to the ============ ====================================================== rusage CPU times and memory usage reported by ps date Current local date and time - hostname Hostname of machine on which pt-query-digest was run + hostname Hostname of machine on which :program:`pt-query-digest` was run files Input files read/parse header Summary of the entire analysis run profile Compact table of queries for an overview of the report @@ -1451,8 +1396,7 @@ This tool accepts additional command-line arguments. Refer to the See "OUTPUT" for more information on the various parts of the query report. - ---report-histogram +.. option:: --report-histogram type: string; default: Query_time @@ -1506,7 +1450,7 @@ This tool accepts additional command-line arguments. Refer to the ---review +.. option:: --review type: DSN @@ -1514,8 +1458,8 @@ This tool accepts additional command-line arguments. Refer to the The argument specifies a table to store all unique query fingerprints in. The table must have at least the following columns. You can add more columns for - your own special purposes, but they won't be used by pt-query-digest. The - following CREATE TABLE definition is also used for "--create-review-table". + your own special purposes, but they won't be used by :program:`pt-query-digest`. The + following CREATE TABLE definition is also used for :option:`--create-review-table`. MAGIC_create_review: @@ -1560,23 +1504,22 @@ This tool accepts additional command-line arguments. Refer to the ---review-history +.. option:: --review-history type: DSN The table in which to store historical values for review trend analysis. - Each time you review queries with "--review", pt-query-digest will save + Each time you review queries with :option:`--review`, :program:`pt-query-digest` will save information into this table so you can see how classes of queries have changed over time. - This DSN inherits unspecified values from "--review". It should mention a - table in which to store statistics about each class of queries. pt-query-digest - verifies the existence of the table, and your privileges to insert, delete and - update on that table. + This DSN inherits unspecified values from :option:`--review`. It should mention a + table in which to store statistics about each class of queries. + +:program:`pt-query-digest` verifies the existence of the table, and your privileges to insert, delete and update on that table. - pt-query-digest then inspects the columns in the table. The table must have at - least the following columns: + :program:`pt-query-digest` then inspects the columns in the table. The table must have at least the following columns: .. code-block:: perl @@ -1601,7 +1544,7 @@ This tool accepts additional command-line arguments. Refer to the the event attribute to store in that column, and the suffix is interpreted as the metric to be stored. For example, a column named Query_time_min will be used to store the minimum Query_time for the class of events. The presence of - this column will also add Query_time to the "--select" list. + this column will also add Query_time to the :option:`--select` list. The table should also have a primary key, but that is up to you, depending on how you want to store the historical data. We suggest adding ts_min and ts_max @@ -1610,7 +1553,7 @@ This tool accepts additional command-line arguments. Refer to the one row per class of queries per day. The default table structure follows. The following MAGIC_create_review_history - table definition is used for "--create-review-history-table": + table definition is used for :option:`--create-review-history-table`: .. code-block:: perl @@ -1665,36 +1608,36 @@ This tool accepts additional command-line arguments. Refer to the Merge_passes_pct_95 FLOAT, Merge_passes_stddev FLOAT, Merge_passes_median FLOAT, - InnoDB_IO_r_ops_min FLOAT, - InnoDB_IO_r_ops_max FLOAT, - InnoDB_IO_r_ops_pct_95 FLOAT, - InnoDB_IO_r_ops_stddev FLOAT, - InnoDB_IO_r_ops_median FLOAT, - InnoDB_IO_r_bytes_min FLOAT, - InnoDB_IO_r_bytes_max FLOAT, - InnoDB_IO_r_bytes_pct_95 FLOAT, - InnoDB_IO_r_bytes_stddev FLOAT, - InnoDB_IO_r_bytes_median FLOAT, - InnoDB_IO_r_wait_min FLOAT, - InnoDB_IO_r_wait_max FLOAT, - InnoDB_IO_r_wait_pct_95 FLOAT, - InnoDB_IO_r_wait_stddev FLOAT, - InnoDB_IO_r_wait_median FLOAT, - InnoDB_rec_lock_wait_min FLOAT, - InnoDB_rec_lock_wait_max FLOAT, - InnoDB_rec_lock_wait_pct_95 FLOAT, - InnoDB_rec_lock_wait_stddev FLOAT, - InnoDB_rec_lock_wait_median FLOAT, - InnoDB_queue_wait_min FLOAT, - InnoDB_queue_wait_max FLOAT, - InnoDB_queue_wait_pct_95 FLOAT, - InnoDB_queue_wait_stddev FLOAT, - InnoDB_queue_wait_median FLOAT, - InnoDB_pages_distinct_min FLOAT, - InnoDB_pages_distinct_max FLOAT, - InnoDB_pages_distinct_pct_95 FLOAT, - InnoDB_pages_distinct_stddev FLOAT, - InnoDB_pages_distinct_median FLOAT, + innodb_IO_r_ops_min FLOAT, + innodb_IO_r_ops_max FLOAT, + innodb_IO_r_ops_pct_95 FLOAT, + innodb_IO_r_ops_stddev FLOAT, + innodb_IO_r_ops_median FLOAT, + innodb_IO_r_bytes_min FLOAT, + innodb_IO_r_bytes_max FLOAT, + innodb_IO_r_bytes_pct_95 FLOAT, + innodb_IO_r_bytes_stddev FLOAT, + innodb_IO_r_bytes_median FLOAT, + innodb_IO_r_wait_min FLOAT, + innodb_IO_r_wait_max FLOAT, + innodb_IO_r_wait_pct_95 FLOAT, + innodb_IO_r_wait_stddev FLOAT, + innodb_IO_r_wait_median FLOAT, + innodb_rec_lock_wait_min FLOAT, + innodb_rec_lock_wait_max FLOAT, + innodb_rec_lock_wait_pct_95 FLOAT, + innodb_rec_lock_wait_stddev FLOAT, + innodb_rec_lock_wait_median FLOAT, + innodb_queue_wait_min FLOAT, + innodb_queue_wait_max FLOAT, + innodb_queue_wait_pct_95 FLOAT, + innodb_queue_wait_stddev FLOAT, + innodb_queue_wait_median FLOAT, + innodb_pages_distinct_min FLOAT, + innodb_pages_distinct_max FLOAT, + innodb_pages_distinct_pct_95 FLOAT, + innodb_pages_distinct_stddev FLOAT, + innodb_pages_distinct_median FLOAT, -- Boolean (Yes/No) attributes. Only the cnt and sum are needed for these. -- cnt is how many times is attribute was recorded and sum is how many of -- those times the value was Yes. Therefore sum/cnt * 100 = % of recorded @@ -1721,66 +1664,64 @@ This tool accepts additional command-line arguments. Refer to the redundant to store this for other attributes. - ---run-time +.. option:: --run-time type: time - How long to run for each "--iterations". The default is to run forever - (you can interrupt with CTRL-C). Because "--iterations" defaults to 1, - if you only specify "--run-time", pt-query-digest runs for that amount of + How long to run for each :option:`--iterations`. The default is to run forever + (you can interrupt with CTRL-C). Because :option:`--iterations` defaults to 1, + if you only specify :option:`--run-time`, :program:`pt-query-digest` runs for that amount of time and then exits. The two options are specified together to do - collect-and-report cycles. For example, specifying "--iterations" \ ``4``\ - "--run-time" \ ``15m``\ with a continuous input (like STDIN or - "--processlist") will cause pt-query-digest to run for 1 hour + collect-and-report cycles. For example, specifying :option:`--iterations` \ ``4``\ + :option:`--run-time` \ ``15m``\ with a continuous input (like ``STDIN``or + :option:`--processlist`) will cause :program:`pt-query-digest` to run for 1 hour (15 minutes x 4), reporting four times, once at each 15 minute interval. ---run-time-mode +.. option:: --run-time-mode type: string; default: clock - Set what the value of "--run-time" operates on. Following are the possible + Set what the value of :option:`--run-time` operates on. Following are the possible values for this option: - clock + * ``clock`` - "--run-time" specifies an amount of real clock time during which the tool - should run for each "--iterations". + :option:`--run-time` specifies an amount of real clock time during which the tool + should run for each :option:`--iterations`. - event + * ``event`` - "--run-time" specifies an amount of log time. Log time is determined by + :option:`--run-time` specifies an amount of log time. Log time is determined by timestamps in the log. The first timestamp seen is remembered, and each timestamp after that is compared to the first to determine how much log time has passed. For example, if the first timestamp seen is \ ``12:00:00``\ and the next is \ ``12:01:30``\ , that is 1 minute and 30 seconds of log time. The tool will read events until the log time is greater than or equal to the specified - "--run-time" value. + :option:`--run-time` value. Since timestamps in logs are not always printed, or not always printed frequently, this mode varies in accuracy. - interval + * ``interval`` - "--run-time" specifies interval boundaries of log time into which events + :option:`--run-time` specifies interval boundaries of log time into which events are divided and reports are generated. This mode is different from the others because it doesn't specify how long to run. The value of - "--run-time" must be an interval that divides evenly into minutes, hours + :option:`--run-time` must be an interval that divides evenly into minutes, hours or days. For example, \ ``5m``\ divides evenly into hours (60/5=12, so 12 5 minutes intervals per hour) but \ ``7m``\ does not (60/7=8.6). Specifying \ ``--run-time-mode interval --run-time 30m --iterations 0``\ is similar to specifying \ ``--run-time-mode clock --run-time 30m --iterations 0``\ . - In the latter case, pt-query-digest will run forever, producing reports every - 30 minutes, but this only works effectively with continuous inputs like - STDIN and the processlist. For fixed inputs, like log files, the former + In the latter case, :program:`pt-query-digest` will run forever, producing reports every 30 minutes, but this only works effectively with continuous inputs like + ``STDIN``and the processlist. For fixed inputs, like log files, the former example produces multiple reports by dividing the log into 30 minutes intervals based on timestamps. @@ -1792,23 +1733,23 @@ This tool accepts additional command-line arguments. Refer to the When a new timestamp exceeds the interval, a report is printed, and the next interval is recalculated based on the new timestamp. - Since "--iterations" is 1 by default, you probably want to specify - a new value else pt-query-digest will only get and report on the first + Since :option:`--iterations` is 1 by default, you probably want to specify + a new value else :program:`pt-query-digest` will only get and report on the first interval from the log since 1 interval = 1 iteration. If you want to - get and report every interval in a log, specify "--iterations" \ ``0``\ . + get and report every interval in a log, specify :option:`--iterations` \ ``0``\ . ---sample +.. option:: --sample type: int Filter out all but the first N occurrences of each query. The queries are - filtered on the first value in "--group-by", so by default, this will filter + filtered on the first value in :option:`--group-by`, so by default, this will filter by query fingerprint. For example, \ ``--sample 2``\ will permit two sample queries - for each fingerprint. Useful in conjunction with "--print" to print out the + for each fingerprint. Useful in conjunction with :option:`--print` to print out the queries. You probably want to set \ ``--no-report``\ to avoid the overhead of aggregating and reporting if you're just using this to print out samples of queries. A complete example: @@ -1816,24 +1757,24 @@ This tool accepts additional command-line arguments. Refer to the .. code-block:: perl - pt-query-digest --sample 2 --no-report --print slow.log + :program:`pt-query-digest` --sample 2 --no-report --print slow.log ---select +.. option:: --select type: Array Compute aggregate statistics for these attributes. - By default pt-query-digest auto-detects, aggregates and prints metrics for + By default :program:`pt-query-digest` auto-detects, aggregates and prints metrics for every query attribute that it finds in the slow query log. This option specifies a list of only the attributes that you want. You can specify an alternative attribute with a colon. For example, \ ``db:Schema``\ uses db if it's available, and Schema if it's not. - Previously, pt-query-digest only aggregated these attributes: + Previously, :program:`pt-query-digest` only aggregated these attributes: .. code-block:: perl @@ -1841,23 +1782,23 @@ This tool accepts additional command-line arguments. Refer to the Query_time,Lock_time,Rows_sent,Rows_examined,user,db:Schema,ts - Attributes specified in the "--review-history" table will always be selected - even if you do not specify "--select". + Attributes specified in the :option:`--review-history` table will always be selected + even if you do not specify :option:`--select`. - See also "--ignore-attributes" and "ATTRIBUTES". + See also :option:`--ignore-attributes" and "ATTRIBUTES`. ---set-vars +.. option:: --set-vars type: string; default: wait_timeout=10000 - Set these MySQL variables. Immediately after connecting to MySQL, this + Set these |MySQL| variables. Immediately after connecting to |MySQL|, this string will be appended to SET and executed. ---shorten +.. option:: --shorten type: int; default: 1024 @@ -1865,7 +1806,7 @@ This tool accepts additional command-line arguments. Refer to the Shortens long statements, replacing the omitted portion with a \ ``/\*... omitted ...\*/``\ comment. This applies only to the output in reports, not to information - stored for "--review" or other places. It prevents a large statement from + stored for :option:`--review` or other places. It prevents a large statement from causing difficulty in a report. The argument is the preferred length of the shortened statement. Not all statements can be shortened, but very large INSERT and similar statements often can; and so can IN() lists, although only the first @@ -1876,13 +1817,13 @@ This tool accepts additional command-line arguments. Refer to the ---show-all +.. option:: --show-all type: Hash Show all values for these attributes. - By default pt-query-digest only shows as many of an attribute's value that + By default :program:`pt-query-digest` only shows as many of an attribute's value that fit on a single line. This option allows you to specify attributes for which all values will be shown (line width is ignored). This only works for attributes with string values like user, host, db, etc. Multiple attributes @@ -1890,7 +1831,7 @@ This tool accepts additional command-line arguments. Refer to the ---since +.. option:: --since type: string @@ -1908,35 +1849,35 @@ This tool accepts additional command-line arguments. Refer to the given); this is like saying "since N[shmd] ago" * Full date with optional hours:minutes:seconds: YYYY-MM-DD [HH:MM::SS] - * Short, MySQL-style date: + * Short, |MySQL|-style date: YYMMDD [HH:MM:SS] - * Any time expression evaluated by MySQL: + * Any time expression evaluated by |MySQL|: CURRENT_DATE - INTERVAL 7 DAY - If you give a MySQL time expression, then you must also specify a DSN - so that pt-query-digest can connect to MySQL to evaluate the expression. If you - specify "--execute", "--explain", "--processlist", "--review" - or "--review-history", then one of these DSNs will be used automatically. - Otherwise, you must specify an "--aux-dsn" or pt-query-digest will die + If you give a |MySQL| time expression, then you must also specify a DSN + so that :program:`pt-query-digest` can connect to |MySQL| to evaluate the expression. If you + specify :option:`--execute", "--explain", "--processlist", "--review` + or :option:`--review-history`, then one of these DSNs will be used automatically. + Otherwise, you must specify an :option:`--aux-dsn` or :program:`pt-query-digest` will die saying that the value is invalid. - The MySQL time expression is wrapped inside a query like + The |MySQL| time expression is wrapped inside a query like "SELECT UNIX_TIMESTAMP()", so be sure that the expression is valid inside this query. For example, do not use UNIX_TIMESTAMP() because UNIX_TIMESTAMP(UNIX_TIMESTAMP()) returns 0. Events are assumed to be in chronological--older events at the beginning of - the log and newer events at the end of the log. "--since" is strict: it + the log and newer events at the end of the log. :option:`--since` is strict: it ignores all queries until one is found that is new enough. Therefore, if the query events are not consistently timestamped, some may be ignored which are actually new enough. - See also "--until". + See also :option:`--until`. ---socket +.. option:: --socket short form: -S; type: string @@ -1944,7 +1885,7 @@ This tool accepts additional command-line arguments. Refer to the ---statistics +.. option:: --statistics Print statistics about internal counters. This option is mostly for development and debugging. The statistics report is printed for each @@ -1978,12 +1919,12 @@ This tool accepts additional command-line arguments. Refer to the an unknown client command, and 22.75% were unknown client data. The other 64.49% were TCP control packets (probably most ACKs). - Since pt-query-digest is complex, you will probably need someone familiar + Since :program:`pt-query-digest` is complex, you will probably need someone familiar with its code to decipher the statistics report. ---table-access +.. option:: --table-access Print a table access report. @@ -2013,39 +1954,39 @@ This tool accepts additional command-line arguments. Refer to the ---tcpdump-errors +.. option:: --tcpdump-errors type: string - Write the tcpdump data to this file on error. If pt-query-digest doesn't + Write the tcpdump data to this file on error. If :program:`pt-query-digest` doesn't parse the stream correctly for some reason, the session's packets since the last query event will be written out to create a usable test case. If this - happens, pt-query-digest will not raise an error; it will just discard the + happens, :program:`pt-query-digest` will not raise an error; it will just discard the session's saved state and permit the tool to continue working. See "tcpdump" for more information about parsing tcpdump output. ---timeline +.. option:: --timeline Show a timeline of events. - This option makes pt-query-digest print another kind of report: a timeline of + This option makes :program:`pt-query-digest` print another kind of report: a timeline of the events. Each query is still grouped and aggregate into classes according to - "--group-by", but then they are printed in chronological order. The timeline + :option:`--group-by`, but then they are printed in chronological order. The timeline report prints out the timestamp, interval, count and value of each classes. If all you want is the timeline report, then specify \ ``--no-report``\ to suppress the default query analysis report. Otherwise, the timeline report will be printed at the end before the response-time profile - (see "--report-format" and "OUTPUT"). + (see :option:`--report-format" and "OUTPUT`). For example, this: .. code-block:: perl - pt-query-digest /path/to/log --group-by distill --timeline + :program:`pt-query-digest` /path/to/log --group-by distill --timeline will print something like: @@ -2063,36 +2004,36 @@ This tool accepts additional command-line arguments. Refer to the ---type +.. option:: --type type: Array The type of input to parse (default slowlog). The permitted types are - binlog + * ``binlog`` Parse a binary log file. - genlog + * ``genlog`` - Parse a MySQL general log file. General logs lack a lot of "ATTRIBUTES", - notably \ ``Query_time``\ . The default "--order-by" for general logs + Parse a |MySQL| general log file. General logs lack a lot of "ATTRIBUTES", + notably \ ``Query_time``\ . The default :option:`--order-by` for general logs changes to \ ``Query_time:cnt``\ . - http + * ``http`` Parse HTTP traffic from tcpdump. - pglog + * ``pglog`` - Parse a log file in PostgreSQL format. The parser will automatically recognize + Parse a log file in *PostgreSQL* format. The parser will automatically recognize logs sent to syslog and transparently parse the syslog format, too. The recommended configuration for logging in your postgresql.conf is as follows. @@ -2124,7 +2065,7 @@ This tool accepts additional command-line arguments. Refer to the Although the suggested format is as shown above, any name=value list will be captured and interpreted by using the first letter of the 'name' part, lowercased, to determine the meaning of the item. The lowercased first letter - is interpreted to mean the same thing as PostgreSQL's built-in %-codes for the + is interpreted to mean the same thing as *PostgreSQL*'s built-in %-codes for the log_line_prefix format string. For example, u means user, so unicorn=fred will be interpreted as user=fred; d means database, so D=john will be interpreted as database=john. The pgfouine-suggested formatting is user=%u and @@ -2138,22 +2079,22 @@ This tool accepts additional command-line arguments. Refer to the - slowlog + * ``slowlog`` - Parse a log file in any variation of MySQL slow-log format. + Parse a log file in any variation of |MySQL| slow-log format. - tcpdump + * ``tcpdump`` - Inspect network packets and decode the MySQL client protocol, extracting queries + Inspect network packets and decode the |MySQL| client protocol, extracting queries and responses from it. - pt-query-digest does not actually watch the network (i.e. it does NOT "sniff + :program:`pt-query-digest` does not actually watch the network (i.e. it does NOT "sniff packets"). Instead, it's just parsing the output of tcpdump. You are - responsible for generating this output; pt-query-digest does not do it for you. - Then you send this to pt-query-digest as you would any log file: as files on the - command line or to STDIN. + responsible for generating this output; :program:`pt-query-digest` does not do it for you. + Then you send this to :program:`pt-query-digest` as you would any log file: as files on the + command line or to ``STDIN``. The parser expects the input to be formatted with the following options: \ ``-x -n -q -tttt``\ . For example, if you want to capture output from your local machine, @@ -2164,7 +2105,7 @@ This tool accepts additional command-line arguments. Refer to the tcpdump -s 65535 -x -nn -q -tttt -i any -c 1000 port 3306 \ > mysql.tcp.txt - pt-query-digest --type tcpdump mysql.tcp.txt + :program:`pt-query-digest` --type tcpdump mysql.tcp.txt The other tcpdump parameters, such as -s, -c, and -i, are up to you. Just make @@ -2185,9 +2126,9 @@ This tool accepts additional command-line arguments. Refer to the tcpdump can't capture traffic on a Unix socket. Read `http://bugs.mysql.com/bug.php?id=31577 `_ if you're confused about this. - Devananda Van Der Veen explained on the MySQL Performance Blog how to capture + Devananda Van Der Veen explained on the |MySQL| Performance Blog how to capture traffic without dropping packets on busy servers. Dropped packets cause - pt-query-digest to miss the response to a request, then see the response to a + :program:`pt-query-digest` to miss the response to a request, then see the response to a later request and assign the wrong execution time to the query. You can change the filter to something like the following to help capture a subset of the queries. (See `http://www.mysqlperformanceblog.com/?p=6092 `_ for details.) @@ -2199,19 +2140,19 @@ This tool accepts additional command-line arguments. Refer to the 'port 3306 and tcp[1] & 7 == 2 and tcp[3] & 7 == 2' - All MySQL servers running on port 3306 are automatically detected in the + All |MySQL| servers running on port 3306 are automatically detected in the tcpdump output. Therefore, if the tcpdump out contains packets from multiple servers on port 3306 (for example, 10.0.0.1:3306, 10.0.0.2:3306, etc.), all packets/queries from all these servers will be analyzed together as if they were one server. - If you're analyzing traffic for a MySQL server that is not running on port - 3306, see "--watch-server". + If you're analyzing traffic for a |MySQL| server that is not running on port + 3306, see :option:`--watch-server`. - Also note that pt-query-digest may fail to report the database for queries + Also note that :program:`pt-query-digest` may fail to report the database for queries when parsing tcpdump output. The database is discovered only in the initial connect events for a new client or when is executed. If the tcpdump - output contains neither of these, then pt-query-digest cannot discover the + output contains neither of these, then :program:`pt-query-digest` cannot discover the database. Server-side prepared statements are supported. SSL-encrypted traffic cannot be @@ -2219,17 +2160,17 @@ This tool accepts additional command-line arguments. Refer to the - memcached + * ``memcached`` Similar to tcpdump, but the expected input is memcached packets - instead of MySQL packets. For example: + instead of |MySQL| packets. For example: .. code-block:: perl tcpdump -i any port 11211 -s 65535 -x -nn -q -tttt \ > memcached.tcp.txt - pt-query-digest --type memcached memcached.tcp.txt + :program:`pt-query-digest` --type memcached memcached.tcp.txt memcached uses port 11211 by default. @@ -2238,7 +2179,7 @@ This tool accepts additional command-line arguments. Refer to the ---until +.. option:: --until type: string @@ -2246,15 +2187,15 @@ This tool accepts additional command-line arguments. Refer to the This option allows you to ignore queries newer than a certain value and parse only those queries which are older than the value. The value can be one of - the same types listed for "--since". + the same types listed for :option:`--since`. - Unlike "--since", "--until" is not strict: all queries are parsed until - one has a timestamp that is equal to or greater than "--until". Then + Unlike :option:`--since", "--until` is not strict: all queries are parsed until + one has a timestamp that is equal to or greater than :option:`--until`. Then all subsequent queries are ignored. ---user +.. option:: --user short form: -u; type: string @@ -2262,7 +2203,7 @@ This tool accepts additional command-line arguments. Refer to the ---variations +.. option:: --variations type: Array @@ -2291,32 +2232,32 @@ This tool accepts additional command-line arguments. Refer to the ---version +.. option:: --version Show version and exit. ---watch-server +.. option:: --watch-server type: string - This option tells pt-query-digest which server IP address and port (like - "10.0.0.1:3306") to watch when parsing tcpdump (for "--type" tcpdump and + This option tells :program:`pt-query-digest` which server IP address and port (like + "10.0.0.1:3306") to watch when parsing tcpdump (for :option:`--type` tcpdump and memcached); all other servers are ignored. If you don't specify it, - pt-query-digest watches all servers by looking for any IP address using port + :program:`pt-query-digest` watches all servers by looking for any IP address using port 3306 or "mysql". If you're watching a server with a non-standard port, this won't work, so you must specify the IP address and port to watch. If you want to watch a mix of servers, some running on standard port 3306 and some running on non-standard ports, you need to create separate tcpdump outputs for the non-standard port servers and then specify this - option for each. At present pt-query-digest cannot auto-detect servers on + option for each. At present :program:`pt-query-digest` cannot auto-detect servers on port 3306 and also be told to watch a server on a non-standard port. ---[no]zero-admin +.. option:: --[no]zero-admin default: yes @@ -2324,7 +2265,7 @@ This tool accepts additional command-line arguments. Refer to the ---[no]zero-bool +.. option:: --[no]zero-bool default: yes @@ -2333,9 +2274,8 @@ This tool accepts additional command-line arguments. Refer to the -*********** DSN OPTIONS -*********** +=========== These DSN options are used to create a DSN. Each option is given like @@ -2345,7 +2285,7 @@ if the value contains whitespace it must be quoted. DSN options are comma-separated. See the percona-toolkit manpage for full details. -\* A + * ``A`` dsn: charset; copy: yes @@ -2353,7 +2293,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* D + * ``D`` dsn: database; copy: yes @@ -2361,7 +2301,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* F + * ``F`` dsn: mysql_read_default_file; copy: yes @@ -2369,7 +2309,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* h + * ``h`` dsn: host; copy: yes @@ -2377,7 +2317,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* p + * ``p`` dsn: password; copy: yes @@ -2385,7 +2325,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* P + * ``p`` dsn: port; copy: yes @@ -2393,7 +2333,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* S + * ``S`` dsn: mysql_socket; copy: yes @@ -2401,13 +2341,13 @@ comma-separated. See the percona-toolkit manpage for full details. -\* t + * ``t`` Table to use as the query review table. -\* u + * ``u`` dsn: user; copy: yes @@ -2416,146 +2356,56 @@ comma-separated. See the percona-toolkit manpage for full details. -*********** ENVIRONMENT -*********** +=========== -The environment variable \ ``PTDEBUG``\ enables verbose debugging output to STDERR. +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-query-digest ... > FILE 2>&1 + PTDEBUG=1 `pt-query-digest ... > FILE 2>&1 Be careful: debugging output is voluminous and can generate several megabytes of output. -******************* SYSTEM REQUIREMENTS -******************* +=================== -You need Perl, DBI, DBD::mysql, and some core packages that ought to be -installed in any reasonably new version of Perl. +You need *Perl* , ``DBI``, ``DBD::mysql``, and some core packages that ought to be +installed in any reasonably new version of *Perl* . -**** BUGS -**** +==== For a list of known bugs, see `http://www.percona.com/bugs/pt-query-digest `_. 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 and Daniel Nichter +*Baron Schwartz* and *Daniel Nichter* -********************* -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 2008-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 -******* +======= - -pt-query-digest 1.0.1 +:program:`pt-query-digest` 1.0.1 diff --git a/docs/user/pt-show-grants.rst b/docs/user/source/pt-show-grants.rst similarity index 55% rename from docs/user/pt-show-grants.rst rename to docs/user/source/pt-show-grants.rst index 23e43cba..d9bfea73 100644 --- a/docs/user/pt-show-grants.rst +++ b/docs/user/source/pt-show-grants.rst @@ -1,30 +1,33 @@ +.. program:: pt-show-grants -############## -pt-show-grants -############## +=========================== + :program:`pt-show-grants` +=========================== .. highlight:: perl -**** NAME -**** +==== + + :program:`pt-show-grants` - Canonicalize and print |MySQL| grants so you can effectively replicate, compare and version-control them. -pt-show-grants - Canonicalize and print MySQL grants so you can effectively replicate, compare and version-control them. - - -******** SYNOPSIS -******** +======== -Usage: pt-show-grants [OPTION...] [DSN] +Usage +----- -pt-show-grants shows grants (user privileges) from a MySQL server. +:: -Examples: + pt-show-grants [OPTION...] [DSN] +:program:`pt-show-grants` shows grants (user privileges) from a |MySQL| server. + +Examples +-------- .. code-block:: perl @@ -34,9 +37,8 @@ Examples: -***** RISKS -***** +===== The following section is included to inform users about the potential risks, @@ -44,8 +46,8 @@ 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-show-grants is read-only by default, and very low-risk. If you specify -"--flush", it will execute \ ``FLUSH PRIVILEGES``\ . +:program:`pt-show-grants` is read-only by default, and very low-risk. If you specify +:option:`--flush`, it will execute \ ``FLUSH PRIVILEGES``\ . At the time of this release, we know of no bugs that could cause serious harm to users. @@ -55,15 +57,13 @@ 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-show-grants `_. -See also "BUGS" for more information on filing bugs and getting help. +See also :ref:`bugs` for more information on filing bugs and getting help. -*********** DESCRIPTION -*********** +=========== - -pt-show-grants extracts, orders, and then prints grants for MySQL user +:program:`pt-show-grants` extracts, orders, and then prints grants for |MySQL| user accounts. Why would you want this? There are several reasons. @@ -74,7 +74,7 @@ into another server. The second use is to place your grants into version control. If you do a daily automated grant dump into version control, you'll get lots of spurious -changesets for grants that don't change, because MySQL prints the actual grants +changesets for grants that don't change, because |MySQL| prints the actual grants out in a seemingly random order. For instance, one day it'll say @@ -99,42 +99,40 @@ you'll get from running SHOW GRANTS, and avoids spurious changesets in version control. Third, if you want to diff grants across servers, it will be hard without -"canonicalizing" them, which pt-show-grants does. The output is fully +"canonicalizing" them, which :program:`pt-show-grants` does. The output is fully diff-able. -With the "--revoke", "--separate" and other options, pt-show-grants -also makes it easy to revoke specific privileges from users. This is tedious +With the :option:`--revoke`, :option:`--separate` and other options, :program:`pt-show-grants` also makes it easy to revoke specific privileges from users. This is tedious otherwise. -******* OPTIONS -******* +======= This tool accepts additional command-line arguments. Refer to the "SYNOPSIS" and usage information for details. ---ask-pass +.. option:: --ask-pass - Prompt for a password when connecting to MySQL. + Prompt for a password when connecting to |MySQL|. ---charset +.. option:: --charset short form: -A; type: string - Default character set. If the value is utf8, sets Perl's binmode on - STDOUT to utf8, passes the mysql_enable_utf8 option to DBD::mysql, and - runs SET NAMES UTF8 after connecting to MySQL. Any other value sets - binmode on STDOUT without the utf8 layer, and runs SET NAMES after - connecting to MySQL. + Default character set. If the value is utf8, sets *Perl* 's binmode on + ``STDOUT`` to utf8, passes the mysql_enable_utf8 option to ``DBD::mysql``, and + runs SET NAMES UTF8 after connecting to |MySQL|. Any other value sets + binmode on ``STDOUT`` without the utf8 layer, and runs SET NAMES after + connecting to |MySQL|. ---config +.. option:: --config type: Array @@ -143,7 +141,7 @@ This tool accepts additional command-line arguments. Refer to the ---database +.. option:: --database short form: -D; type: string @@ -151,7 +149,7 @@ This tool accepts additional command-line arguments. Refer to the ---defaults-file +.. option:: --defaults-file short form: -F; type: string @@ -160,13 +158,13 @@ This tool accepts additional command-line arguments. Refer to the ---drop +.. option:: --drop Add DROP USER before each user in the output. ---flush +.. option:: --flush Add FLUSH PRIVILEGES after output. @@ -174,7 +172,7 @@ This tool accepts additional command-line arguments. Refer to the ---[no]header +.. option:: --[no]header default: yes @@ -185,21 +183,21 @@ This tool accepts additional command-line arguments. Refer to the .. code-block:: perl - -- Grants dumped by pt-show-grants 1.0.19 - -- Dumped from server Localhost via UNIX socket, MySQL 5.0.82-log at 2009-10-26 10:01:04 + -- Grants dumped by :program:`pt-show-grants` 1.0.19 + -- Dumped from server Localhost via UNIX socket, |MySQL| 5.0.82-log at 2009-10-26 10:01:04 - See also "--[no]timestamp". + See also :option:`--[no]timestamp`. ---help +.. option:: --help Show help and exit. ---host +.. option:: --host short form: -h; type: string @@ -207,7 +205,7 @@ This tool accepts additional command-line arguments. Refer to the ---ignore +.. option:: --ignore type: array @@ -215,7 +213,7 @@ This tool accepts additional command-line arguments. Refer to the ---only +.. option:: --only type: array @@ -223,7 +221,7 @@ This tool accepts additional command-line arguments. Refer to the ---password +.. option:: --password short form: -p; type: string @@ -231,7 +229,7 @@ This tool accepts additional command-line arguments. Refer to the ---pid +.. option:: --pid type: string @@ -246,7 +244,7 @@ This tool accepts additional command-line arguments. Refer to the ---port +.. option:: --port short form: -P; type: int @@ -254,32 +252,32 @@ This tool accepts additional command-line arguments. Refer to the ---revoke +.. option:: --revoke Add REVOKE statements for each GRANT statement. ---separate +.. option:: --separate List each GRANT or REVOKE separately. - The default output from MySQL's SHOW GRANTS command lists many privileges on a - single line. With "--flush", places a FLUSH PRIVILEGES after each user, + The default output from |MySQL|'s SHOW GRANTS command lists many privileges on a + single line. With :option:`--flush`, places a FLUSH PRIVILEGES after each user, instead of once at the end of all the output. ---set-vars +.. option:: --set-vars type: string; default: wait_timeout=10000 - Set these MySQL variables. Immediately after connecting to MySQL, this + Set these |MySQL| variables. Immediately after connecting to |MySQL|, this string will be appended to SET and executed. ---socket +.. option:: --socket short form: -S; type: string @@ -287,17 +285,17 @@ This tool accepts additional command-line arguments. Refer to the ---[no]timestamp +.. option:: --[no]timestamp default: yes Add timestamp to the dump header. - See also "--[no]header". + See also :option:`--[no]header`. ---user +.. option:: --user short form: -u; type: string @@ -305,16 +303,15 @@ This tool accepts additional command-line arguments. Refer to the ---version +.. option:: --version Show version and exit. -*********** DSN OPTIONS -*********** +=========== These DSN options are used to create a DSN. Each option is given like @@ -324,7 +321,7 @@ if the value contains whitespace it must be quoted. DSN options are comma-separated. See the percona-toolkit manpage for full details. -\* A + * ``A`` dsn: charset; copy: yes @@ -332,7 +329,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* D + * ``D`` dsn: database; copy: yes @@ -340,7 +337,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* F + * ``F`` dsn: mysql_read_default_file; copy: yes @@ -348,7 +345,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* h + * ``h`` dsn: host; copy: yes @@ -356,7 +353,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* p + * ``p`` dsn: password; copy: yes @@ -364,7 +361,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* P + * ``p`` dsn: port; copy: yes @@ -372,7 +369,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* S + * ``S`` dsn: mysql_socket; copy: yes @@ -380,7 +377,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* u + * ``u`` dsn: user; copy: yes @@ -389,146 +386,54 @@ comma-separated. See the percona-toolkit manpage for full details. -*********** ENVIRONMENT -*********** +=========== -The environment variable \ ``PTDEBUG``\ enables verbose debugging output to STDERR. +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-show-grants ... > FILE 2>&1 + PTDEBUG=1 :program:`pt-show-grants` ... > FILE 2>&1 Be careful: debugging output is voluminous and can generate several megabytes of output. -******************* SYSTEM REQUIREMENTS -******************* +=================== -You need Perl, DBI, DBD::mysql, and some core packages that ought to be -installed in any reasonably new version of Perl. +You need *Perl* , ``DBI``, ``DBD::mysql``, and some core packages that ought to be +installed in any reasonably new version of *Perl* . -**** BUGS -**** +==== For a list of known bugs, see `http://www.percona.com/bugs/pt-show-grants `_. 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* -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 2007-2011 Baron Schwartz, 2011 Percona Inc. +This program is copyright 2007-2011 *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 -******* +======= - -pt-show-grants 1.0.1 +:program:`pt-show-grants` 1.0.1 diff --git a/docs/user/source/pt-sift.rst b/docs/user/source/pt-sift.rst new file mode 100644 index 00000000..9e454c4f --- /dev/null +++ b/docs/user/source/pt-sift.rst @@ -0,0 +1,181 @@ +.. program:: pt-sift + +==================== + :program:`pt-sift` +==================== + +.. highlight:: perl + + +NAME +==== + + :program:`pt-sift` - Browses files created by pt-collect. + + +SYNOPSIS +======== + + +Usage +----- + +:: + + pt-sift FILE|PREFIX|DIRECTORY + +:program:`pt-sift` browses the files created by :program:`pt-collect`. If you specify a +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. + :program:`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 :ref:`bugs` for more information on filing bugs and getting help. + + +DESCRIPTION +=========== + + :program:`pt-sift` downloads other tools that it might need, such as pt-diskstats, +and then makes a list of the unique timestamp prefixes of all the files in +the directory, as written by the pt-collect tool. If the user specified +a timestamp on the command line, then it begins with that sample of data; +otherwise it begins by showing a list of the timestamps and prompting for +a selection. Thereafter, it displays a summary of the selected sample, and +the user can navigate and inspect with keystrokes. The keystroke commands +you can use are as follows: + + + * ``d`` + + Sets the action to start the pt-diskstats tool on the sample's disk + performance statistics. + + + + * ``i`` + + Sets the action to view the first INNODB STATUS sample in less. + + + + * ``m`` + + Displays the first 4 samples of SHOW STATUS counters side by side with the + pt-mext tool. + + + + * ``n`` + + Summarizes the first sample of netstat data in two ways: by originating host, + and by connection state. + + + + * ``j`` + + Select the next timestamp as the active sample. + + + + * ``k`` + + Select the previous timestamp as the active sample. + + + + * ``q`` + + Quit the program. + + + + * ``1`` + + Sets the action for each sample to the default, which is to view a summary + of the sample. + + + + * ``0`` + + Sets the action to just list the files in the sample. + + + + * ``*`` + + Sets the action to view all of the samples's files in the less program. + + + + +OPTIONS +======= + + +This tool does not have any command-line options. + + +ENVIRONMENT +=========== + + +This tool does not use any environment variables. + + +SYSTEM REQUIREMENTS +=================== + + +This tool requires Bash v3 and the following programs: pt-diskstats, pt-pmp, +pt-mext, and align (from Aspersa). If these programs are not in your PATH, +they will be fetched from the Internet if curl is available. + + +BUGS +==== + + +For a list of known bugs, see `http://www.percona.com/bugs/pt-sift `_. + +Please report bugs at `https://bugs.launchpad.net/percona-toolkit `_. + + +AUTHORS +======= + +*Baron Schwartz* + + +COPYRIGHT, LICENSE, AND WARRANTY +================================ + + +This program is copyright 2010-2011 *Baron Schwartz*, 2011 Percona Inc. +Feedback and improvements are welcome. + + +VERSION +======= + +:program:`pt-sift` 1.0.1 + diff --git a/docs/user/pt-slave-delay.rst b/docs/user/source/pt-slave-delay.rst similarity index 53% rename from docs/user/pt-slave-delay.rst rename to docs/user/source/pt-slave-delay.rst index d272fbb0..d3d7548a 100644 --- a/docs/user/pt-slave-delay.rst +++ b/docs/user/source/pt-slave-delay.rst @@ -1,27 +1,30 @@ +.. program:: pt-slave-delay -############## -pt-slave-delay -############## +=========================== + :program:`pt-slave-delay` +=========================== .. highlight:: perl -**** NAME -**** +==== + + :program:`pt-slave-delay` - Make a |MySQL| slave server lag behind its master. -pt-slave-delay - Make a MySQL slave server lag behind its master. - - -******** SYNOPSIS -******** +======== -Usage: pt-slave-delay [OPTION...] SLAVE-HOST [MASTER-HOST] +Usage +----- -pt-slave-delay starts and stops a slave server as needed to make it lag +:: + + pt-slave-delay [OPTION...] SLAVE-HOST [MASTER-HOST] + +:program:`pt-slave-delay` starts and stops a slave server as needed to make it lag behind the master. The SLAVE-HOST and MASTER-HOST use DSN syntax, and values are copied from the SLAVE-HOST to the MASTER-HOST if omitted. @@ -30,13 +33,12 @@ To hold slavehost one minute behind its master for ten minutes: .. code-block:: perl - pt-slave-delay --delay 1m --interval 15s --run-time 10m slavehost + pt-slave-delay --delay 1m --interval 15s --run-time 10m slavehost -***** RISKS -***** +===== The following section is included to inform users about the potential risks, @@ -44,7 +46,7 @@ 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-slave-delay is generally very low-risk. It simply starts and stops the +:program:`pt-slave-delay` is generally very low-risk. It simply starts and stops the replication SQL thread. This might cause monitoring systems to think the slave is having trouble. @@ -56,92 +58,85 @@ 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-slave-delay `_. -See also "BUGS" for more information on filing bugs and getting help. +See also :ref:`bugs` for more information on filing bugs and getting help. -*********** DESCRIPTION -*********** +=========== -\ ``pt-slave-delay``\ watches a slave and starts and stops its replication SQL +:program:`pt-slave-delay` watches a slave and starts and stops its replication SQL thread as necessary to hold it at least as far behind the master as you request. In practice, it will typically cause the slave to lag between -"--delay" and "--delay"+"--interval" behind the master. +:option:`--delay` and :option:`--delay` + :option:`--interval` behind the master. It bases the delay on binlog positions in the slave's relay logs by default, so there is no need to connect to the master. This works well if the IO thread doesn't lag the master much, which is typical in most replication setups; the IO thread lag is usually milliseconds on a fast network. If your -IO thread's lag is too large for your purposes, \ ``pt-slave-delay``\ can also +IO thread's lag is too large for your purposes, :program:`pt-slave-delay` can also connect to the master for information about binlog positions. If the slave's I/O thread reports that it is waiting for the SQL thread to -free some relay log space, \ ``pt-slave-delay``\ will automatically connect to the -master to find binary log positions. If "--ask-pass" and "--daemonize" +free some relay log space, :program:`pt-slave-delay` will automatically connect to the +master to find binary log positions. If :option:`--ask-pass` and :option:`--daemonize` are given, it is possible that this could cause it to ask for a password while daemonized. In this case, it exits. Therefore, if you think your slave might encounter this condition, you should be sure to either specify -"--use-master" explicitly when daemonizing, or don't specify "--ask-pass". +:option:`--use-master` explicitly when daemonizing, or don't specify :option:`--ask-pass`. The SLAVE-HOST and optional MASTER-HOST are both DSNs. See "DSN OPTIONS". Missing MASTER-HOST values are filled in with values from SLAVE-HOST, so you -don't need to specify them in both places. \ ``pt-slave-delay``\ reads all normal -MySQL option files, such as ~/.my.cnf, so you may not need to specify username, -password and other common options at all. +don't need to specify them in both places. :program:`pt-slave-delay` reads all normal +|MySQL| option files, such as :file:`~/.my.cnf`, so you may not need to specify username, password and other common options at all. -\ ``pt-slave-delay``\ tries to exit gracefully by trapping signals such as Ctrl-C. -You cannot bypass "--[no]continue" with a trappable signal. +:program:`pt-slave-delay` tries to exit gracefully by trapping signals such as ``Ctrl-C``. +You cannot bypass :option:`--[no]continue` with a trappable signal. -********** PRIVILEGES -********** +========== + +:program:`pt-slave-delay` requires the following privileges: ``PROCESS``, ``REPLICATION CLIENT``, and ``SUPER``. -pt-slave-delay requires the following privileges: PROCESS, REPLICATION CLIENT, -and SUPER. - - -****** OUTPUT -****** +====== -If you specify "--quiet", there is no output. Otherwise, the normal output +If you specify :option:`--quiet`, there is no output. Otherwise, the normal output is a status message consisting of a timestamp and information about what -\ ``pt-slave-delay``\ is doing: starting the slave, stopping the slave, or just +:program:`pt-slave-delay` is doing: starting the slave, stopping the slave, or just observing. -******* OPTIONS -******* +======= This tool accepts additional command-line arguments. Refer to the "SYNOPSIS" and usage information for details. ---ask-pass +.. option:: --ask-pass - Prompt for a password when connecting to MySQL. + Prompt for a password when connecting to |MySQL|. ---charset +.. option:: --charset short form: -A; type: string - Default character set. If the value is utf8, sets Perl's binmode on - STDOUT to utf8, passes the mysql_enable_utf8 option to DBD::mysql, and - runs SET NAMES UTF8 after connecting to MySQL. Any other value sets - binmode on STDOUT without the utf8 layer, and runs SET NAMES after - connecting to MySQL. + Default character set. If the value is utf8, sets *Perl* 's binmode on + ``STDOUT`` to utf8, passes the mysql_enable_utf8 option to ``DBD::mysql``, and + runs SET NAMES UTF8 after connecting to |MySQL|. Any other value sets + binmode on ``STDOUT`` without the utf8 layer, and runs SET NAMES after + connecting to |MySQL|. ---config +.. option:: --config type: Array @@ -150,25 +145,25 @@ This tool accepts additional command-line arguments. Refer to the ---[no]continue +.. option:: --[no]continue default: yes Continue replication normally on exit. After exiting, restart the slave's SQL thread with no UNTIL condition, so it will run as usual and catch up to the master. This is enabled by default and works even if you terminate - \ ``pt-slave-delay``\ with Control-C. + :program:`pt-slave-delay` with ``Control-C``. ---daemonize +.. option:: --daemonize Fork to the background and detach from the shell. POSIX operating systems only. ---defaults-file +.. option:: --defaults-file short form: -F; type: string @@ -177,7 +172,7 @@ This tool accepts additional command-line arguments. Refer to the ---delay +.. option:: --delay type: time; default: 1h @@ -185,13 +180,13 @@ This tool accepts additional command-line arguments. Refer to the ---help +.. option:: --help Show help and exit. ---host +.. option:: --host short form: -h; type: string @@ -199,16 +194,16 @@ This tool accepts additional command-line arguments. Refer to the ---interval +.. option:: --interval type: time; default: 1m - How frequently \ ``pt-slave-delay``\ should check whether the slave needs to be + How frequently :program:`pt-slave-delay` should check whether the slave needs to be started or stopped. ---log +.. option:: --log type: string @@ -216,7 +211,7 @@ This tool accepts additional command-line arguments. Refer to the ---password +.. option:: --password short form: -p; type: string @@ -224,7 +219,7 @@ This tool accepts additional command-line arguments. Refer to the ---pid +.. option:: --pid type: string @@ -236,7 +231,7 @@ This tool accepts additional command-line arguments. Refer to the ---port +.. option:: --port short form: -P; type: int @@ -244,7 +239,7 @@ This tool accepts additional command-line arguments. Refer to the ---quiet +.. option:: --quiet short form: -q @@ -252,25 +247,25 @@ This tool accepts additional command-line arguments. Refer to the ---run-time +.. option:: --run-time type: time - How long \ ``pt-slave-delay``\ should run before exiting. The default is to run + How long :program:`pt-slave-delay` should run before exiting. The default is to run forever. ---set-vars +.. option:: --set-vars type: string; default: wait_timeout=10000 - Set these MySQL variables. Immediately after connecting to MySQL, this string + Set these |MySQL| variables. Immediately after connecting to |MySQL|, this string will be appended to SET and executed. ---socket +.. option:: --socket short form: -S; type: string @@ -278,40 +273,35 @@ This tool accepts additional command-line arguments. Refer to the ---use-master +.. option:: --use-master Get binlog positions from master, not slave. Don't trust the binlog positions in the slave's relay log. Connect to the master and get binlog positions instead. If you specify this option without giving a MASTER-HOST on the command - line, \ ``pt-slave-delay``\ examines the slave's SHOW SLAVE STATUS to determine the + line, :program:`pt-slave-delay` examines the slave's SHOW SLAVE STATUS to determine the hostname and port for connecting to the master. - \ ``pt-slave-delay``\ uses only the MASTER_HOST and MASTER_PORT values from SHOW + :program:`pt-slave-delay` uses only the MASTER_HOST and MASTER_PORT values from SHOW SLAVE STATUS for the master connection. It does not use the MASTER_USER value. If you want to specify a different username for the master than the one you use to connect to the slave, you should specify the MASTER-HOST option explicitly on the command line. - ---user +.. option:: --user short form: -u; type: string User for login if not current user. - ---version +.. option:: --version Show version and exit. - - -*********** DSN OPTIONS -*********** +=========== These DSN options are used to create a DSN. Each option is given like @@ -321,7 +311,7 @@ if the value contains whitespace it must be quoted. DSN options are comma-separated. See the percona-toolkit manpage for full details. -\* A + * ``A`` dsn: charset; copy: yes @@ -329,7 +319,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* D + * ``D`` dsn: database; copy: yes @@ -337,7 +327,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* F + * ``F`` dsn: mysql_read_default_file; copy: yes @@ -345,7 +335,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* h + * ``h`` dsn: host; copy: yes @@ -353,7 +343,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* p + * ``p`` dsn: password; copy: yes @@ -361,7 +351,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* P + * ``p`` dsn: port; copy: yes @@ -369,7 +359,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* S + * ``S`` dsn: mysql_socket; copy: yes @@ -377,7 +367,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* u + * ``u`` dsn: user; copy: yes @@ -386,12 +376,11 @@ comma-separated. See the percona-toolkit manpage for full details. -*********** ENVIRONMENT -*********** +=========== -The environment variable \ ``PTDEBUG``\ enables verbose debugging output to STDERR. +The environment variable \ ``PTDEBUG``\ enables verbose debugging output to ``STDERR``. To enable debugging and capture all output to a file, run the tool like: @@ -404,129 +393,39 @@ Be careful: debugging output is voluminous and can generate several megabytes of output. -******************* SYSTEM REQUIREMENTS -******************* +=================== -You need Perl, DBI, DBD::mysql, and some core packages that ought to be -installed in any reasonably new version of Perl. +You need *Perl* , ``DBI``, ``DBD::mysql``, and some core packages that ought to be +installed in any reasonably new version of *Perl* . -**** BUGS -**** +==== For a list of known bugs, see `http://www.percona.com/bugs/pt-slave-delay `_. 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 -******* +======= -Sergey Zhuravlev and Baron Schwartz +*Sergey Zhuravlev* and *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 2007-2011 Sergey Zhuravle and Baron Schwartz, +This program is copyright 2007-2011 Sergey Zhuravle and *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 -******* +======= - -pt-slave-delay 1.0.1 +:program:`pt-slave-delay` 1.0.1 diff --git a/docs/user/pt-slave-find.rst b/docs/user/source/pt-slave-find.rst similarity index 61% rename from docs/user/pt-slave-find.rst rename to docs/user/source/pt-slave-find.rst index c8e53906..4885afae 100644 --- a/docs/user/pt-slave-find.rst +++ b/docs/user/source/pt-slave-find.rst @@ -1,30 +1,33 @@ +.. program:: pt-slave-find -############# -pt-slave-find -############# +========================== + :program:`pt-slave-find` +========================== .. highlight:: perl -**** NAME -**** +==== + + :program:`pt-slave-find` - Find and print replication hierarchy tree of |MySQL| slaves. -pt-slave-find - Find and print replication hierarchy tree of MySQL slaves. - - -******** SYNOPSIS -******** +======== -Usage: pt-slave-find [OPTION...] MASTER-HOST +Usage +----- -pt-slave-find finds and prints a hierarchy tree of MySQL slaves. +:: -Examples: + pt-slave-find [OPTION...] MASTER-HOST +:program:`pt-slave-find` finds and prints a hierarchy tree of |MySQL| slaves. + +Examples +-------- .. code-block:: perl @@ -32,9 +35,8 @@ Examples: -***** RISKS -***** +===== The following section is included to inform users about the potential risks, @@ -42,7 +44,7 @@ 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-slave-find is read-only and very low-risk. +:program:`pt-slave-find` is read-only and very low-risk. At the time of this release, we know of no bugs that could cause serious harm to users. @@ -52,22 +54,19 @@ 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-slave-find `_. -See also "BUGS" for more information on filing bugs and getting help. +See also :ref:`bugs` for more information on filing bugs and getting help. -*********** DESCRIPTION -*********** +=========== - -pt-slave-find connects to a MySQL replication master and finds its slaves. +:program:`pt-slave-find` connects to a |MySQL| replication master and finds its slaves. Currently the only thing it can do is print a tree-like view of the replication hierarchy. The master host can be specified using one of two methods. The first method is to use the standard connection-related command line options: -"--defaults-file", "--password", "--host", "--port", "--socket" -or "--user". +:option:`--defaults-file`, :option:`--password`, :option:`--host`, :option:`--port`, :option:`--socket` or :option:`--user`. The second method to specify the master host is a DSN. A DSN is a special syntax that can be either just a hostname (like \ ``server.domain.com``\ or @@ -86,48 +85,45 @@ syntax that can be either just a hostname (like \ ``server.domain.com``\ or F Only read default options from the given file -\ ``pt-slave-find``\ reads all normal MySQL option files, such as ~/.my.cnf, so -you may not need to specify username, password and other common options at all. +:program:`pt-slave-find` reads all normal |MySQL| option files, such as :option:`~/.my.cnf`, so you may not need to specify username, password and other common options at all. -*********** EXIT STATUS -*********** +=========== An exit status of 0 (sometimes also called a return value or return code) indicates success. Any other value represents the exit status of -the Perl process itself. +the *Perl* process itself. -******* OPTIONS -******* +======= This tool accepts additional command-line arguments. Refer to the "SYNOPSIS" and usage information for details. ---ask-pass +.. option:: --ask-pass - Prompt for a password when connecting to MySQL. + Prompt for a password when connecting to |MySQL|. ---charset +.. option:: --charset short form: -A; type: string - Default character set. If the value is utf8, sets Perl's binmode on - STDOUT to utf8, passes the mysql_enable_utf8 option to DBD::mysql, and - runs SET NAMES UTF8 after connecting to MySQL. Any other value sets - binmode on STDOUT without the utf8 layer, and runs SET NAMES after - connecting to MySQL. + Default character set. If the value is utf8, sets *Perl* 's binmode on + ``STDOUT`` to utf8, passes the mysql_enable_utf8 option to ``DBD::mysql``, and + runs SET NAMES UTF8 after connecting to |MySQL|. Any other value sets + binmode on ``STDOUT`` without the utf8 layer, and runs SET NAMES after + connecting to |MySQL|. ---config +.. option:: --config type: Array @@ -136,7 +132,7 @@ This tool accepts additional command-line arguments. Refer to the ---database +.. option:: --database type: string; short form: -D @@ -144,7 +140,7 @@ This tool accepts additional command-line arguments. Refer to the ---defaults-file +.. option:: --defaults-file short form: -F; type: string @@ -153,13 +149,13 @@ This tool accepts additional command-line arguments. Refer to the ---help +.. option:: --help Show help and exit. ---host +.. option:: --host short form: -h; type: string @@ -167,7 +163,7 @@ This tool accepts additional command-line arguments. Refer to the ---password +.. option:: --password short form: -p; type: string @@ -175,7 +171,7 @@ This tool accepts additional command-line arguments. Refer to the ---pid +.. option:: --pid type: string @@ -190,7 +186,7 @@ This tool accepts additional command-line arguments. Refer to the ---port +.. option:: --port short form: -P; type: int @@ -198,17 +194,17 @@ This tool accepts additional command-line arguments. Refer to the ---recurse +.. option:: --recurse type: int Number of levels to recurse in the hierarchy. Default is infinite. - See "--recursion-method". + See :option:`--recursion-method`. ---recursion-method +.. option:: --recursion-method type: string @@ -227,13 +223,13 @@ This tool accepts additional command-line arguments. Refer to the The processlist method is preferred because SHOW SLAVE HOSTS is not reliable. However, the hosts method is required if the server uses a non-standard - port (not 3306). Usually pt-slave-find does the right thing and finds + port (not 3306). Usually :program:`pt-slave-find` does the right thing and finds the slaves, but you may give a preferred method and it will be used first. If it doesn't find any slaves, the other methods will be tried. ---report-format +.. option:: --report-format type: string; default: summary @@ -241,7 +237,7 @@ This tool accepts additional command-line arguments. Refer to the one of the following: - \* hostname + * ``hostname`` Print just the hostname name of the slaves. It looks like: @@ -255,7 +251,7 @@ This tool accepts additional command-line arguments. Refer to the - \* summary + * ``summary`` Print a summary of each slave's settings. This report shows more information about each slave, like: @@ -289,16 +285,16 @@ This tool accepts additional command-line arguments. Refer to the ---set-vars +.. option:: --set-vars type: string; default: wait_timeout=10000 - Set these MySQL variables. Immediately after connecting to MySQL, this + Set these |MySQL| variables. Immediately after connecting to |MySQL|, this string will be appended to SET and executed. ---socket +.. option:: --socket short form: -S; type: string @@ -306,7 +302,7 @@ This tool accepts additional command-line arguments. Refer to the ---user +.. option:: --user short form: -u; type: string @@ -314,16 +310,15 @@ This tool accepts additional command-line arguments. Refer to the ---version +.. option:: --version Show version and exit. -*********** DSN OPTIONS -*********** +=========== These DSN options are used to create a DSN. Each option is given like @@ -333,7 +328,7 @@ if the value contains whitespace it must be quoted. DSN options are comma-separated. See the percona-toolkit manpage for full details. -\* A + * ``A`` dsn: charset; copy: yes @@ -341,7 +336,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* D + * ``D`` dsn: database; copy: yes @@ -349,7 +344,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* F + * ``F`` dsn: mysql_read_default_file; copy: yes @@ -357,7 +352,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* h + * ``h`` dsn: host; copy: yes @@ -365,7 +360,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* p + * ``p`` dsn: password; copy: yes @@ -373,7 +368,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* P + * ``p`` dsn: port; copy: yes @@ -381,7 +376,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* S + * ``S`` dsn: mysql_socket; copy: yes @@ -389,7 +384,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* u + * ``u`` dsn: user; copy: yes @@ -398,146 +393,56 @@ comma-separated. See the percona-toolkit manpage for full details. -*********** ENVIRONMENT -*********** +=========== -The environment variable \ ``PTDEBUG``\ enables verbose debugging output to STDERR. +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-slave-find ... > FILE 2>&1 + PTDEBUG=1 :program:`pt-slave-find` ... > FILE 2>&1 Be careful: debugging output is voluminous and can generate several megabytes of output. -******************* SYSTEM REQUIREMENTS -******************* +=================== -You need Perl, DBI, DBD::mysql, and some core packages that ought to be -installed in any reasonably new version of Perl. +You need *Perl* , ``DBI``, ``DBD::mysql``, and some core packages that ought to be +installed in any reasonably new version of *Perl* . -**** BUGS -**** +==== For a list of known bugs, see `http://www.percona.com/bugs/pt-slave-find `_. 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 and Daniel Nichter +*Baron Schwartz* and *Daniel Nichter* -********************* -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 2007-2011 Baron Schwartz, 2011 Percona Inc. +This program is copyright 2007-2011 *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 -******* +======= - -pt-slave-find 1.0.1 +:program:`pt-slave-find` 1.0.1 diff --git a/docs/user/pt-slave-restart.rst b/docs/user/source/pt-slave-restart.rst similarity index 52% rename from docs/user/pt-slave-restart.rst rename to docs/user/source/pt-slave-restart.rst index b8c18884..f6a75202 100644 --- a/docs/user/pt-slave-restart.rst +++ b/docs/user/source/pt-slave-restart.rst @@ -1,33 +1,35 @@ +.. program:: pt-slave-restart -################ -pt-slave-restart -################ +============================= + :program:`pt-slave-restart` +============================= .. highlight:: perl -**** NAME -**** +==== + + :program:`pt-slave-restart` - Watch and restart |MySQL| replication after errors. -pt-slave-restart - Watch and restart MySQL replication after errors. - - -******** SYNOPSIS -******** +======== -Usage: pt-slave-restart [OPTION...] [DSN] +Usage +----- -pt-slave-restart watches one or more MySQL replication slaves for +:: + + pt-slave-restart [OPTION...] [DSN] + +:program:`pt-slave-restart` watches one or more |MySQL| replication slaves for errors, and tries to restart replication if it stops. -***** RISKS -***** +===== The following section is included to inform users about the potential risks, @@ -35,7 +37,7 @@ 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-slave-restart is a brute-force way to try to keep a slave server running when +:program:`pt-slave-restart` is a brute-force way to try to keep a slave server running when it is having problems with replication. Don't be too hasty to use it unless you need to. If you use this tool carelessly, you might miss the chance to really solve the slave server's problems. @@ -48,152 +50,120 @@ 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-slave-restart `_. -See also "BUGS" for more information on filing bugs and getting help. +See also :ref:`bugs` for more information on filing bugs and getting help. -*********** DESCRIPTION -*********** +=========== - -pt-slave-restart watches one or more MySQL replication slaves and tries to skip -statements that cause errors. It polls slaves intelligently with an +:program:`pt-slave-restart` watches one or more |MySQL| replication slaves and tries to skip statements that cause errors. It polls slaves intelligently with an exponentially varying sleep time. You can specify errors to skip and run the slaves until a certain binlog position. Note: it has come to my attention that Yahoo! had or has an internal tool called fix_repl, described to me by a past Yahoo! employee and mentioned in -the first edition of High Performance MySQL. Apparently this tool does the +the first edition of *High Performance MySQL*. Apparently this tool does the same thing. Make no mistake, though: this is not a way to "fix replication." In fact I would not even encourage its use on a regular basis; I use it only when I have an error I know I just need to skip past. -****** OUTPUT -****** +====== -If you specify "--verbose", pt-slave-restart prints a line every time it sees -the slave has an error. See "--verbose" for details. +If you specify :option:`--verbose`, :program:`pt-slave-restart` prints a line every time it sees +the slave has an error. See :option:`--verbose` for details. -***** SLEEP -***** +===== - -pt-slave-restart sleeps intelligently between polling the slave. The current + :program:`pt-slave-restart` sleeps intelligently between polling the slave. The current sleep time varies. -\* - - The initial sleep time is given by "--sleep". - + * The initial sleep time is given by :option:`--sleep`. + * If it checks and finds an error, it halves the previous sleep time. -\* - - If it checks and finds an error, it halves the previous sleep time. + * If it finds no error, it doubles the previous sleep time. + * The sleep time is bounded below by :option:`--min-sleep` and above by + :option:`--max-sleep`. - -\* - - If it finds no error, it doubles the previous sleep time. - - - -\* - - The sleep time is bounded below by "--min-sleep" and above by - "--max-sleep". - - - -\* - - Immediately after finding an error, pt-slave-restart assumes another error is - very likely to happen next, so it sleeps the current sleep time or the initial + * Immediately after finding an error, :program:`pt-slave-restart` assumes another error is very likely to happen next, so it sleeps the current sleep time or the initial sleep time, whichever is less. - - -*********** EXIT STATUS -*********** +=========== An exit status of 0 (sometimes also called a return value or return code) -indicates success. Any other value represents the exit status of the Perl +indicates success. Any other value represents the exit status of the *Perl* process itself, or of the last forked process that exited if there were multiple servers to monitor. -************* COMPATIBILITY -************* +============= - -pt-slave-restart should work on many versions of MySQL. Lettercase of many -output columns from SHOW SLAVE STATUS has changed over time, so it treats them +:program:`pt-slave-restart` should work on many versions of |MySQL|. Lettercase of many output columns from SHOW SLAVE STATUS has changed over time, so it treats them all as lowercase. -******* OPTIONS -******* +======= This tool accepts additional command-line arguments. Refer to the "SYNOPSIS" and usage information for details. ---always +.. option:: --always Start slaves even when there is no error. With this option enabled, - pt-slave-restart will not let you stop the slave manually if you want to! + :program:`pt-slave-restart` will not let you stop the slave manually if you want to! ---ask-pass +.. option:: --ask-pass - Prompt for a password when connecting to MySQL. + Prompt for a password when connecting to |MySQL|. ---charset +.. option:: --charset short form: -A; type: string - Default character set. If the value is utf8, sets Perl's binmode on - STDOUT to utf8, passes the mysql_enable_utf8 option to DBD::mysql, and - runs SET NAMES UTF8 after connecting to MySQL. Any other value sets - binmode on STDOUT without the utf8 layer, and runs SET NAMES after - connecting to MySQL. + Default character set. If the value is utf8, sets *Perl* 's binmode on + ``STDOUT`` to utf8, passes the mysql_enable_utf8 option to ``DBD::mysql``, and + runs SET NAMES UTF8 after connecting to |MySQL|. Any other value sets + binmode on ``STDOUT`` without the utf8 layer, and runs SET NAMES after + connecting to |MySQL|. ---[no]check-relay-log +.. option:: --[no]check-relay-log default: yes Check the last relay log file and position before checking for slave errors. - By default pt-slave-restart will not doing anything (it will just sleep) + By default :program:`pt-slave-restart` will not doing anything (it will just sleep) if neither the relay log file nor the relay log position have changed since the last check. This prevents infinite loops (i.e. restarting the same error in the same relay log file at the same relay log position). For certain slave errors, however, this check needs to be disabled by - specifying \ ``--no-check-relay-log``\ . Do not do this unless you know what + specifying :option:`--no-check-relay-log`. Do not do this unless you know what you are doing! ---config +.. option:: --config type: Array @@ -202,14 +172,14 @@ This tool accepts additional command-line arguments. Refer to the ---daemonize +.. option:: --daemonize Fork to the background and detach from the shell. POSIX operating systems only. ---database +.. option:: --database short form: -D; type: string @@ -217,7 +187,7 @@ This tool accepts additional command-line arguments. Refer to the ---defaults-file +.. option:: --defaults-file short form: -F; type: string @@ -226,94 +196,86 @@ This tool accepts additional command-line arguments. Refer to the ---error-length +.. option:: --error-length type: int - Max length of error message to print. When "--verbose" is set high enough to + Max length of error message to print. When :option:`--verbose` is set high enough to print the error, this option will truncate the error text to the specified length. This can be useful to prevent wrapping on the terminal. ---error-numbers +.. option:: --error-numbers type: hash - Only restart this comma-separated list of errors. Makes pt-slave-restart only - try to restart if the error number is in this comma-separated list of errors. + Only restart this comma-separated list of errors. Makes :program:`pt-slave-restart` only try to restart if the error number is in this comma-separated list of errors. If it sees an error not in the list, it will exit. The error number is in the \ ``last_errno``\ column of \ ``SHOW SLAVE STATUS``\ . ---error-text +.. option:: --error-text type: string - Only restart errors that match this pattern. A Perl regular expression against + Only restart errors that match this pattern. A *Perl* regular expression against which the error text, if any, is matched. If the error text exists and matches, - pt-slave-restart will try to restart the slave. If it exists but doesn't match, - pt-slave-restart will exit. + :program:`pt-slave-restart` will try to restart the slave. If it exists but doesn't match, :program:`pt-slave-restart` will exit. The error text is in the \ ``last_error``\ column of \ ``SHOW SLAVE STATUS``\ . - ---help +.. option:: --help Show help and exit. - ---host +.. option:: --host short form: -h; type: string Connect to host. - ---log +.. option:: --log type: string Print all output to this file when daemonized. - ---max-sleep +.. option:: --max-sleep type: float; default: 64 Maximum sleep seconds. - The maximum time pt-slave-restart will sleep before polling the slave again. - This is also the time that pt-slave-restart will wait for all other running - instances to quit if both "--stop" and "--monitor" are specified. + The maximum time :program:`pt-slave-restart` will sleep before polling the slave again. + This is also the time that :program:`pt-slave-restart` will wait for all other running + instances to quit if both :option:`--stop` and :option:`--monitor` are specified. See "SLEEP". - ---min-sleep +.. option:: --min-sleep type: float; default: 0.015625 - The minimum time pt-slave-restart will sleep before polling the slave again. + The minimum time :program:`pt-slave-restart` will sleep before polling the slave again. See "SLEEP". - ---monitor +.. option:: --monitor - Whether to monitor the slave (default). Unless you specify --monitor - explicitly, "--stop" will disable it. + Whether to monitor the slave (default). Unless you specify :option:`--monitor` + explicitly, :option:`--stop` will disable it. ---password +.. option:: --password short form: -p; type: string @@ -321,7 +283,7 @@ This tool accepts additional command-line arguments. Refer to the ---pid +.. option:: --pid type: string @@ -333,7 +295,7 @@ This tool accepts additional command-line arguments. Refer to the ---port +.. option:: --port short form: -P; type: int @@ -341,15 +303,15 @@ This tool accepts additional command-line arguments. Refer to the ---quiet +.. option:: --quiet short form: -q - Suppresses normal output (disables "--verbose"). + Suppresses normal output (disables :option:`--verbose`). ---recurse +.. option:: --recurse type: int; default: 0 @@ -357,21 +319,18 @@ This tool accepts additional command-line arguments. Refer to the in the hierarchy. The default depth of 0 means "just watch the slave specified." - pt-slave-restart examines \ ``SHOW PROCESSLIST``\ and tries to determine which - connections are from slaves, then connect to them. See "--recursion-method". + :program:`pt-slave-restart` examines \ ``SHOW PROCESSLIST``\ and tries to determine which connections are from slaves, then connect to them. See :option:`--recursion-method`. Recursion works by finding all slaves when the program starts, then watching - them. If there is more than one slave, \ ``pt-slave-restart``\ uses \ ``fork()``\ to - monitor them. + them. If there is more than one slave, :program:`pt-slave-restart` uses \ ``fork()``\ to monitor them. This also works if you have configured your slaves to show up in \ ``SHOW SLAVE - HOSTS``\ . The minimal configuration for this is the \ ``report_host``\ parameter, but - there are other "report" parameters as well for the port, username, and + HOSTS``\ . The minimal configuration for this is the \ ``report_host``\ parameter, but there are other "report" parameters as well for the port, username, and password. ---recursion-method +.. option:: --recursion-method type: string @@ -390,23 +349,18 @@ This tool accepts additional command-line arguments. Refer to the The processlist method is preferred because SHOW SLAVE HOSTS is not reliable. However, the hosts method is required if the server uses a non-standard - port (not 3306). Usually pt-slave-restart does the right thing and finds + port (not 3306). Usually :program:`pt-slave-restart` does the right thing and finds the slaves, but you may give a preferred method and it will be used first. If it doesn't find any slaves, the other methods will be tried. - ---run-time +.. option:: --run-time type: time - Time to run before exiting. Causes pt-slave-restart to stop after the specified - time has elapsed. Optional suffix: s=seconds, m=minutes, h=hours, d=days; if no - suffix, s is used. + Time to run before exiting. Causes :program:`pt-slave-restart` to stop after the specified time has elapsed. Optional suffix: s=seconds, m=minutes, h=hours, d=days; if no suffix, s is used. - - ---sentinel +.. option:: --sentinel type: string; default: /tmp/pt-slave-restart-sentinel @@ -414,16 +368,16 @@ This tool accepts additional command-line arguments. Refer to the ---set-vars +.. option:: --set-vars type: string; default: wait_timeout=10000 - Set these MySQL variables. Immediately after connecting to MySQL, this string + Set these |MySQL| variables. Immediately after connecting to |MySQL|, this string will be appended to SET and executed. ---skip-count +.. option:: --skip-count type: int; default: 1 @@ -431,7 +385,7 @@ This tool accepts additional command-line arguments. Refer to the ---sleep +.. option:: --sleep type: int; default: 1 @@ -441,7 +395,7 @@ This tool accepts additional command-line arguments. Refer to the ---socket +.. option:: --socket short form: -S; type: string @@ -449,22 +403,22 @@ This tool accepts additional command-line arguments. Refer to the ---stop +.. option:: --stop Stop running instances by creating the sentinel file. - Causes \ ``pt-slave-restart``\ to create the sentinel file specified by - "--sentinel". This should have the effect of stopping all running - instances which are watching the same sentinel file. If "--monitor" isn't - specified, \ ``pt-slave-restart``\ will exit after creating the file. If it is - specified, \ ``pt-slave-restart``\ will wait the interval given by - "--max-sleep", then remove the file and continue working. + Causes :program:`pt-slave-restart` to create the sentinel file specified by + :option:`--sentinel`. This should have the effect of stopping all running + instances which are watching the same sentinel file. If :option:`--monitor` isn't + specified, :program:`pt-slave-restart` will exit after creating the file. If it is + specified, :program:`pt-slave-restart` will wait the interval given by + :option:`--max-sleep`, then remove the file and continue working. You might find this handy to stop cron jobs gracefully if necessary, or to replace one running instance with another. For example, if you want to stop - and restart \ ``pt-slave-restart``\ every hour (just to make sure that it is + and restart :program:`pt-slave-restart` every hour (just to make sure that it is restarted every hour, in case of a server crash or some other problem), you - could use a \ ``crontab``\ line like this: + could use a ``crontab`` line like this: .. code-block:: perl @@ -472,15 +426,14 @@ This tool accepts additional command-line arguments. Refer to the 0 * * * * pt-slave-restart --monitor --stop --sentinel /tmp/pt-slave-restartup - The non-default "--sentinel" will make sure the hourly \ ``cron``\ job stops + The non-default :option:`--sentinel` will make sure the hourly \ ``cron``\ job stops only instances previously started with the same options (that is, from the same \ ``cron``\ job). - See also "--sentinel". + See also :option:`--sentinel`. - ---until-master +.. option:: --until-master type: string @@ -492,22 +445,22 @@ This tool accepts additional command-line arguments. Refer to the This will also cause an UNTIL clause to be given to START SLAVE. - After reaching this point, the slave should be stopped and pt-slave-restart + After reaching this point, the slave should be stopped and :program:`pt-slave-restart` will exit. ---until-relay +.. option:: --until-relay type: string - Run until this relay log file and position. Like "--until-master", but in + Run until this relay log file and position. Like :option:`--until-master`, but in the slave's relay logs instead. The coordinates are given by relay_log_file, relay_log_pos. ---user +.. option:: --user short form: -u; type: string @@ -515,27 +468,26 @@ This tool accepts additional command-line arguments. Refer to the ---verbose +.. option:: --verbose short form: -v; cumulative: yes; default: 1 Be verbose; can specify multiple times. Verbosity 1 outputs connection information, a timestamp, relay_log_file, relay_log_pos, and last_errno. - Verbosity 2 adds last_error. See also "--error-length". Verbosity 3 prints - the current sleep time each time pt-slave-restart sleeps. + Verbosity 2 adds last_error. See also :option:`--error-length`. Verbosity 3 prints + the current sleep time each time :program:`pt-slave-restart` sleeps. ---version +.. option:: --version Show version and exit. -*********** DSN OPTIONS -*********** +=========== These DSN options are used to create a DSN. Each option is given like @@ -545,7 +497,7 @@ if the value contains whitespace it must be quoted. DSN options are comma-separated. See the percona-toolkit manpage for full details. -\* A + * ``A`` dsn: charset; copy: yes @@ -553,7 +505,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* D + * ``D`` dsn: database; copy: yes @@ -561,7 +513,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* F + * ``F`` dsn: mysql_read_default_file; copy: yes @@ -569,7 +521,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* h + * ``h`` dsn: host; copy: yes @@ -577,7 +529,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* p + * ``p`` dsn: password; copy: yes @@ -585,7 +537,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* P + * ``p`` dsn: port; copy: yes @@ -593,7 +545,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* S + * ``S`` dsn: mysql_socket; copy: yes @@ -601,7 +553,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* u + * ``u`` dsn: user; copy: yes @@ -610,12 +562,11 @@ comma-separated. See the percona-toolkit manpage for full details. -*********** ENVIRONMENT -*********** +=========== -The environment variable \ ``PTDEBUG``\ enables verbose debugging output to STDERR. +The environment variable \ ``PTDEBUG``\ enables verbose debugging output to ``STDERR``. To enable debugging and capture all output to a file, run the tool like: @@ -628,128 +579,36 @@ Be careful: debugging output is voluminous and can generate several megabytes of output. -******************* SYSTEM REQUIREMENTS -******************* +=================== -You need Perl, DBI, DBD::mysql, and some core packages that ought to be -installed in any reasonably new version of Perl. +You need *Perl* , ``DBI``, ``DBD::mysql``, and some core packages that ought to be +installed in any reasonably new version of *Perl* . -**** BUGS -**** +==== For a list of known bugs, see `http://www.percona.com/bugs/pt-slave-restart `_. 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* -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 2007-2011 Baron Schwartz, 2011 Percona Inc. +This program is copyright 2007-2011 *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 -******* +======= - -pt-slave-restart 1.0.1 + :program:`pt-slave-restart` 1.0.1 diff --git a/docs/user/source/pt-stalk.rst b/docs/user/source/pt-stalk.rst new file mode 100644 index 00000000..9ca7c18d --- /dev/null +++ b/docs/user/source/pt-stalk.rst @@ -0,0 +1,270 @@ +.. program:: pt-stalk + +===================== + :program:`pt-stalk` +===================== + +.. highlight:: perl + + +NAME +==== + + :program:`pt-stalk` - Wait for a condition to occur then begin collecting data. + + +SYNOPSIS +======== + + +Usage +----- + +:: + + pt-stalk + +:program:`pt-stalk` watches for a condition to become true, and when it does, executes +a script. By default it executes :program:`pt-collect`, but that can be customized. +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. + :program:`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 :ref:`bugs` for more information on filing bugs and getting help. + + +DESCRIPTION +=========== + + +Although :program:`pt-stalk` comes pre-configured to do a specific thing, in general +this tool is just a skeleton script for the following flow of actions: + + + 1. Loop infinitely, sleeping between iterations. + + + + 2. In each iteration, run some command and get the output. + + + + 3. If the command fails or the output is larger than the threshold, + execute the collection script; but do not execute if the destination disk + is too full. + + + +By default, the tool is configured to execute mysqladmin extended-status and +extract the value of the Threads_connected variable; if this is greater than +100, it runs the collection script. This is really just placeholder code, +and almost certainly needs to be customized! + +If the tool does execute the collection script, it will wait for a while +before checking and executing again. This is to prevent a continuous +condition from causing a huge number of executions to fire off. + +The name 'stalk' is because 'watch' is already taken, and 'stalk' is fun. + + +CONFIGURING +=========== + + +If the file :file:`pt-stalk.conf` exists in the current working directory, then +"ENVIRONMENT" variables are imported from it. For example, the config +file has the format: + + +.. code-block:: perl + + INTERVAL=10 + GDB=yes + + +See "ENVIRONMENT". + + +OPTIONS +======= + + +This tool does not have any command-line options, but see +"ENVIRONMENT" and "CONFIGURING". + + +ENVIRONMENT +=========== + + +The following environment variables configure how, what, and when the tool +runs. They are all optional and can be specified either on the command line +or in the :file:`pt-stalk.conf` config file (see "CONFIGURING"). + + + * ``THRESHOLD`` (default 100) + + This is the max number of we want to tolerate. + + + + * ``VARIABLE`` (default Threads_connected} + + This is the thing to check for. + + + + * ``CYCLES`` (default 1) + + How many times must the condition be met before the script will fire? + + + + * ``GDB`` (default no) + + Collect GDB stacktraces? + + + + * ``OPROFILE`` (default yes) + + Collect oprofile data? + + + + * ``STRACE`` (default no) + + Collect strace data? + + + + * ``TCPDUMP`` (default yes) + + Collect tcpdump data? + + + + * ``EMAIL`` + + Send mail to this list of addresses when the script triggers. + + + + * ``MYSQLOPTIONS`` + + Any options to pass to mysql/mysqladmin, such as -u, -p, etc + + + + * ``INTERVAL`` (default 30) + + This is the interval between checks. + + + + * ``MAYBE_EMPTY`` (default no) + + If the command you're running to detect the condition is allowed to return + nothing (e.g. a grep line that might not even exist if there's no problem), + then set this to "yes". + + + + * ``COLLECT`` (default ${HOME}/bin/pt-collect) + + This is the location of the 'collect' script. + + + + * ``DEST`` (default ${HOME}/collected/) + + This is where to store the collected data. + + + + * ``DURATION`` (default 30) + + How long to collect statistics data for? Make sure that this isn't longer + than SLEEP. + + + + * ``SLEEP`` (default DURATION \* 10) + + How long to sleep after collecting? + + + + * ``PCT_THRESHOLD`` (default 95) + + Bail out if the disk is more than this %full. + + + + * ``MB_THRESHOLD`` (default 100) + + Bail out if the disk has less than this many MB free. + + + + * ``PURGE`` (default 30) + + Remove samples after this many days. + + + + +SYSTEM REQUIREMENTS +=================== + + +This tool requires Bash v3 or newer. + + +BUGS +==== + + +For a list of known bugs, see `http://www.percona.com/bugs/pt-stalk `_. + +Please report bugs at `https://bugs.launchpad.net/percona-toolkit `_. + + +AUTHORS +======= + + +*Baron Schwartz*, *Justin Swanhart*, and *Fernando Ipar* + + +COPYRIGHT, LICENSE, AND WARRANTY +================================ + + +This program is copyright 2010-2011 *Baron Schwartz*, 2011 Percona Inc. +Feedback and improvements are welcome. + + +VERSION +======= + +:program:`pt-stalk` 1.0.1 + diff --git a/docs/user/source/pt-summary.rst b/docs/user/source/pt-summary.rst new file mode 100644 index 00000000..ab9c86a6 --- /dev/null +++ b/docs/user/source/pt-summary.rst @@ -0,0 +1,136 @@ +.. program:: pt-summary + +======================= + :program:`pt-summary` +======================= + +.. highlight:: perl + + +NAME +==== + + :program:`pt-summary` - Summarize system information in a nice way. + + +SYNOPSIS +======== + + +Usage +----- + +:: + + pt-summary + +:program:`pt-summary` conveniently summarizes the status and configuration of a server. +It is not a tuning tool or diagnosis tool. It produces a report that is easy +to diff and can be pasted into emails without losing the formatting. This +tool works well on Linux systems. + +Download and run: + + +.. code-block:: perl + + wget http://percona.com/get/pt-summary + bash ./pt-summary + + +Download and run in a single step: + + +.. code-block:: perl + + 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. + +:program:`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 :ref:`bugs` for more information on filing bugs and getting help. + + +DESCRIPTION +=========== + +:program:`pt-summary` runs a large variety of commands to inspect system status and +configuration, saves the output into files in /tmp, and then runs Unix +commands on these results to format them nicely. It works best when +executed as a privileged user, but will also work without privileges, +although some output might not be possible to generate without root. + + +OPTIONS +======= + + +This tool does not have any command-line options. + + +ENVIRONMENT +=========== + + +The ``PT_SUMMARY_SKIP`` environment variable specifies a comma-separated list +of things to skip: + + +.. code-block:: perl + + MOUNT: Don't print out mounted filesystems and disk fullness. + NETWORK: Don't print out information on network controllers & config. + PROCESS: Don't print out top processes and vmstat information. + + + +SYSTEM REQUIREMENTS +=================== + + +This tool requires the Bourne shell (\ */bin/sh*\ ). + + +BUGS +==== + + +For a list of known bugs, see `http://www.percona.com/bugs/pt-summary `_. + +Please report bugs at `https://bugs.launchpad.net/percona-toolkit `_. + +AUTHORS +======= + +*Baron Schwartz* and *Kevin van Zonneveld* (http://kevin.vanzonneveld.net) + + +COPYRIGHT, LICENSE, AND WARRANTY +================================ + +This program is copyright 2010-2011 *Baron Schwartz*, 2011 Percona Inc. +Feedback and improvements are welcome. + +VERSION +======= + +:program:`pt-summary` 1.0.1 + diff --git a/docs/user/pt-table-checksum.rst b/docs/user/source/pt-table-checksum.rst similarity index 66% rename from docs/user/pt-table-checksum.rst rename to docs/user/source/pt-table-checksum.rst index 73ed4d5f..e3ef841b 100644 --- a/docs/user/pt-table-checksum.rst +++ b/docs/user/source/pt-table-checksum.rst @@ -1,33 +1,36 @@ +.. program:: pt-table-checksum -################# -pt-table-checksum -################# +============================== + :program:`pt-table-checksum` +============================== .. highlight:: perl -**** NAME -**** +==== + + :program:`pt-table-checksum` - Perform an online replication consistency check, or checksum |MySQL| tables efficiently on one or many servers. -pt-table-checksum - Perform an online replication consistency check, or checksum MySQL tables efficiently on one or many servers. - - -******** SYNOPSIS -******** +======== -Usage: pt-table-checksum [OPTION...] DSN [DSN...] +Usage +----- -pt-table-checksum checksums MySQL tables efficiently on one or more hosts. +:: + + pt-table-checksum [OPTION...] DSN [DSN...] + +:program:`pt-table-checksum` checksums |MySQL| tables efficiently on one or more hosts. 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 slaves against a master? Then be sure to learn -what "--replicate" does. It is probably the option you want to use. +what :option:`--replicate` does. It is probably the option you want to use. Checksum all slaves against the master: @@ -58,9 +61,8 @@ Checksum all databases and tables on two servers and print the differences: See "SPECIFYING HOSTS" for more on the syntax of the host arguments. -***** RISKS -***** +===== The following section is included to inform users about the potential risks, @@ -68,9 +70,8 @@ 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-table-checksum executes queries that cause the MySQL server to checksum its -data. This can cause significant server load. It is read-only unless you use -the "--replicate" option, in which case it inserts a small amount of data +:program:`pt-table-checksum` executes queries that cause the |MySQL| server to checksum its data. This can cause significant server load. It is read-only unless you use +the :option:`--replicate` option, in which case it inserts a small amount of data into the specified table. At the time of this release, we know of no bugs that could cause serious harm to @@ -81,24 +82,22 @@ 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-table-checksum `_. -See also "BUGS" for more information on filing bugs and getting help. +See also :ref:`bugs` for more information on filing bugs and getting help. -*********** DESCRIPTION -*********** +=========== - -pt-table-checksum generates table checksums for MySQL tables, typically +:program:`pt-table-checksum` generates table checksums for |MySQL| tables, typically useful for verifying your slaves are in sync with the master. The checksums are generated by a query on the server, and there is very little network traffic as a result. -Checksums typically take about twice as long as COUNT(\*) on very large InnoDB +Checksums typically take about twice as long as COUNT(\*) on very large |InnoDB| tables in my tests. For smaller tables, COUNT(\*) is a good bit faster than -the checksums. See "--algorithm" for more details on performance. +the checksums. See :option:`--algorithm` for more details on performance. -If you specify more than one server, pt-table-checksum assumes the first +If you specify more than one server, :program:`pt-table-checksum` assumes the first server is the master and others are slaves. Checksums are parallelized for speed, forking off a child process for each table. Duplicate server names are ignored, but if you want to checksum a server against itself you can use two @@ -117,18 +116,17 @@ on the same server, just checksum both databases: You can then use pt-checksum-filter to compare the results in both databases easily. -pt-table-checksum examines table structure only on the first host specified, +:program:`pt-table-checksum` examines table structure only on the first host specified, so if anything differs on the others, it won't notice. It ignores views. -The checksums work on MySQL version 3.23.58 through 6.0-alpha. They will not +The checksums work on |MySQL| version 3.23.58 through 6.0-alpha. They will not necessarily produce the same values on all versions. Differences in formatting and/or space-padding between 4.1 and 5.0, for example, will cause the checksums to be different. -**************** SPECIFYING HOSTS -**************** +================ Each host is specified on the command line as a DSN. A DSN is a comma-separted @@ -142,9 +140,9 @@ to subsequent DSNs that do not specify the DSN option. For example, This allows you to avoid repeating DSN options that have the same value for all DSNs. -Connection-related command-line options like "--user" and "--password" +Connection-related command-line options like :option:`--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" +the short form of each option. For example, the short form of :option:`--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. @@ -159,29 +157,27 @@ The DSN option value precedence from higest to lowest is: * default values from connection-related command-line options -If you are confused about how pt-table-checksum will connect to your servers, -use the "--explain-hosts" option and it will tell you. +If you are confused about how :program:`pt-table-checksum` will connect to your servers, +use the :option:`--explain-hosts` option and it will tell you. -*************** HOW FAST IS IT? -*************** +=============== Speed and efficiency are important, because the typical use case is checksumming large amounts of data. -\ ``pt-table-checksum``\ is designed to do very little work itself, and generates -very little network traffic aside from inspecting table structures with \ ``SHOW -CREATE TABLE``\ . The results of checksum queries are typically 40-character or +:program:`pt-table-checksum` is designed to do very little work itself, and generates +very little network traffic aside from inspecting table structures with ``SHOW +CREATE TABLE``. The results of checksum queries are typically 40-character or shorter strings. -The MySQL server does the bulk of the work, in the form of the checksum queries. +The |MySQL| server does the bulk of the work, in the form of the checksum queries. The following benchmarks show the checksum query times for various checksum algorithms. The first two results are simply running \ ``COUNT(col8)``\ and -\ ``CHECKSUM TABLE``\ on the table. \ ``CHECKSUM TABLE``\ is just \ ``CRC32``\ under the -hood, but it's implemented inside the storage engine layer instead of at the -MySQL layer. +\ ``CHECKSUM TABLE``\ on the table. \ ``CHECKSUM TABLE``\ is just \ ``CRC32``\ under the hood, but it's implemented inside the storage engine layer instead of at the +|MySQL| layer. .. code-block:: perl @@ -200,7 +196,7 @@ MySQL layer. BIT_XOR SHA1 197.3 -The tests are entirely CPU-bound. The sample data is an InnoDB table with the +The tests are entirely CPU-bound. The sample data is an |InnoDB| table with the following structure: @@ -218,7 +214,7 @@ following structure: PRIMARY KEY (col2, col1), KEY (col7), KEY (col1) - ) ENGINE=InnoDB + ) ENGINE=|InnoDB| The table has 4303585 rows, 365969408 bytes of data and 173457408 bytes of @@ -232,15 +228,14 @@ cases. If you need stronger guarantees that your data is identical, you should use one of the other functions. -******************* ALGORITHM SELECTION -******************* +=================== -The "--algorithm" option allows you to specify which algorithm you would -like to use, but it does not guarantee that pt-table-checksum will use this -algorithm. pt-table-checksum will ultimately select the best algorithm possible -given various factors such as the MySQL version and other command line options. +The :option:`--algorithm` option allows you to specify which algorithm you would +like to use, but it does not guarantee that :program:`pt-table-checksum` will use this +algorithm. :program:`pt-table-checksum` will ultimately select the best algorithm possible +given various factors such as the |MySQL| version and other command line options. The three basic algorithms in descending order of preference are CHECKSUM, BIT_XOR and ACCUM. CHECKSUM cannot be used if any one of these criteria @@ -257,22 +252,21 @@ is true: * MySQL version less than 4.1.1 -The BIT_XOR algorithm also requires MySQL version 4.1.1 or later. +The BIT_XOR algorithm also requires |MySQL| version 4.1.1 or later. -After checking these criteria, if the requested "--algorithm" remains then it +After checking these criteria, if the requested :option:`--algorithm` remains then it is used, otherwise the first remaining algorithm with the highest preference is used. -******************** CONSISTENT CHECKSUMS -******************** +==================== If you are using this tool to verify your slaves still have the same data as the master, which is why I wrote it, you should read this section. -The best way to do this with replication is to use the "--replicate" option. +The best way to do this with replication is to use the :option:`--replicate` option. When the queries are finished running on the master and its slaves, you can go to the slaves and issue SQL queries to see if any tables are different from the master. Try the following: @@ -288,57 +282,39 @@ master. Try the following: OR ISNULL(master_crc) <> ISNULL(this_crc); -The "--replicate-check" option can do this query for you. If you can't use +The :option:`--replicate-check` option can do this query for you. If you can't use this method, try the following: - -\* - - If your servers are not being written to, you can just run the tool with no + * If your servers are not being written to, you can just run the tool with no further ado: .. code-block:: perl - pt-table-checksum server1 server2 ... serverN - - + pt-table-checksum server1 server2 ... serverN -\* - - If the servers are being written to, you need some way to make sure they are + * If the servers are being written to, you need some way to make sure they are consistent at the moment you run the checksums. For situations other than master-slave replication, you will have to figure this out yourself. You may be - able to use the "--where" option with a date or time column to only checksum + able to use the :option:`--where` option with a date or time column to only checksum data that's not recent. - - -\* - - If you are checksumming a master and slaves, you can do a fast parallel + * If you are checksumming a master and slaves, you can do a fast parallel checksum and assume the slaves are caught up to the master. In practice, this tends to work well except for tables which are constantly updated. You can - use the "--slave-lag" option to see how far behind each slave was when it + use the :option:`--slave-lag` option to see how far behind each slave was when it checksummed a given table. This can help you decide whether to investigate further. - - -\* - - The next most disruptive technique is to lock the table on the master, then take + * The next most disruptive technique is to lock the table on the master, then take checksums. This should prevent changes from propagating to the slaves. You can - just lock on the master (with "--lock"), or you can both lock on the master + just lock on the master (with :option:`--lock`), or you can both lock on the master and wait on the slaves till they reach that point in the master's binlog - ("--wait"). Which is better depends on your workload; only you know that. + (:option:`--wait`). Which is better depends on your workload; only you know that. - -\* - - If you decide to make the checksums on the slaves wait until they're guaranteed + * If you decide to make the checksums on the slaves wait until they're guaranteed to be caught up to the master, the algorithm looks like this: @@ -355,27 +331,23 @@ this method, try the following: End - - -What I typically do when I'm not using the "--replicate" option is simply run +What I typically do when I'm not using the :option:`--replicate` option is simply run the tool on all servers with no further options. This runs fast, parallel, non-blocking checksums simultaneously. If there are tables that look different, -I re-run with "--wait"=600 on the tables in question. This makes the tool +I re-run with :option:`--wait`=600 on the tables in question. This makes the tool lock on the master as explained above. -****** OUTPUT -****** +====== - -Output is to STDOUT, one line per server and table, with header lines for each +Output is to ``STDOUT``, one line per server and table, with header lines for each database. I tried to make the output easy to process with awk. For this reason -columns are always present. If there's no value, pt-table-checksum prints +columns are always present. If there's no value, :program:`pt-table-checksum` prints 'NULL'. The default is column-aligned output for human readability, but you can change -it to tab-separated if you want. Use the "--tab" option for this. +it to tab-separated if you want. Use the :option:`--tab` option for this. Output is unsorted, though all lines for one table should be output together. For speed, all checksums are done in parallel (as much as possible) and may @@ -388,76 +360,73 @@ differences. The columns in the output are as follows. The database, table, and chunk come first so you can sort by them easily (they are the "primary key"). -Output from "--replicate-check" and "--checksum" are different. +Output from :option:`--replicate-check` and :option:`--checksum` are different. -DATABASE + * ``DATABASE`` The database the table is in. -TABLE + * ``TABLE`` The table name. -CHUNK + * ``CHUNK`` - The chunk (see "--chunk-size"). Zero if you are not doing chunked checksums. + The chunk (see :option:`--chunk-size`). Zero if you are not doing chunked checksums. -HOST + * ``HOST`` The server's hostname. -ENGINE + * ``ENGINE`` The table's storage engine. -COUNT + * ``COUNT`` The table's row count, unless you specified to skip it. If \ ``OVERSIZE``\ is printed, the chunk was skipped because the actual number of rows was greater - than "--chunk-size" times "--chunk-size-limit". + than :option:`--chunk-size` times :option:`--chunk-size-limit`. - -CHECKSUM + * ``CHECKSUM`` The table's checksum, unless you specified to skip it or the table has no rows. some types of checksums will be 0 if there are no rows; others will print NULL. - - -TIME + * ``TIME`` How long it took to checksum the \ ``CHUNK``\ , not including \ ``WAIT``\ time. Total checksum time is \ ``WAIT + TIME``\ . -WAIT + * ``WAIT`` How long the slave waited to catch up to its master before beginning to - checksum. \ ``WAIT``\ is always 0 for the master. See "--wait". + checksum. \ ``WAIT``\ is always 0 for the master. See :option:`--wait`. -STAT + * ``STAT`` The return value of MASTER_POS_WAIT(). \ ``STAT``\ is always \ ``NULL``\ for the master. -LAG + * ``LAG`` How far the slave lags the master, as reported by SHOW SLAVE STATUS. \ ``LAG``\ is always \ ``NULL``\ for the master. @@ -465,22 +434,21 @@ LAG -*************************** REPLICATE TABLE MAINTENANCE -*************************** +=========================== -If you use "--replicate" to store and replicate checksums, you may need to +If you use :option:`--replicate` to store and replicate checksums, you may need to perform maintenance on the replicate table from time to time to remove old checksums. This section describes when checksums in the replicate table are -deleted automatically by pt-table-checksum and when you must manually delete +deleted automatically by :program:`pt-table-checksum` and when you must manually delete them. -Before starting, pt-table-checksum calculates chunks for each table, even -if "--chunk-size" is not specified (in that case there is one chunk: "1=1"). +Before starting, :program:`pt-table-checksum` calculates chunks for each table, even +if :option:`--chunk-size` is not specified (in that case there is one chunk: "1=1"). Then, before checksumming each table, the tool deletes checksum chunks in the replicate table greater than the current number of chunks. For example, -if a table is chunked into 100 chunks, 0-99, then pt-table-checksum does: +if a table is chunked into 100 chunks, 0-99, then :program:`pt-table-checksum` does: .. code-block:: perl @@ -491,7 +459,7 @@ if a table is chunked into 100 chunks, 0-99, then pt-table-checksum does: That removes any high-end chunks from previous runs which no longer exist. Currently, this operation cannot be disabled. -If you use "--resume", "--resume-replicate", or "--modulo", then +If you use :option:`--resume`, :option:`--resume-replicate`, or :option:`--modulo`, then you need to be careful that the number of rows in a table does not decrease so much that the number of chunks decreases too, else some checksum chunks may be deleted. The one exception is if only rows at the high end of the range @@ -499,39 +467,36 @@ are deleted. In that case, the high-end chunks are deleted and lower chunks remain unchanged. An increasing number of rows or chunks should not cause any adverse affects. -Changing the "--chunk-size" between runs with "--resume", -"--resume-replicate", or "--modulo" can cause odd or invalid checksums. +Changing the :option:`--chunk-size` between runs with :option:`--resume`, +:option:`--resume-replicate`, or :option:`--modulo` can cause odd or invalid checksums. You should not do this. It won't work with the resume options. With -"--modulo", the safest thing to do is manually delete all the rows in +:option:`--modulo`, the safest thing to do is manually delete all the rows in the replicate table for the table in question and start over. If the replicate table becomes cluttered with old or invalid checksums and the auto-delete operation is not deleting them, then you will need to manually clean up the replicate table. Alternatively, if you specify -"--empty-replicate-table", then the tool deletes every row in the +:option:`--empty-replicate-table`, then the tool deletes every row in the replicate table. -*********** EXIT STATUS -*********** - +=========== An exit status of 0 (sometimes also called a return value or return code) indicates success. If there is an error checksumming any table, the exit status is 1. -When running "--replicate-check", if any slave has chunks that differ from +When running :option:`--replicate-check`, if any slave has chunks that differ from the master, the exit status is 1. -******* QUERIES -******* +======= If you are using innotop (see `http://code.google.com/p/innotop `_), -mytop, or another tool to watch currently running MySQL queries, you may see +mytop, or another tool to watch currently running |MySQL| queries, you may see the checksum queries. They look similar to this: @@ -540,7 +505,7 @@ the checksum queries. They look similar to this: REPLACE /*test.test_tbl:'2'/'5'*/ INTO test.checksum(db, ... -Since pt-table-checksum's queries run for a long time and tend to be +Since :program:`pt-table-checksum`'s queries run for a long time and tend to be textually very long, and thus won't fit on one screen of these monitoring tools, I've been careful to place a comment at the beginning of the query so you can see what it is and what it's doing. The comment contains the name of @@ -549,20 +514,18 @@ and how many chunks will be checksummed. In the case above, it is checksumming chunk 2 of 5 in table test.test_tbl. -******* OPTIONS -******* +======= -"--schema" is restricted to option groups Connection, Filter, Output, Help, Config, Safety. +:option:`--schema` is restricted to option groups Connection, Filter, Output, Help, Config, Safety. -"--empty-replicate-table", "--resume" and "--resume-replicate" are mutually exclusive. +:option:`--empty-replicate-table`, :option:`--resume` and :option:`--resume-replicate` are mutually exclusive. -This tool accepts additional command-line arguments. Refer to the -"SYNOPSIS" and usage information for details. +This tool accepts additional command-line arguments. Refer to the "SYNOPSIS" and usage information for details. ---algorithm +.. option:: --algorithm type: string @@ -572,19 +535,19 @@ This tool accepts additional command-line arguments. Refer to the BIT_XOR and ACCUM. The latter two do cryptographic hash checksums. See also "ALGORITHM SELECTION". - CHECKSUM is built into MySQL, but has some disadvantages. BIT_XOR and ACCUM are + CHECKSUM is built into |MySQL|, but has some disadvantages. BIT_XOR and ACCUM are implemented by SQL queries. They use a cryptographic hash of all columns concatenated together with a separator, followed by a bitmap of each nullable column that is NULL (necessary because CONCAT_WS() skips NULL columns). - CHECKSUM is the default. This method uses MySQL's built-in CHECKSUM TABLE - command, which is a CRC32 behind the scenes. It cannot be used before MySQL + CHECKSUM is the default. This method uses |MySQL|'s built-in CHECKSUM TABLE + command, which is a CRC32 behind the scenes. It cannot be used before |MySQL| 4.1.1, and various options disable it as well. It does not simultaneously count rows; that requires an extra COUNT(\*) query. This is a good option when you are - using MyISAM tables with live checksums enabled; in this case both the COUNT(\*) + using |MyISAM| tables with live checksums enabled; in this case both the COUNT(\*) and CHECKSUM queries will run very quickly. - The BIT_XOR algorithm is available for MySQL 4.1.1 and newer. It uses + The BIT_XOR algorithm is available for |MySQL| 4.1.1 and newer. It uses BIT_XOR(), which is order-independent, to reduce all the rows to a single checksum. @@ -602,13 +565,12 @@ This tool accepts additional command-line arguments. Refer to the with identical data but the rows are out of order, you'll get different checksums with ACCUM. - If a given algorithm won't work for some reason, pt-table-checksum falls back to - another. The least common denominator is ACCUM, which works on MySQL 3.23.2 and + If a given algorithm won't work for some reason, :program:`pt-table-checksum` falls back to + another. The least common denominator is ACCUM, which works on |MySQL| 3.23.2 and newer. - ---arg-table +.. option:: --arg-table type: string @@ -645,7 +607,7 @@ This tool accepts additional command-line arguments. Refer to the not matter, but it's suggested you use a sensible data type to prevent garbage data. - When \ ``pt-table-checksum``\ checksums a table, it will look for a matching entry + When :program:`pt-table-checksum` checksums a table, it will look for a matching entry in this table. Any column that has a defined value will override the corresponding command-line argument for the table being currently processed. In this way it is possible to specify custom command-line arguments for any @@ -654,99 +616,89 @@ This tool accepts additional command-line arguments. Refer to the If you add columns to the table that aren't in the above list of allowable columns, it's an error. The exceptions are \ ``db``\ , \ ``tbl``\ , and \ ``ts``\ . The \ ``ts``\ column can be used as a timestamp for easy visibility into the last time the - \ ``since``\ column was updated with "--save-since". + \ ``since``\ column was updated with :option:`--save-since`. This table is assumed to be located on the first server given on the command-line. - ---ask-pass +.. option:: --ask-pass group: Connection - Prompt for a password when connecting to MySQL. + Prompt for a password when connecting to |MySQL|. - ---check-interval +.. option:: --check-interval type: time; group: Throttle; default: 1s - How often to check for slave lag if "--check-slave-lag" is given. + How often to check for slave lag if :option:`--check-slave-lag` is given. - ---[no]check-replication-filters +.. option:: --[no]check-replication-filters default: yes; group: Safety - Do not "--replicate" if any replication filters are set. When - --replicate is specified, pt-table-checksum tries to detect slaves and look + Do not :option:`--replicate` if any replication filters are set. When + --replicate is specified, :program:`pt-table-checksum` tries to detect slaves and look for options that filter replication, such as binlog_ignore_db and replicate_do_db. If it finds any such filters, it aborts with an error. Replication filtering makes it impossible to be sure that the checksum queries won't break replication or simply fail to replicate. If you are sure that it's OK to run the checksum queries, you can negate this option to - disable the checks. See also "--replicate-database". + disable the checks. See also :option:`--replicate-database`. - ---check-slave-lag +.. option:: --check-slave-lag type: DSN; group: Throttle - Pause checksumming until the specified slave's lag is less than "--max-lag". + Pause checksumming until the specified slave's lag is less than :option:`--max-lag`. - If this option is specified and "--throttle-method" is set to \ ``slavelag``\ - then "--throttle-method" only checks this slave. + If this option is specified and :option:`--throttle-method` is set to \ ``slavelag``\ + then :option:`--throttle-method` only checks this slave. - ---checksum +.. option:: --checksum group: Output Print checksums and table names in the style of md5sum (disables - "--[no]count"). + :option:`--[no]count`). Makes the output behave more like the output of \ ``md5sum``\ . The checksum is first on the line, followed by the host, database, table, and chunk number, concatenated with dots. - ---chunk-column +.. option:: --chunk-column type: string Prefer this column for dividing tables into chunks. By default, - pt-table-checksum chooses the first suitable column for each table, preferring + :program:`pt-table-checksum` chooses the first suitable column for each table, preferring to use the primary key. This option lets you specify a preferred column, which - pt-table-checksum uses if it exists in the table and is chunkable. If not, then - pt-table-checksum will revert to its default behavior. Be careful when using + :program:`pt-table-checksum` uses if it exists in the table and is chunkable. If not, then + :program:`pt-table-checksum` will revert to its default behavior. Be careful when using this option; a poor choice could cause bad performance. This is probably best to use when you are checksumming only a single table, not an entire server. See - also "--chunk-index". + also :option:`--chunk-index`. - ---chunk-index +.. option:: --chunk-index type: string - Prefer this index for chunking tables. By default, pt-table-checksum chooses an - appropriate index for the "--chunk-column" (even if it chooses the chunk + Prefer this index for chunking tables. By default, :program:`pt-table-checksum` chooses an appropriate index for the :option:`--chunk-column` (even if it chooses the chunk column automatically). This option lets you specify the index you prefer. If - the index doesn't exist, then pt-table-checksum will fall back to its default - behavior. pt-table-checksum adds the index to the checksum SQL statements in a - \ ``FORCE INDEX``\ clause. Be careful when using this option; a poor choice of + the index doesn't exist, then :program:`pt-table-checksum` will fall back to its default + behavior. :program:`pt-table-checksum` adds the index to the checksum SQL statements in a \ ``FORCE INDEX``\ clause. Be careful when using this option; a poor choice of index could cause bad performance. This is probably best to use when you are checksumming only a single table, not an entire server. - ---chunk-range +.. option:: --chunk-range type: string; default: open @@ -762,7 +714,7 @@ This tool accepts additional command-line arguments. Refer to the openclosed Low end open, high end closed - By default pt-table-checksum uses an open range of chunks like: + By default :program:`pt-table-checksum` uses an open range of chunks like: .. code-block:: perl @@ -774,7 +726,7 @@ This tool accepts additional command-line arguments. Refer to the That range is open because the last chunk selects any row with id greater than (or equal to) 20. An open range can be a problem in cases where a lot of new - rows are inserted with IDs greater than 20 while pt-table-checksumming is + rows are inserted with IDs greater than 20 while :program:`pt-table-checksum`ming is running because the final open-ended chunk will select all the newly inserted rows. (The less common case of inserting rows with IDs less than 10 would require a \ ``closedopen``\ range but that is not currently implemented.) @@ -786,31 +738,31 @@ This tool accepts additional command-line arguments. Refer to the `id` >= '20' AND `id` <= N - N is the \ ``MAX(\`id\`)``\ that pt-table-checksum used when it first chunked + N is the \ ``MAX(\`id\`)``\ that :program:`pt-table-checksum` used when it first chunked the rows. Therefore, it will only chunk the range of rows that existed when the tool started and not any newly inserted rows (unless those rows happen to be inserted with IDs less than N). - See also "--chunk-size-limit". + See also :option:`--chunk-size-limit`. ---chunk-size +.. option:: --chunk-size type: string Approximate number of rows or size of data to checksum at a time. Allowable suffixes are k, M, G. Disallows \ ``--algorithm CHECKSUM``\ . - If you specify a chunk size, pt-table-checksum will try to find an index that - will let it split the table into ranges of approximately "--chunk-size" + If you specify a chunk size, :program:`pt-table-checksum` will try to find an index that + will let it split the table into ranges of approximately :option:`--chunk-size` rows, based on the table's index statistics. Currently only numeric and date types can be chunked. - If the table is chunkable, pt-table-checksum will checksum each range separately - with parameters in the checksum query's WHERE clause. If pt-table-checksum + If the table is chunkable, :program:`pt-table-checksum` will checksum each range separately + with parameters in the checksum query's WHERE clause. If :program:`pt-table-checksum` cannot find a suitable index, it will do the entire table in one chunk as though - you had not specified "--chunk-size" at all. Each table is handled + you had not specified :option:`--chunk-size` at all. Each table is handled individually, so some tables may be chunked and others not. The chunks will be approximately sized, and depending on the distribution of @@ -824,37 +776,37 @@ This tool accepts additional command-line arguments. Refer to the ---chunk-size-limit +.. option:: --chunk-size-limit type: float; default: 2.0; group: Safety - Do not checksum chunks with this many times more rows than "--chunk-size". + Do not checksum chunks with this many times more rows than :option:`--chunk-size`. - When "--chunk-size" is given it specifies an ideal size for each chunk + When :option:`--chunk-size` is given it specifies an ideal size for each chunk of a chunkable table (in rows; size values are converted to rows). Before - checksumming each chunk, pt-table-checksum checks how many rows are in the + checksumming each chunk, :program:`pt-table-checksum` checks how many rows are in the chunk with EXPLAIN. If the number of rows reported by EXPLAIN is this many - times greater than "--chunk-size", then the chunk is skipped and \ ``OVERSIZE``\ + times greater than :option:`--chunk-size`, then the chunk is skipped and \ ``OVERSIZE``\ is printed for the \ ``COUNT``\ column of the "OUTPUT". - For example, if you specify "--chunk-size" 100 and a chunk has 150 rows, - then it is checksummed with the default "--chunk-size-limit" value 2.0 + For example, if you specify :option:`--chunk-size` 100 and a chunk has 150 rows, + then it is checksummed with the default :option:`--chunk-size-limit` value 2.0 because 150 is less than 100 \* 2.0. But if the chunk has 205 rows, then it is not checksummed because 205 is greater than 100 \* 2.0. The minimum value for this option is 1 which means that no chunk can be any - larger than "--chunk-size". You probably don't want to specify 1 because + larger than :option:`--chunk-size`. You probably don't want to specify 1 because rows reported by EXPLAIN are estimates which can be greater than or less than the real number of rows in the chunk. If too many chunks are skipped because they are oversize, you might want to specify a value larger than 2. - You can disable oversize chunk checking by specifying "--chunk-size-limit" 0. + You can disable oversize chunk checking by specifying :option:`--chunk-size-limit` 0. - See also "--unchunkable-tables". + See also :option:`--unchunkable-tables`. ---columns +.. option:: --columns short form: -c; type: array; group: Filter @@ -862,7 +814,7 @@ This tool accepts additional command-line arguments. Refer to the ---config +.. option:: --config type: Array; group: Config @@ -871,19 +823,19 @@ This tool accepts additional command-line arguments. Refer to the ---[no]count +.. option:: --[no]count Count rows in tables. This is built into ACCUM and BIT_XOR, but requires an extra query for CHECKSUM. This is disabled by default to avoid an extra COUNT(\*) query when - "--algorithm" is CHECKSUM. If you have only MyISAM tables and live checksums + :option:`--algorithm` is CHECKSUM. If you have only |MyISAM| tables and live checksums are enabled, both CHECKSUM and COUNT will be very fast, but otherwise you may want to use one of the other algorithms. ---[no]crc +.. option:: --[no]crc default: yes @@ -894,23 +846,23 @@ This tool accepts additional command-line arguments. Refer to the ---create-replicate-table +.. option:: --create-replicate-table - Create the replicate table given by "--replicate" if it does not exist. + Create the replicate table given by :option:`--replicate` if it does not exist. - Normally, if the replicate table given by "--replicate" does not exist, - \ ``pt-table-checksum``\ will die. With this option, however, \ ``pt-table-checksum``\ + Normally, if the replicate table given by :option:`--replicate` does not exist, + \ ` :program:`pt-table-checksum```\ will die. With this option, however, \ ` :program:`pt-table-checksum```\ will create the replicate table for you, using the database.table name given to - "--replicate". + :option:`--replicate`. The structure of the replicate table is the same as the suggested table - mentioned in "--replicate". Note that since ENGINE is not specified, the + mentioned in :option:`--replicate`. Note that since ENGINE is not specified, the replicate table will use the server's default storage engine. If you want to use a different engine, you need to create the table yourself. ---databases +.. option:: --databases short form: -d; type: hash; group: Filter @@ -918,15 +870,15 @@ This tool accepts additional command-line arguments. Refer to the ---databases-regex +.. option:: --databases-regex type: string - Only checksum databases whose names match this Perl regex. + Only checksum databases whose names match this *Perl* regex. ---defaults-file +.. option:: --defaults-file short form: -F; type: string; group: Connection @@ -935,12 +887,12 @@ This tool accepts additional command-line arguments. Refer to the ---empty-replicate-table +.. option:: --empty-replicate-table - DELETE all rows in the "--replicate" table before starting. + DELETE all rows in the :option:`--replicate` table before starting. - Issues a DELETE against the table given by "--replicate" before beginning - work. Ignored if "--replicate" is not specified. This can be useful to + Issues a DELETE against the table given by :option:`--replicate` before beginning + work. Ignored if :option:`--replicate` is not specified. This can be useful to remove entries related to tables that no longer exist, or just to clean out the results of a previous run. @@ -949,7 +901,7 @@ This tool accepts additional command-line arguments. Refer to the ---engines +.. option:: --engines short form: -e; type: hash; group: Filter @@ -957,53 +909,51 @@ This tool accepts additional command-line arguments. Refer to the ---explain +.. option:: --explain group: Output - Show, but do not execute, checksum queries (disables "--empty-replicate-table"). + Show, but do not execute, checksum queries (disables :option:`--empty-replicate-table`). ---explain-hosts +.. option:: --explain-hosts group: Help 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 + :program:`pt-table-checksum` parses DSNs from the command-line and how it will connect to those hosts. See "SPECIFYING HOSTS". ---float-precision +.. option:: --float-precision type: int Precision for \ ``FLOAT``\ and \ ``DOUBLE``\ number-to-string conversion. Causes FLOAT and DOUBLE values to be rounded to the specified number of digits after the - decimal point, with the ROUND() function in MySQL. This can help avoid + decimal point, with the ROUND() function in |MySQL|. This can help avoid checksum mismatches due to different floating-point representations of the same - values on different MySQL versions and hardware. The default is no rounding; - the values are converted to strings by the CONCAT() function, and MySQL chooses + values on different |MySQL| versions and hardware. The default is no rounding; + the values are converted to strings by the CONCAT() function, and |MySQL| chooses the string representation. If you specify a value of 2, for example, then the values 1.008 and 1.009 will be rounded to 1.01, and will checksum as equal. ---function +.. option:: --function type: string Hash function for checksums (FNV1A_64, MURMUR_HASH, SHA1, MD5, CRC32, etc). You can use this option to choose the cryptographic hash function used for - "--algorithm"=ACCUM or "--algorithm"=BIT_XOR. The default is to use - \ ``CRC32``\ , but \ ``MD5``\ and \ ``SHA1``\ also work, and you can use your own function, - such as a compiled UDF, if you wish. Whatever function you specify is run in - SQL, not in Perl, so it must be available to MySQL. + :option:`--algorithm=ACCUM` or :option:`--algorithm=BIT_XOR`. The default is to use + \ ``CRC32``\ , but \ ``MD5``\ and \ ``SHA1``\ also work, and you can use your own function, such as a compiled UDF, if you wish. Whatever function you specify is run in + SQL, not in *Perl* , so it must be available to |MySQL|. - The \ ``FNV1A_64``\ UDF mentioned in the benchmarks is much faster than \ ``MD5``\ . The - C++ source code is distributed with Maatkit. It is very simple to compile and + The \ ``FNV1A_64``\ UDF mentioned in the benchmarks is much faster than \ ``MD5``\ . The C++ source code is distributed with Maatkit. It is very simple to compile and install; look at the header in the source code for instructions. If it is installed, it is preferred over \ ``MD5``\ . You can also use the MURMUR_HASH function if you compile and install that as a UDF; the source is also @@ -1012,7 +962,7 @@ This tool accepts additional command-line arguments. Refer to the ---help +.. option:: --help group: Help @@ -1020,18 +970,18 @@ This tool accepts additional command-line arguments. Refer to the ---ignore-columns +.. option:: --ignore-columns type: Hash; group: Filter Ignore this comma-separated list of columns when calculating the checksum. This option only affects the checksum when using the ACCUM or BIT_XOR - "--algorithm". + :option:`--algorithm`. ---ignore-databases +.. option:: --ignore-databases type: Hash; group: Filter @@ -1039,15 +989,15 @@ This tool accepts additional command-line arguments. Refer to the ---ignore-databases-regex +.. option:: --ignore-databases-regex type: string - Ignore databases whose names match this Perl regex. + Ignore databases whose names match this *Perl* regex. ---ignore-engines +.. option:: --ignore-engines type: Hash; default: FEDERATED,MRG_MyISAM; group: Filter @@ -1055,7 +1005,7 @@ This tool accepts additional command-line arguments. Refer to the ---ignore-tables +.. option:: --ignore-tables type: Hash; group: Filter @@ -1065,81 +1015,79 @@ This tool accepts additional command-line arguments. Refer to the ---ignore-tables-regex +.. option:: --ignore-tables-regex type: string - Ignore tables whose names match the Perl regex. + Ignore tables whose names match the *Perl* regex. ---lock +.. option:: --lock - Lock on master until done on slaves (implies "--slave-lag"). + Lock on master until done on slaves (implies :option:`--slave-lag`). This option can help you to get a consistent read on a master and many slaves. - If you specify this option, pt-table-checksum will lock the table on the + If you specify this option, :program:`pt-table-checksum` will lock the table on the first server on the command line, which it assumes to be the master. It will keep this lock until the checksums complete on the other servers. - This option isn't very useful by itself, so you probably want to use "--wait" + This option isn't very useful by itself, so you probably want to use :option:`--wait` instead. Note: if you're checksumming a slave against its master, you should use - "--replicate". In that case, there's no need for locking, waiting, or any of + :option:`--replicate`. In that case, there's no need for locking, waiting, or any of that. ---max-lag +.. option:: --max-lag type: time; group: Throttle; default: 1s - Suspend checksumming if the slave given by "--check-slave-lag" lags. + Suspend checksumming if the slave given by :option:`--check-slave-lag` lags. - This option causes pt-table-checksum to look at the slave every time it's about + This option causes :program:`pt-table-checksum` to look at the slave every time it's about to checksum a chunk. If the slave's lag is greater than the option's value, or - if the slave isn't running (so its lag is NULL), pt-table-checksum sleeps for - "--check-interval" seconds and then looks at the lag again. It repeats until + if the slave isn't running (so its lag is NULL), :program:`pt-table-checksum` sleeps for + :option:`--check-interval` seconds and then looks at the lag again. It repeats until the slave is caught up, then proceeds to checksum the chunk. This option is useful to let you checksum data as fast as the slaves can handle - it, assuming the slave you directed pt-table-checksum to monitor is + it, assuming the slave you directed :program:`pt-table-checksum` to monitor is representative of all the slaves that may be replicating from this server. It - should eliminate the need for "--sleep" or "--sleep-coef". + should eliminate the need for :option:`--sleep` or :option:`--sleep-coef`. ---modulo +.. option:: --modulo type: int Do only every Nth chunk on chunked tables. This option lets you checksum only some chunks of the table. This is a useful - alternative to "--probability" when you want to be sure you get full coverage + alternative to :option:`--probability` when you want to be sure you get full coverage in some specified number of runs; for example, you can do only every 7th chunk, - and then use "--offset" to rotate the modulo every day of the week. + and then use :option:`--offset` to rotate the modulo every day of the week. - Just like with "--probability", a table that cannot be chunked is done every + Just like with :option:`--probability`, a table that cannot be chunked is done every time. - ---offset +.. option:: --offset type: string; default: 0 - Modulo offset expression for use with "--modulo". + Modulo offset expression for use with :option:`--modulo`. The argument may be an SQL expression, such as \ ``WEEKDAY(NOW())``\ (which returns - a number from 0 through 6). The argument is evaluated by MySQL. The result is - used as follows: if chunk_num % "--modulo" == "--offset", the chunk will + a number from 0 through 6). The argument is evaluated by |MySQL|. The result is + used as follows: if chunk_num % :option:`--modulo" == "--offset`, the chunk will be checksummed. - ---[no]optimize-xor +.. option:: --[no]optimize-xor default: yes @@ -1151,7 +1099,7 @@ This tool accepts additional command-line arguments. Refer to the With the optimization, the queries look like this in pseudo-code: - + .. code-block:: perl SELECT CONCAT( @@ -1162,7 +1110,7 @@ This tool accepts additional command-line arguments. Refer to the The exact positioning of user variables and calls to the hash function is - determined dynamically, and will vary between MySQL versions. Without the + determined dynamically, and will vary between |MySQL| versions. Without the optimization, it looks like this: @@ -1180,16 +1128,14 @@ This tool accepts additional command-line arguments. Refer to the columns, such as BLOB or TEXT columns, this might make a big difference. - ---password +.. option:: --password short form: -p; type: string; group: Connection Password to use when connecting. - ---pid +.. option:: --pid type: string @@ -1203,16 +1149,14 @@ This tool accepts additional command-line arguments. Refer to the contains no PID, then the script dies. - ---port +.. option:: --port short form: -P; type: int; group: Connection Port number to use for connection. - ---probability +.. option:: --probability type: int; default: 100 @@ -1224,51 +1168,46 @@ This tool accepts additional command-line arguments. Refer to the randomly sample bits of tables without checksumming the whole server. By default, if a table is not chunkable, it will be checksummed every time even when the probability is less than 100. You can override this with - "--single-chunk". + :option:`--single-chunk`. - See also "--modulo". + See also :option:`--modulo`. - ---progress +.. option:: --progress type: array; default: time,30 - Print progress reports to STDERR. Currently, this feature is only for when - "--throttle-method" waits for slaves to catch up. + Print progress reports to ``STDERR``. Currently, this feature is only for when + :option:`--throttle-method` waits for slaves to catch up. The value is a comma-separated list with two parts. The first part can be percentage, time, or iterations; the second part specifies how often an update should be printed, in percentage, seconds, or number of iterations. - ---quiet +.. option:: --quiet short form: -q; group: Output Do not print checksum results. - ---recheck +.. option:: --recheck - Re-checksum chunks that "--replicate-check" found to be different. + Re-checksum chunks that :option:`--replicate-check` found to be different. - ---recurse +.. option:: --recurse type: int; group: Throttle Number of levels to recurse in the hierarchy when discovering slaves. Default is infinite. - See "--recursion-method". + See :option:`--recursion-method`. - ---recursion-method +.. option:: --recursion-method type: string @@ -1287,13 +1226,12 @@ This tool accepts additional command-line arguments. Refer to the The processlist method is preferred because SHOW SLAVE HOSTS is not reliable. However, the hosts method is required if the server uses a non-standard - port (not 3306). Usually pt-table-checksum does the right thing and finds + port (not 3306). Usually :program:`pt-table-checksum` does the right thing and finds the slaves, but you may give a preferred method and it will be used first. If it doesn't find any slaves, the other methods will be tried. - ---replicate +.. option:: --replicate type: string @@ -1308,8 +1246,7 @@ This tool accepts additional command-line arguments. Refer to the When the queries are finished replicating, you can run a simple query on each slave to see which tables have differences from the master. With the - "--replicate-check" option, pt-table-checksum can run the query for you to - make it even easier. See "CONSISTENT CHECKSUMS" for details. + :option:`--replicate-check` option, :program:`pt-table-checksum` can run the query for you to make it even easier. See "CONSISTENT CHECKSUMS" for details. If you find tables that have differences, you can use the chunk boundaries in a WHERE clause with pt-table-sync to help repair them more efficiently. See @@ -1318,7 +1255,7 @@ This tool accepts additional command-line arguments. Refer to the The table must have at least these columns: db, tbl, chunk, boundaries, this_crc, master_crc, this_cnt, master_cnt. The table may be named anything you wish. Here is a suggested table structure, which is automatically used for - "--create-replicate-table" (MAGIC_create_replicate): + :option:`--create-replicate-table` (MAGIC_create_replicate): .. code-block:: perl @@ -1338,58 +1275,56 @@ This tool accepts additional command-line arguments. Refer to the Be sure to choose an appropriate storage engine for the checksum table. If you - are checksumming InnoDB tables, for instance, a deadlock will break replication + are checksumming |InnoDB| tables, for instance, a deadlock will break replication if the checksum table is non-transactional, because the transaction will still be written to the binlog. It will then replay without a deadlock on the slave and break replication with "different error on master and slave." This - is not a problem with pt-table-checksum, it's a problem with MySQL - replication, and you can read more about it in the MySQL manual. + is not a problem with :program:`pt-table-checksum`, it's a problem with |MySQL| + replication, and you can read more about it in the |MySQL| manual. - This works only with statement-based replication (pt-table-checksum will switch + This works only with statement-based replication :program:`pt-table-checksum` will switch the binlog format to STATEMENT for the duration of the session if your server uses row-based replication). In contrast to running the tool against multiple servers at once, using this option eliminates the complexities of synchronizing checksum queries across multiple servers, which normally requires locking and unlocking, waiting for - master binlog positions, and so on. Thus, it disables "--lock", "--wait", - and "--slave-lag" (but not "--check-slave-lag", which is a way to throttle - the execution speed). + master binlog positions, and so on. Thus, it disables :option:`--lock`, :option:`--wait`, and :option:`--slave-lag` (but not :option:`--check-slave-lag`, which is a way to throttle the execution speed). The checksum queries actually do a REPLACE into this table, so existing rows need not be removed before running. However, you may wish to do this anyway to remove rows related to tables that don't exist anymore. The - "--empty-replicate-table" option does this for you. + :option:`--empty-replicate-table` option does this for you. Since the table must be qualified with a database (e.g. \ ``db.checksums``\ ), - pt-table-checksum will only USE this database. This may be important if any + :program:`pt-table-checksum` will only USE this database. This may be important if any replication options are set because it could affect whether or not changes to the table are replicated. If the slaves have any --replicate-do-X or --replicate-ignore-X options, you should be careful not to checksum any databases or tables that exist on the master and not the slaves. Changes to such tables may not normally be executed - on the slaves because of the --replicate options, but the checksum queries + on the slaves because of the :option:`--replicate` options, but the checksum queries modify the contents of the table that stores the checksums, not the tables whose data you are checksumming. Therefore, these queries will be executed on the slave, and if the table or database you're checksumming does not exist, the queries will cause replication to fail. For more information on replication rules, see `http://dev.mysql.com/doc/en/replication-rules.html `_. - The table specified by "--replicate" will never be checksummed itself. + The table specified by :option:`--replicate` will never be checksummed itself. ---replicate-check +.. option:: --replicate-check type: int - Check results in "--replicate" table, to the specified depth. You must use + Check results in :option:`--replicate` table, to the specified depth. You must use this after you run the tool normally; it skips the checksum step and only checks results. It recursively finds differences recorded in the table given by - "--replicate". It recurses to the depth you specify: 0 is no recursion + :option:`--replicate`. It recurses to the depth you specify: 0 is no recursion (check only the server you specify), 1 is check the server and its slaves, 2 is check the slaves of its slaves, and so on. @@ -1398,53 +1333,47 @@ This tool accepts additional command-line arguments. Refer to the running the query so you don't have to do it manually. The output is one informational line per slave host, followed by the results - of the query, if any. If "--quiet" is specified, there is no output. If + of the query, if any. If :option:`--quiet` is specified, there is no output. If there are no differences between the master and any slave, there is no output. - If any slave has chunks that differ from the master, pt-table-checksum's + If any slave has chunks that differ from the master, :program:`pt-table-checksum`'s exit status is 1; otherwise it is 0. - This option makes \ ``pt-table-checksum``\ look for slaves by running \ ``SHOW - PROCESSLIST``\ . If it finds connections that appear to be from slaves, it derives + This option makes :program:`pt-table-checksum` look for slaves by running \ ``SHOW PROCESSLIST``\ . If it finds connections that appear to be from slaves, it derives connection information for each slave with the same default-and-override method described in "SPECIFYING HOSTS". - If \ ``SHOW PROCESSLIST``\ doesn't return any rows, \ ``pt-table-checksum``\ looks at - \ ``SHOW SLAVE HOSTS``\ instead. The host and port, and user and password if + If \ ``SHOW PROCESSLIST``\ doesn't return any rows, :program:`pt-table-checksum` looks at \ ``SHOW SLAVE HOSTS``\ instead. The host and port, and user and password if available, from \ ``SHOW SLAVE HOSTS``\ are combined into a DSN and used as the argument. This requires slaves to be configured with \ ``report-host``\ , \ ``report-port``\ and so on. - This requires the @@SERVER_ID system variable, so it works only on MySQL + This requires the @@SERVER_ID system variable, so it works only on |MySQL| 3.23.26 or newer. - ---replicate-database +.. option:: --replicate-database type: string - \ ``USE``\ only this database with "--replicate". By default, pt-table-checksum - executes USE to set its default database to the database that contains the table - it's currently working on. It changes its default database as it works on - different tables. This is is a best effort to avoid problems with replication + \ ``USE``\ only this database with :option:`--replicate`. By default, :program:`pt-table-checksum` executes USE to set its default database to the database that contains the table it's currently working on. It changes its default database as it works on different tables. This is is a best effort to avoid problems with replication filters such as binlog_ignore_db and replicate_ignore_db. However, replication filters can create a situation where there simply is no one right way to do things. Some statements might not be replicated, and others might cause replication to fail on the slaves. In such cases, it is up to the user to specify a safe default database. This option specifies a default database that - pt-table-checksum selects with USE, and never changes afterwards. See also - . + :program:`pt-table-checksum` selects with USE, and never changes afterwards. See also + :option:`--[no]check-replication-filters`. ---resume +.. option:: --resume type: string Resume checksum using given output file from a previously interrupted run. The given output file should be the literal output from a previous run of - \ ``pt-table-checksum``\ . For example: + :program:`pt-table-checksum`. For example: .. code-block:: perl @@ -1454,65 +1383,58 @@ This tool accepts additional command-line arguments. Refer to the The command line options given to the first run and the resumed run must - be identical (except, of course, for --resume). If they are not, the result + be identical (except, of course, for :option:`--resume`). If they are not, the result will be unpredictable and probably wrong. - "--resume" does not work with "--replicate"; for that, use - "--resume-replicate". + :option:`--resume" does not work with "--replicate`; for that, use :option:`--resume-replicate`. ---resume-replicate +.. option:: --resume-replicate - Resume "--replicate". + Resume :option:`--replicate`. - This option resumes a previous checksum operation using "--replicate". - It is like "--resume" but does not require an output file. Instead, - it uses the checksum table given to "--replicate" to determine where to + This option resumes a previous checksum operation using :option:`--replicate`. + It is like :option:`--resume` but does not require an output file. Instead, + it uses the checksum table given to :option:`--replicate` to determine where to resume the checksum operation. ---save-since +.. option:: --save-since - When "--arg-table" and "--since" are given, save the current "--since" - value into that table's \ ``since``\ column after checksumming. In this way you can - incrementally checksum tables by starting where the last one finished. + When :option:`--arg-table` and :option:`--since` are given, save the current :option:`--since` value into that table's \ ``since``\ column after checksumming. In this way you can incrementally checksum tables by starting where the last one finished. The value to be saved could be the current timestamp, or it could be the maximum - existing value of the column given by "--since-column". It depends on what - options are in effect. See the description of "--since" to see how + existing value of the column given by :option:`--since-column`. It depends on what + options are in effect. See the description of :option:`--since` to see how timestamps are different from ordinary values. - ---schema +.. option:: --schema Checksum \ ``SHOW CREATE TABLE``\ instead of table data. - ---separator +.. option:: --separator type: string; default: # The separator character used for CONCAT_WS(). This character is used to join the values of columns when checksumming with - "--algorithm" of BIT_XOR or ACCUM. + :option:`--algorithm` of BIT_XOR or ACCUM. - ---set-vars +.. option:: --set-vars type: string; default: wait_timeout=10000; group: Connection - Set these MySQL variables. Immediately after connecting to MySQL, this + Set these |MySQL| variables. Immediately after connecting to |MySQL|, this string will be appended to SET and executed. - ---since +.. option:: --since type: string @@ -1521,27 +1443,26 @@ This tool accepts additional command-line arguments. Refer to the If the table is chunk-able or nibble-able, this value will apply to the first column of the chunked or nibbled index. - This is not too different to "--where", but instead of universally applying a + This is not too different to :option:`--where`, but instead of universally applying a WHERE clause to every table, it selectively finds the right column to use and - applies it only if such a column is found. See also "--since-column". + applies it only if such a column is found. See also :option:`--since-column`. - The argument may be an expression, which is evaluated by MySQL. For example, + The argument may be an expression, which is evaluated by |MySQL|. For example, you can specify \ ``CURRENT_DATE - INTERVAL 7 DAY``\ to get the date of one week ago. A special bit of extra magic: if the value is temporal (looks like a date or datetime), then the table is checksummed only if the create time (or last - modified time, for tables that report the last modified time, such as MyISAM + modified time, for tables that report the last modified time, such as |MyISAM| tables) is newer than the value. In this sense it's not applied as a WHERE clause at all. - ---since-column +.. option:: --since-column type: string - The column name to be used for "--since". + The column name to be used for :option:`--since`. The default is for the tool to choose the best one automatically. If you specify a value, that will be used if possible; otherwise the best @@ -1549,18 +1470,16 @@ This tool accepts additional command-line arguments. Refer to the it is just ignored. - ---single-chunk +.. option:: --single-chunk - Permit skipping with "--probability" if there is only one chunk. + Permit skipping with :option:`--probability` if there is only one chunk. Normally, if a table isn't split into many chunks, it will always be - checksummed regardless of "--probability". This setting lets the + checksummed regardless of :option:`--probability`. This setting lets the probabilistic behavior apply to tables that aren't divided into chunks. - ---slave-lag +.. option:: --slave-lag group: Output @@ -1572,60 +1491,55 @@ This tool accepts additional command-line arguments. Refer to the master. You can inspect the results and make an educated guess whether any discrepancies on the slave are due to replication delay instead of corrupt data. - If you're using "--replicate", a slave that is delayed relative to the master + If you're using :option:`--replicate`, a slave that is delayed relative to the master does not invalidate the correctness of the results, so this option is disabled. - ---sleep +.. option:: --sleep type: int; group: Throttle Sleep time between checksums. - If this option is specified, pt-table-checksum will sleep the specified + If this option is specified, :program:`pt-table-checksum` will sleep the specified number of seconds between checksums. That is, it will sleep between every - table, and if you specify "--chunk-size", it will also sleep between chunks. + table, and if you specify :option:`--chunk-size`, it will also sleep between chunks. - This is a very crude way to throttle checksumming; see "--sleep-coef" and - "--check-slave-lag" for techniques that permit greater control. + This is a very crude way to throttle checksumming; see :option:`--sleep-coef` and + :option:`--check-slave-lag` for techniques that permit greater control. - ---sleep-coef +.. option:: --sleep-coef type: float; group: Throttle - Calculate "--sleep" as a multiple of the last checksum time. + Calculate :option:`--sleep` as a multiple of the last checksum time. - If this option is specified, pt-table-checksum will sleep the amount of + If this option is specified, :program:`pt-table-checksum` will sleep the amount of time elapsed during the previous checksum, multiplied by the specified - coefficient. This option is ignored if "--sleep" is specified. + coefficient. This option is ignored if :option:`--sleep` is specified. This is a slightly more sophisticated way to throttle checksum speed: sleep a varying amount of time between chunks, depending on how long the chunks are - taking. Even better is to use "--check-slave-lag" if you're checksumming + taking. Even better is to use :option:`--check-slave-lag` if you're checksumming master/slave replication. - ---socket +.. option:: --socket short form: -S; type: string; group: Connection Socket file to use for connection. - ---tab +.. option:: --tab group: Output Print tab-separated output, not column-aligned output. - ---tables +.. option:: --tables short form: -t; type: hash; group: Filter @@ -1634,33 +1548,30 @@ This tool accepts additional command-line arguments. Refer to the Table names may be qualified with the database name. - ---tables-regex +.. option:: --tables-regex type: string - Only checksum tables whose names match this Perl regex. + Only checksum tables whose names match this *Perl* regex. - ---throttle-method +.. option:: --throttle-method type: string; default: none; group: Throttle - Throttle checksumming when doing "--replicate". + Throttle checksumming when doing :option:`--replicate`. - At present there is only one method: \ ``slavelag``\ . When "--replicate" is - used, pt-table-checksum automatically sets "--throttle-method" to + At present there is only one method: \ ``slavelag``\ . When :option:`--replicate` is + used, :program:`pt-table-checksum` automatically sets :option:`--throttle-method` to \ ``slavelag``\ and discovers every slave and throttles checksumming if any slave - lags more than "--max-lag". Specify \ ``-throttle-method none``\ to disable - this behavior completely, or specify "--check-slave-lag" and - pt-table-checksum will only check that slave. + lags more than :option:`--max-lag`. Specify \ ``-throttle-method none``\ to disable + this behavior completely, or specify :option:`--check-slave-lag` and + :program:`pt-table-checksum` will only check that slave. - See also "--recurse" and "--recursion-method". + See also :option:`--recurse` and :option:`--recursion-method`. - ---trim +.. option:: --trim Trim \ ``VARCHAR``\ columns (helps when comparing 4.1 to >= 5.0). @@ -1668,20 +1579,19 @@ This tool accepts additional command-line arguments. Refer to the modes. This is useful when you don't care about the trailing space differences between - MySQL versions which vary in their handling of trailing spaces. MySQL 5.0 and + |MySQL| versions which vary in their handling of trailing spaces. |MySQL| 5.0 and later all retain trailing spaces in \ ``VARCHAR``\ , while previous versions would remove them. - ---unchunkable-tables +.. option:: --unchunkable-tables group: Safety - Checksum tables that cannot be chunked when "--chunk-size" is specified. + Checksum tables that cannot be chunked when :option:`--chunk-size` is specified. - By default pt-table-checksum will not checksum a table that cannot be chunked - when "--chunk-size" is specified because this might result in a huge, + By default :program:`pt-table-checksum` will not checksum a table that cannot be chunked + when :option:`--chunk-size` is specified because this might result in a huge, non-chunkable table being checksummed in one huge, memory-intensive chunk. Specifying this option allows checksumming tables that cannot be chunked. @@ -1689,33 +1599,28 @@ This tool accepts additional command-line arguments. Refer to the are not so large that they will cause the tool to consume too much memory or CPU. - See also "--chunk-size-limit". + See also :option:`--chunk-size-limit`. - ---[no]use-index +.. option:: --[no]use-index default: yes Add FORCE INDEX hints to SQL statements. - By default \ ``pt-table-checksum``\ adds an index hint (\ ``FORCE INDEX``\ for MySQL - v4.0.9 and newer, \ ``USE INDEX``\ for older MySQL versions) to each SQL statement - to coerce MySQL into using the "--chunk-index" (whether the index is + By default \ ` :program:`pt-table-checksum```\ adds an index hint (\ ``FORCE INDEX``\ for |MySQL| v4.0.9 and newer, \ ``USE INDEX``\ for older |MySQL| versions) to each SQL statement to coerce |MySQL| into using the :option:`--chunk-index` (whether the index is specified by the option or auto-detected). Specifying \ ``--no-use-index``\ causes - \ ``pt-table-checksum``\ to omit index hints. + :program:`pt-table-checksum` to omit index hints. - ---user +.. option:: --user short form: -u; type: string; group: Connection User for login if not current user. - ---[no]verify +.. option:: --[no]verify default: yes @@ -1724,7 +1629,7 @@ This tool accepts additional command-line arguments. Refer to the This option runs a trivial checksum on all servers to ensure they have compatible CONCAT_WS() and cryptographic hash functions. - Versions of MySQL before 4.0.14 will skip empty strings and NULLs in + Versions of |MySQL| before 4.0.14 will skip empty strings and NULLs in CONCAT_WS, and others will only skip NULLs. The two kinds of behavior will produce different results if you have any columns containing the empty string in your table. If you know you don't (for instance, all columns are @@ -1733,7 +1638,7 @@ This tool accepts additional command-line arguments. Refer to the ---version +.. option:: --version group: Help @@ -1741,16 +1646,16 @@ This tool accepts additional command-line arguments. Refer to the ---wait +.. option:: --wait short form: -w; type: time - Wait this long for slaves to catch up to their master (implies "--lock" - "--slave-lag"). + Wait this long for slaves to catch up to their master (implies :option:`--lock` + :option:`--slave-lag`). Note: the best way to verify that a slave is in sync with its master is to use - "--replicate" instead. The "--wait" option is really only useful if - you're trying to compare masters and slaves without using "--replicate", + :option:`--replicate" instead. The "--wait` option is really only useful if + you're trying to compare masters and slaves without using :option:`--replicate`, which is possible but complex and less efficient in some ways. This option helps you get a consistent checksum across a master server and its @@ -1768,11 +1673,11 @@ This tool accepts additional command-line arguments. Refer to the ---where +.. option:: --where type: string - Do only rows matching this \ ``WHERE``\ clause (disallows "--algorithm" CHECKSUM). + Do only rows matching this \ ``WHERE``\ clause (disallows :option:`--algorithm` CHECKSUM). You can use this option to limit the checksum to only part of the table. This is particularly useful if you have append-only tables and don't want to @@ -1790,12 +1695,12 @@ This tool accepts additional command-line arguments. Refer to the ---[no]zero-chunk +.. option:: --[no]zero-chunk default: yes Add a chunk for rows with zero or zero-equivalent values. The only has an - effect when "--chunk-size" is specified. The purpose of the zero chunk + effect when :option:`--chunk-size` is specified. The purpose of the zero chunk is to capture a potentially large number of zero values that would imbalance the size of the first chunk. For example, if a lot of negative numbers were inserted into an unsigned integer column causing them to be stored as zeros, @@ -1805,9 +1710,8 @@ This tool accepts additional command-line arguments. Refer to the -*********** DSN OPTIONS -*********** +=========== These DSN options are used to create a DSN. Each option is given like @@ -1817,7 +1721,7 @@ if the value contains whitespace it must be quoted. DSN options are comma-separated. See the percona-toolkit manpage for full details. -\* A + * ``A`` dsn: charset; copy: yes @@ -1825,7 +1729,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* D + * ``D`` dsn: database; copy: yes @@ -1833,7 +1737,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* F + * ``F`` dsn: mysql_read_default_file; copy: yes @@ -1841,7 +1745,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* h + * ``h`` dsn: host; copy: yes @@ -1849,7 +1753,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* p + * ``p`` dsn: password; copy: yes @@ -1857,7 +1761,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* P + * ``p`` dsn: port; copy: yes @@ -1865,7 +1769,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* S + * ``S`` dsn: mysql_socket; copy: yes @@ -1873,7 +1777,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* u + * ``u`` dsn: user; copy: yes @@ -1882,12 +1786,11 @@ comma-separated. See the percona-toolkit manpage for full details. -*********** ENVIRONMENT -*********** +=========== -The environment variable \ ``PTDEBUG``\ enables verbose debugging output to STDERR. +The environment variable \ ``PTDEBUG``\ enables verbose debugging output to ``STDERR``. To enable debugging and capture all output to a file, run the tool like: @@ -1900,137 +1803,47 @@ Be careful: debugging output is voluminous and can generate several megabytes of output. -******************* SYSTEM REQUIREMENTS -******************* +=================== -You need Perl, DBI, DBD::mysql, and some core packages that ought to be -installed in any reasonably new version of Perl. +You need *Perl* , ``DBI``, ``DBD::mysql``, and some core packages that ought to be +installed in any reasonably new version of *Perl* . -**** BUGS -**** +==== For a list of known bugs, see `http://www.percona.com/bugs/pt-table-checksum `_. 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* -Baron Schwartz - - -*************** ACKNOWLEDGMENTS -*************** +=============== + +*Claus Jeppesen*, *Francois Saint-Jacques*, *Giuseppe Maxia*, *Heikki Tuuri*, +*James Briggs*, *Martin Friebe*, and *Sergey Zhuravlev* -Claus Jeppesen, Francois Saint-Jacques, Giuseppe Maxia, Heikki Tuuri, -James Briggs, Martin Friebe, and Sergey Zhuravlev - - -********************* -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 2007-2011 Baron Schwartz, 2011 Percona Inc. +This program is copyright 2007-2011 *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 -******* +======= - -pt-table-checksum 1.0.1 +:program:`pt-table-checksum` 1.0.1 diff --git a/docs/user/pt-table-sync.rst b/docs/user/source/pt-table-sync.rst similarity index 73% rename from docs/user/pt-table-sync.rst rename to docs/user/source/pt-table-sync.rst index b84f0735..3e4eaf8b 100644 --- a/docs/user/pt-table-sync.rst +++ b/docs/user/source/pt-table-sync.rst @@ -1,27 +1,30 @@ +.. program:: pt-table-sync -############# -pt-table-sync -############# +========================== + :program:`pt-table-sync` +========================== .. highlight:: perl -**** NAME -**** +==== + + :program:`pt-table-sync` - Synchronize |MySQL| table data efficiently. -pt-table-sync - Synchronize MySQL table data efficiently. - - -******** SYNOPSIS -******** +======== -Usage: pt-table-sync [OPTION...] DSN [DSN...] +Usage +----- -pt-table-sync synchronizes data efficiently between MySQL tables. +:: + + pt-table-sync [OPTION...] DSN [DSN...] + +:program:`pt-table-sync` synchronizes data efficiently between |MySQL| tables. This tool changes data, so for maximum safety, you should back up your data before you use it. When synchronizing a server that is a replication slave with @@ -95,9 +98,8 @@ through replication and change master1's data: -***** RISKS -***** +===== The following section is included to inform users about the potential risks, @@ -107,12 +109,12 @@ tools) and those created by bugs. With great power comes great responsibility! This tool changes data, so it is a good idea to back up your data. It is also very powerful, which means it is -very complex, so you should run it with the "--dry-run" option to see what it +very complex, so you should run it with the :option:`--dry-run` option to see what it will do, until you're familiar with its operation. If you want to see which -rows are different, without changing any data, use "--print" instead of -"--execute". +rows are different, without changing any data, use :option:`--print` instead of +:option:`--execute`. -Be careful when using pt-table-sync in any master-master setup. Master-master +Be careful when using :program:`pt-table-sync` in any master-master setup. Master-master replication is inherently tricky, and it's easy to make mistakes. You need to be sure you're using the tool correctly for master-master replication. See the "SYNOPSIS" for the overview of the correct usage. @@ -126,7 +128,7 @@ unique index. Although it can synchronize data in tables lacking a primary key or unique index, it might be best to synchronize that data by another means. At the time of this release, there is a potential bug using -"--lock-and-rename" with MySQL 5.1, a bug detecting certain differences, +:option:`--lock-and-rename` with |MySQL| 5.1, a bug detecting certain differences, a bug using ROUND() across different platforms, and a bug mixing collations. The authoritative source for updated information is always the online issue @@ -134,22 +136,20 @@ 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-table-sync `_. -See also "BUGS" for more information on filing bugs and getting help. +See also :ref:`bugs` for more information on filing bugs and getting help. -*********** DESCRIPTION -*********** +=========== - -pt-table-sync does one-way and bidirectional synchronization of table data. +:program:`pt-table-sync` does one-way and bidirectional synchronization of table data. It does \ **not**\ synchronize table structures, indexes, or any other schema objects. The following describes one-way synchronization. "BIDIRECTIONAL SYNCING" is described later. This tool is complex and functions in several different ways. To use it safely and effectively, you should understand three things: the purpose -of "--replicate", finding differences, and specifying hosts. These +of :option:`--replicate`, finding differences, and specifying hosts. These three concepts are closely related and determine how the tool will run. The following is the abbreviated logic: @@ -177,23 +177,23 @@ The following is the abbreviated logic: find tables, filtering with --databases etc, and sync each DSN to the first. +:program:`pt-table-sync` can run in one of two ways: with :option:`--replicate` or without. -pt-table-sync can run in one of two ways: with "--replicate" or without. -The default is to run without "--replicate" which causes pt-table-sync +The default is to run without :option:`--replicate` which causes :program:`pt-table-sync` to automatically find differences efficiently with one of several algorithms (see "ALGORITHMS"). Alternatively, the value of -"--replicate", if specified, causes pt-table-sync to use the differences +:option:`--replicate`, if specified, causes :program:`pt-table-sync` to use the differences already found by having previously ran pt-table-checksum with its own \ ``--replicate``\ option. Strictly speaking, you don't need to use -"--replicate" because pt-table-sync can find differences, but many -people use "--replicate" if, for example, they checksum regularly -using pt-table-checksum then fix differences as needed with pt-table-sync. +:option:`--replicate` because :program:`pt-table-sync` can find differences, but many +people use :option:`--replicate` if, for example, they checksum regularly +using pt-table-checksum then fix differences as needed with :program:`pt-table-sync`. If you're unsure, read each tool's documentation carefully and decide for yourself, or consult with an expert. -Regardless of whether "--replicate" is used or not, you need to specify -which hosts to sync. There are two ways: with "--sync-to-master" or -without. Specifying "--sync-to-master" makes pt-table-sync expect +Regardless of whether :option:`--replicate` is used or not, you need to specify +which hosts to sync. There are two ways: with :option:`--sync-to-master` or +without. Specifying :option:`--sync-to-master` makes :program:`pt-table-sync` expect one and only slave DSN on the command line. The tool will automatically discover the slave's master and sync it so that its data is the same as its master. This is accomplished by making changes on the master which @@ -203,23 +203,22 @@ slave, if there are other slaves on the same master, they will receive via replication the changes intended for the slave that you're trying to sync. -Alternatively, if you do not specify "--sync-to-master", the first +Alternatively, if you do not specify :option:`--sync-to-master`, the first DSN given on the command line is the source host. There is only ever -one source host. If you do not also specify "--replicate", then you +one source host. If you do not also specify :option:`--replicate`, then you must specify at least one other DSN as the destination host. There can be one or more destination hosts. Source and destination hosts -must be independent; they cannot be in the same replication topology. -pt-table-sync will die with an error if it detects that a destination +must be independent; they cannot be in the same replication topology. :program:`pt-table-sync` will die with an error if it detects that a destination host is a slave because changes are written directly to destination hosts (and it's not safe to write directly to slaves). Or, if you specify -"--replicate" (but not "--sync-to-master") then pt-table-sync expects +:option:`--replicate" (but not "--sync-to-master`) then :program:`pt-table-sync` expects one and only one master DSN on the command line. The tool will automatically discover all the master's slaves and sync them to the master. This is the only way to sync several (all) slaves at once (because -"--sync-to-master" only specifies one slave). +:option:`--sync-to-master` only specifies one slave). Each host on the command line is specified as a DSN. The first DSN -(or only DSN for cases like "--sync-to-master") provides default values +(or only DSN for cases like :option:`--sync-to-master`) provides default values for other DSNs, whether those other DSNs are specified on the command line or auto-discovered by the tool. So in this example, @@ -230,16 +229,14 @@ or auto-discovered by the tool. So in this example, the host2 DSN inherits the \ ``u``\ and \ ``p``\ DSN parts from the host1 DSN. -Use the "--explain-hosts" option to see how pt-table-sync will interpret -the DSNs given on the command line. +Use the :option:`--explain-hosts` option to see how :program:`pt-table-sync` will interpret the DSNs given on the command line. -****** OUTPUT -****** +====== -If you specify the "--verbose" option, you'll see information about the +If you specify the :option:`--verbose` option, you'll see information about the differences between the tables. There is one row per table. Each server is printed separately. For example, @@ -257,12 +254,12 @@ for this table started at 13:00:00 and ended 17 seconds later (times taken from \ ``NOW()``\ on the source host). Because differences were found, its "EXIT STATUS" was 2. -If you specify the "--print" option, you'll see the actual SQL statements -that the script uses to synchronize the table if "--execute" is also +If you specify the :option:`--print` option, you'll see the actual SQL statements +that the script uses to synchronize the table if :option:`--execute` is also specified. -If you want to see the SQL statements that pt-table-sync is using to select -chunks, nibbles, rows, etc., then specify "--print" once and "--verbose" +If you want to see the SQL statements that :program:`pt-table-sync` is using to select +chunks, nibbles, rows, etc., then specify :option:`--print` once and :option:`--verbose` twice. Be careful though: this can print a lot of SQL statements. There are cases where no combination of \ ``INSERT``\ , \ ``UPDATE``\ or \ ``DELETE``\ @@ -287,9 +284,8 @@ automatically handled after the first index violation, so you don't have to worry about it. -****************** REPLICATION SAFETY -****************** +================== Synchronizing a replication master and slave safely is a non-trivial problem, in @@ -303,42 +299,39 @@ However, this works only if it's possible to REPLACE into the table on the master. REPLACE works only if there's a unique index on the table (otherwise it just acts like an ordinary INSERT). -If your table has unique keys, you should use the "--sync-to-master" and/or -"--replicate" options to sync a slave to its master. This will generally do +If your table has unique keys, you should use the :option:`--sync-to-master` and/or +:option:`--replicate` options to sync a slave to its master. This will generally do the right thing. When there is no unique key on the table, there is no choice -but to change the data on the slave, and pt-table-sync will detect that you're +but to change the data on the slave, and :program:`pt-table-sync` will detect that you're trying to do so. It will complain and die unless you specify -\ ``--no-check-slave``\ (see "--[no]check-slave"). +\ ``--no-check-slave``\ (see :option:`--[no]check-slave`). If you're syncing a table without a primary or unique key on a master-master pair, you must change the data on the destination server. Therefore, you need -to specify \ ``--no-bin-log``\ for safety (see "--[no]bin-log"). If you don't, +to specify \ ``--no-bin-log``\ for safety (see :option:`--[no]bin-log`). If you don't, the changes you make on the destination server will replicate back to the source server and change the data there! The generally safe thing to do on a master-master pair is to use the -"--sync-to-master" option so you don't change the data on the destination -server. You will also need to specify \ ``--no-check-slave``\ to keep -pt-table-sync from complaining that it is changing data on a slave. +:option:`--sync-to-master` option so you don't change the data on the destination +server. You will also need to specify \ ``--no-check-slave``\ to keep :program:`pt-table-sync` from complaining that it is changing data on a slave. -********** ALGORITHMS -********** +========== - -pt-table-sync has a generic data-syncing framework which uses different +:program:`pt-table-sync` has a generic data-syncing framework which uses different algorithms to find differences. The tool automatically chooses the best algorithm for each table based on indexes, column types, and the algorithm -preferences specified by "--algorithms". The following algorithms are +preferences specified by :option:`--algorithms`. The following algorithms are available, listed in their default order of preference: -Chunk + * ``Chunk`` Finds an index whose first column is numeric (including date and time types), and divides the column's range of values into chunks of approximately - "--chunk-size" rows. Syncs a chunk at a time by checksumming the entire + :option:`--chunk-size` rows. Syncs a chunk at a time by checksumming the entire chunk. If the chunk differs on the source and destination, checksums each chunk's rows individually to find the rows that differ. @@ -353,9 +346,9 @@ Chunk -Nibble + * ``Nibble`` - Finds an index and ascends the index in fixed-size nibbles of "--chunk-size" + Finds an index and ascends the index in fixed-size nibbles of :option:`--chunk-size` rows, using a non-backtracking algorithm (see pt-archiver for more on this algorithm). It is very similar to "Chunk", but instead of pre-calculating the boundaries of each piece of the table based on index cardinality, it uses @@ -369,7 +362,7 @@ Nibble -GroupBy + * ``GroupBy`` Selects the entire table grouped by all columns, with a COUNT(\*) column added. Compares all columns, and if they're the same, compares the COUNT(\*) column's @@ -378,7 +371,7 @@ GroupBy -Stream + * ``Stream`` Selects the entire table in one big stream and compares all columns. Selects all columns. Much less efficient than the other algorithms, but works when @@ -386,7 +379,7 @@ Stream -Future Plans + * ``Future Plans`` Possibilities for future algorithms are TempTable (what I originally called bottom-up in earlier versions of this tool), DrillDown (what I originally @@ -399,9 +392,8 @@ Future Plans -********************* BIDIRECTIONAL SYNCING -********************* +===================== Bidirectional syncing is a new, experimental feature. To make it work @@ -443,20 +435,20 @@ source and its values are used to update the other row. There are subtle differences between three columns used to achieve bidirectional syncing that you should be familiar with: chunk column -("--chunk-column"), comparison column(s) ("--columns"), and conflict -column ("--conflict-column"). The chunk column is only used to chunk the +(:option:`--chunk-column"), comparison column(s) ("--columns`), and conflict +column (:option:`--conflict-column`). The chunk column is only used to chunk the table; e.g. "WHERE id >= 5 AND id < 10". Chunks are checksummed and when chunk checksums reveal a difference, the tool selects the rows in that -chunk and checksums the "--columns" for each row. If a column checksum +chunk and checksums the :option:`--columns` for each row. If a column checksum differs, the rows have one or more conflicting column values. In a traditional unidirectional sync, the conflict is a moot point because it can be resolved simply by updating the entire destination row with the source -row's values. In a bidirectional sync, however, the "--conflict-column" +row's values. In a bidirectional sync, however, the :option:`--conflict-column` (in accordance with other \ ``--conflict-\*``\ options list below) is compared to determine which row is "correct" or "authoritative"; this row becomes the "source". -To sync all three servers completely, two runs of pt-table-sync are required. +To sync all three servers completely, two runs of :program:`pt-table-sync` are required. The first run syncs c1 and r1, then syncs c1 and r2 including any changes from r1. At this point c1 and r2 are completely in sync, but r1 is missing any changes from r2 because c1 didn't have these changes when it and r1 @@ -473,9 +465,8 @@ this example would be ran twice like: pt-table-sync --bidirectional h=c1 h=r1 h=r2 -The "--bidirectional" option enables this feature and causes various -sanity checks to be performed. You must specify other options that tell -pt-table-sync how to resolve conflicts for same but differing rows. +The :option:`--bidirectional` option enables this feature and causes various +sanity checks to be performed. You must specify other options that tell :program:`pt-table-sync` how to resolve conflicts for same but differing rows. These options are: @@ -488,9 +479,9 @@ These options are: * --conflict-error"> (optional) -Use "--print" to test this option before "--execute". The printed +Use :option:`--print" to test this option before "--execute`. The printed SQL statements will have comments saying on which host the statement -would be executed if you used "--execute". +would be executed if you used :option:`--execute`. Technical side note: the first DSN is always the "left" server and the other DSNs are always the "right" server. Since either server can become the source @@ -500,13 +491,12 @@ this because the first DSN is always to the left of the other server DSNs on the command line. -*********** EXIT STATUS -*********** +=========== The following are the exit statuses (also called return values, or return codes) -when pt-table-sync finishes and exits. +when :program:`pt-table-sync` finishes and exits. .. code-block:: perl @@ -520,38 +510,36 @@ when pt-table-sync finishes and exits. -******* OPTIONS -******* +======= -Specify at least one of "--print", "--execute", or "--dry-run". +Specify at least one of :option:`--print`, :option:`--execute`, or :option:`--dry-run`. -"--where" and "--replicate" are mutually exclusive. +:option:`--where` and :option:`--replicate` are mutually exclusive. -This tool accepts additional command-line arguments. Refer to the -"SYNOPSIS" and usage information for details. +This tool accepts additional command-line arguments. Refer to the "SYNOPSIS" and usage information for details. ---algorithms +.. option:: --algorithms type: string; default: Chunk,Nibble,GroupBy,Stream Algorithm to use when comparing the tables, in order of preference. - For each table, pt-table-sync will check if the table can be synced with + For each table, :program:`pt-table-sync` will check if the table can be synced with the given algorithms in the order that they're given. The first algorithm that can sync the table is used. See "ALGORITHMS". ---ask-pass +.. option:: --ask-pass - Prompt for a password when connecting to MySQL. + Prompt for a password when connecting to |MySQL|. ---bidirectional +.. option:: --bidirectional Enable bidirectional sync between first and subsequent hosts. @@ -559,7 +547,7 @@ This tool accepts additional command-line arguments. Refer to the ---[no]bin-log +.. option:: --[no]bin-log default: yes @@ -569,69 +557,69 @@ This tool accepts additional command-line arguments. Refer to the ---buffer-in-mysql +.. option:: --buffer-in-mysql - Instruct MySQL to buffer queries in its memory. + Instruct |MySQL| to buffer queries in its memory. This option adds the \ ``SQL_BUFFER_RESULT``\ option to the comparison queries. - This causes MySQL to execute the queries and place them in a temporary table - internally before sending the results back to pt-table-sync. The advantage of - this strategy is that pt-table-sync can fetch rows as desired without using a - lot of memory inside the Perl process, while releasing locks on the MySQL table + This causes |MySQL| to execute the queries and place them in a temporary table + internally before sending the results back to :program:`pt-table-sync`. The advantage of + this strategy is that :program:`pt-table-sync` can fetch rows as desired without using a + lot of memory inside the *Perl* process, while releasing locks on the |MySQL| table (to reduce contention with other queries). The disadvantage is that it uses - more memory on the MySQL server instead. + more memory on the |MySQL| server instead. - You probably want to leave "--[no]buffer-to-client" enabled too, because - buffering into a temp table and then fetching it all into Perl's memory is + You probably want to leave :option:`--[no]buffer-to-client` enabled too, because + buffering into a temp table and then fetching it all into *Perl* 's memory is probably a silly thing to do. This option is most useful for the GroupBy and Stream algorithms, which may fetch a lot of data from the server. ---[no]buffer-to-client +.. option:: --[no]buffer-to-client default: yes - Fetch rows one-by-one from MySQL while comparing. + Fetch rows one-by-one from |MySQL| while comparing. - This option enables \ ``mysql_use_result``\ which causes MySQL to hold the selected + This option enables \ ``mysql_use_result``\ which causes |MySQL| to hold the selected rows on the server until the tool fetches them. This allows the tool to use less memory but may keep the rows locked on the server longer. If this option is disabled by specifying \ ``--no-buffer-to-client``\ then - \ ``mysql_store_result``\ is used which causes MySQL to send all selected rows to + \ ``mysql_store_result``\ is used which causes |MySQL| to send all selected rows to the tool at once. This may result in the results "cursor" being held open for a shorter time on the server, but if the tables are large, it could take a long time anyway, and use all your memory. For most non-trivial data sizes, you want to leave this option enabled. - This option is disabled when "--bidirectional" is used. + This option is disabled when :option:`--bidirectional` is used. ---charset +.. option:: --charset short form: -A; type: string - Default character set. If the value is utf8, sets Perl's binmode on - STDOUT to utf8, passes the mysql_enable_utf8 option to DBD::mysql, and - runs SET NAMES UTF8 after connecting to MySQL. Any other value sets - binmode on STDOUT without the utf8 layer, and runs SET NAMES after - connecting to MySQL. + Default character set. If the value is utf8, sets *Perl* 's binmode on + ``STDOUT`` to utf8, passes the mysql_enable_utf8 option to ``DBD::mysql``, and + runs SET NAMES UTF8 after connecting to |MySQL|. Any other value sets + binmode on ``STDOUT`` without the utf8 layer, and runs SET NAMES after + connecting to |MySQL|. ---[no]check-master +.. option:: --[no]check-master default: yes - With "--sync-to-master", try to verify that the detected + With :option:`--sync-to-master`, try to verify that the detected master is the real master. ---[no]check-privileges +.. option:: --[no]check-privileges default: yes @@ -639,33 +627,33 @@ This tool accepts additional command-line arguments. Refer to the ---[no]check-slave +.. option:: --[no]check-slave default: yes Check whether the destination server is a slave. If the destination server is a slave, it's generally unsafe to make changes on - it. However, sometimes you have to; "--replace" won't work unless there's a + it. However, sometimes you have to; :option:`--replace` won't work unless there's a unique index, for example, so you can't make changes on the master in that - scenario. By default pt-table-sync will complain if you try to change data on + scenario. By default :program:`pt-table-sync` will complain if you try to change data on a slave. Specify \ ``--no-check-slave``\ to disable this check. Use it at your own risk. ---[no]check-triggers +.. option:: --[no]check-triggers default: yes Check that no triggers are defined on the destination table. - Triggers were introduced in MySQL v5.0.2, so for older versions this option + Triggers were introduced in |MySQL| v5.0.2, so for older versions this option has no effect because triggers will not be checked. ---chunk-column +.. option:: --chunk-column type: string @@ -673,7 +661,7 @@ This tool accepts additional command-line arguments. Refer to the ---chunk-index +.. option:: --chunk-index type: string @@ -681,7 +669,7 @@ This tool accepts additional command-line arguments. Refer to the ---chunk-size +.. option:: --chunk-size type: string; default: 1000 @@ -694,7 +682,7 @@ This tool accepts additional command-line arguments. Refer to the ---columns +.. option:: --columns short form: -c; type: array @@ -702,7 +690,7 @@ This tool accepts additional command-line arguments. Refer to the ---config +.. option:: --config type: Array @@ -711,31 +699,31 @@ This tool accepts additional command-line arguments. Refer to the ---conflict-column +.. option:: --conflict-column type: string - Compare this column when rows conflict during a "--bidirectional" sync. + Compare this column when rows conflict during a :option:`--bidirectional` sync. When a same but differing row is found the value of this column from each - row is compared according to "--conflict-comparison", "--conflict-value" - and "--conflict-threshold" to determine which row has the correct data and + row is compared according to :option:`--conflict-comparison`, :option:`--conflict-value` + and :option:`--conflict-threshold` to determine which row has the correct data and becomes the source. The column can be any type for which there is an - appropriate "--conflict-comparison" (this is almost all types except, for + appropriate :option:`--conflict-comparison` (this is almost all types except, for example, blobs). - This option only works with "--bidirectional". + This option only works with :option:`--bidirectional`. See "BIDIRECTIONAL SYNCING" for more information. ---conflict-comparison +.. option:: --conflict-comparison type: string - Choose the "--conflict-column" with this property as the source. + Choose the :option:`--conflict-column` with this property as the source. - The option affects how the "--conflict-column" values from the conflicting + The option affects how the :option:`--conflict-column` values from the conflicting rows are compared. Possible comparisons are one of these MAGIC_comparisons: @@ -750,16 +738,16 @@ This tool accepts additional command-line arguments. Refer to the greatest Greatest numerical "--conflict-column value least Least numerical --conflict-column value equals --conflict-column value equal to --conflict-value - matches --conflict-column value matching Perl regex pattern + matches --conflict-column value matching *Perl* regex pattern --conflict-value - This option only works with "--bidirectional". + This option only works with :option:`--bidirectional`. See "BIDIRECTIONAL SYNCING" for more information. ---conflict-error +.. option:: --conflict-error type: string; default: warn @@ -771,51 +759,51 @@ This tool accepts additional command-line arguments. Refer to the .. code-block:: perl - * warn: Print a warning to STDERR about the unresolvable conflict - * die: Die, stop syncing, and print a warning to STDERR + * warn: Print a warning to ``STDERR`` about the unresolvable conflict + * die: Die, stop syncing, and print a warning to ``STDERR`` - This option only works with "--bidirectional". + This option only works with :option:`--bidirectional`. See "BIDIRECTIONAL SYNCING" for more information. ---conflict-threshold +.. option:: --conflict-threshold type: string - Amount by which one "--conflict-column" must exceed the other. + Amount by which one :option:`--conflict-column` must exceed the other. - The "--conflict-threshold" prevents a conflict from being resolved if - the absolute difference between the two "--conflict-column" values is - less than this amount. For example, if two "--conflict-column" have + The :option:`--conflict-threshold` prevents a conflict from being resolved if + the absolute difference between the two :option:`--conflict-column` values is + less than this amount. For example, if two :option:`--conflict-column` have timestamp values "2009-12-01 12:00:00" and "2009-12-01 12:05:00" the difference - is 5 minutes. If "--conflict-threshold" is set to "5m" the conflict will - be resolved, but if "--conflict-threshold" is set to "6m" the conflict + is 5 minutes. If :option:`--conflict-threshold` is set to "5m" the conflict will + be resolved, but if :option:`--conflict-threshold` is set to "6m" the conflict will fail to resolve because the difference is not greater than or equal - to 6 minutes. In this latter case, "--conflict-error" will report + to 6 minutes. In this latter case, :option:`--conflict-error` will report the failure. - This option only works with "--bidirectional". + This option only works with :option:`--bidirectional`. See "BIDIRECTIONAL SYNCING" for more information. ---conflict-value +.. option:: --conflict-value type: string - Use this value for certain "--conflict-comparison". + Use this value for certain :option:`--conflict-comparison`. This option gives the value for \ ``equals``\ and \ ``matches``\ - "--conflict-comparison". + :option:`--conflict-comparison`. - This option only works with "--bidirectional". + This option only works with :option:`--bidirectional`. See "BIDIRECTIONAL SYNCING" for more information. ---databases +.. option:: --databases short form: -d; type: hash @@ -823,13 +811,13 @@ This tool accepts additional command-line arguments. Refer to the A common request is to sync tables from one database with tables from another database on the same or different server. This is not yet possible. - "--databases" will not do it, and you can't do it with the D part of the DSN + :option:`--databases` will not do it, and you can't do it with the D part of the DSN either because in the absence of a table name it assumes the whole server should be synced and the D part controls only the connection's default database. ---defaults-file +.. option:: --defaults-file short form: -F; type: string @@ -837,11 +825,11 @@ This tool accepts additional command-line arguments. Refer to the ---dry-run +.. option:: --dry-run Analyze, decide the sync algorithm to use, print and exit. - Implies "--verbose" so you can see the results. The results are in the same + Implies :option:`--verbose` so you can see the results. The results are in the same output format that you'll see from actually running the tool, but there will be zeros for rows affected. This is because the tool actually executes, but stops before it compares any data and just returns zeros. The zeros do not mean there @@ -849,7 +837,7 @@ This tool accepts additional command-line arguments. Refer to the ---engines +.. option:: --engines short form: -e; type: hash @@ -857,43 +845,43 @@ This tool accepts additional command-line arguments. Refer to the ---execute +.. option:: --execute Execute queries to make the tables have identical data. - This option makes pt-table-sync actually sync table data by executing all + This option makes :program:`pt-table-sync` actually sync table data by executing all the queries that it created to resolve table differences. Therefore, \ **the - tables will be changed!**\ And unless you also specify "--verbose", the + tables will be changed!**\ And unless you also specify :option:`--verbose`, the changes will be made silently. If this is not what you want, see - "--print" or "--dry-run". + :option:`--print` or :option:`--dry-run`. ---explain-hosts +.. option:: --explain-hosts Print connection information and exit. - Print out a list of hosts to which pt-table-sync will connect, with all + Print out a list of hosts to which :program:`pt-table-sync` will connect, with all the various connection options, and exit. ---float-precision +.. option:: --float-precision type: int Precision for \ ``FLOAT``\ and \ ``DOUBLE``\ number-to-string conversion. Causes FLOAT and DOUBLE values to be rounded to the specified number of digits after the - decimal point, with the ROUND() function in MySQL. This can help avoid + decimal point, with the ROUND() function in |MySQL|. This can help avoid checksum mismatches due to different floating-point representations of the same - values on different MySQL versions and hardware. The default is no rounding; - the values are converted to strings by the CONCAT() function, and MySQL chooses + values on different |MySQL| versions and hardware. The default is no rounding; + the values are converted to strings by the CONCAT() function, and |MySQL| chooses the string representation. If you specify a value of 2, for example, then the values 1.008 and 1.009 will be rounded to 1.01, and will checksum as equal. ---[no]foreign-key-checks +.. option:: --[no]foreign-key-checks default: yes @@ -903,14 +891,14 @@ This tool accepts additional command-line arguments. Refer to the ---function +.. option:: --function type: string Which hash function you'd like to use for checksums. The default is \ ``CRC32``\ . Other good choices include \ ``MD5``\ and \ ``SHA1``\ . If you - have installed the \ ``FNV_64``\ user-defined function, \ ``pt-table-sync``\ will detect + have installed the \ ``FNV_64``\ user-defined function, :program:`pt-table-sync` will detect it and prefer to use it, because it is much faster than the built-ins. You can also use MURMUR_HASH if you've installed that user-defined function. Both of these are distributed with Maatkit. See pt-table-checksum for more @@ -918,27 +906,27 @@ This tool accepts additional command-line arguments. Refer to the ---help +.. option:: --help Show help and exit. ---[no]hex-blob +.. option:: --[no]hex-blob default: yes \ ``HEX()``\ \ ``BLOB``\ , \ ``TEXT``\ and \ ``BINARY``\ columns. When row data from the source is fetched to create queries to sync the - data (i.e. the queries seen with "--print" and executed by "--execute"), + data (i.e. the queries seen with :option:`--print` and executed by :option:`--execute`), binary columns are wrapped in HEX() so the binary data does not produce an invalid SQL statement. You can disable this option but you probably shouldn't. ---host +.. option:: --host short form: -h; type: string @@ -946,7 +934,7 @@ This tool accepts additional command-line arguments. Refer to the ---ignore-columns +.. option:: --ignore-columns type: Hash @@ -959,7 +947,7 @@ This tool accepts additional command-line arguments. Refer to the ---ignore-databases +.. option:: --ignore-databases type: Hash @@ -967,7 +955,7 @@ This tool accepts additional command-line arguments. Refer to the ---ignore-engines +.. option:: --ignore-engines type: Hash; default: FEDERATED,MRG_MyISAM @@ -975,7 +963,7 @@ This tool accepts additional command-line arguments. Refer to the ---ignore-tables +.. option:: --ignore-tables type: Hash @@ -985,24 +973,23 @@ This tool accepts additional command-line arguments. Refer to the ---[no]index-hint +.. option:: --[no]index-hint default: yes Add FORCE/USE INDEX hints to the chunk and row queries. - By default \ ``pt-table-sync``\ adds a FORCE/USE INDEX hint to each SQL statement - to coerce MySQL into using the index chosen by the sync algorithm or specified - by "--chunk-index". This is usually a good thing, but in rare cases the + By default :program:`pt-table-sync` adds a FORCE/USE INDEX hint to each SQL statement + to coerce |MySQL| into using the index chosen by the sync algorithm or specified + by :option:`--chunk-index`. This is usually a good thing, but in rare cases the index may not be the best for the query so you can suppress the index hint - by specifying \ ``--no-index-hint``\ and let MySQL choose the index. + by specifying \ ``--no-index-hint``\ and let |MySQL| choose the index. - This does not affect the queries printed by "--print"; it only affects the - chunk and row queries that \ ``pt-table-sync``\ uses to select and compare rows. + This does not affect the queries printed by :option:`--print`; it only affects the + chunk and row queries that :program:`pt-table-sync` uses to select and compare rows. - ---lock +.. option:: --lock type: int @@ -1028,22 +1015,20 @@ This tool accepts additional command-line arguments. Refer to the C. - A replication slave is never locked if "--replicate" or "--sync-to-master" + A replication slave is never locked if :option:`--replicate" or "--sync-to-master` is specified, since in theory locking the table on the master should prevent any changes from taking place. (You are not changing data on your slave, right?) - If "--wait" is given, the master (source) is locked and then the tool waits + If :option:`--wait` is given, the master (source) is locked and then the tool waits for the slave to catch up to the master before continuing. If \ ``--transaction``\ is specified, \ ``LOCK TABLES``\ is not used. Instead, lock and unlock are implemented by beginning and committing transactions. - The exception is if "--lock" is 3. + The exception is if :option:`--lock` is 3. If \ ``--no-transaction``\ is specified, then \ ``LOCK TABLES``\ is used for any - value of "--lock". See "--[no]transaction". + value of :option:`--lock`. See :option:`--[no]transaction`. - - ---lock-and-rename +.. option:: --lock-and-rename Lock the source and destination table, sync, then swap names. This is useful as a less-blocking ALTER TABLE, once the tables are reasonably in sync with each @@ -1054,7 +1039,7 @@ This tool accepts additional command-line arguments. Refer to the ---password +.. option:: --password short form: -p; type: string @@ -1062,7 +1047,7 @@ This tool accepts additional command-line arguments. Refer to the ---pid +.. option:: --pid type: string @@ -1077,7 +1062,7 @@ This tool accepts additional command-line arguments. Refer to the ---port +.. option:: --port short form: -P; type: int @@ -1085,17 +1070,17 @@ This tool accepts additional command-line arguments. Refer to the ---print +.. option:: --print Print queries that will resolve differences. - If you don't trust \ ``pt-table-sync``\ , or just want to see what it will do, this + If you don't trust :program:`pt-table-sync`, or just want to see what it will do, this is a good way to be safe. These queries are valid SQL and you can run them yourself if you want to sync the tables manually. ---recursion-method +.. option:: --recursion-method type: string @@ -1114,13 +1099,13 @@ This tool accepts additional command-line arguments. Refer to the The processlist method is preferred because SHOW SLAVE HOSTS is not reliable. However, the hosts method is required if the server uses a non-standard - port (not 3306). Usually pt-table-sync does the right thing and finds + port (not 3306). Usually :program:`pt-table-sync` does the right thing and finds the slaves, but you may give a preferred method and it will be used first. If it doesn't find any slaves, the other methods will be tried. ---replace +.. option:: --replace Write all \ ``INSERT``\ and \ ``UPDATE``\ statements as \ ``REPLACE``\ . @@ -1129,13 +1114,13 @@ This tool accepts additional command-line arguments. Refer to the ---replicate +.. option:: --replicate type: string Sync tables listed as different in this table. - Specifies that \ ``pt-table-sync``\ should examine the specified table to find data + Specifies that :program:`pt-table-sync` should examine the specified table to find data that differs. The table is exactly the same as the argument of the same name to pt-table-checksum. That is, it contains records of which tables (and ranges of values) differ between the master and slave. @@ -1144,10 +1129,10 @@ This tool accepts additional command-line arguments. Refer to the slave, \ ``pt-table-checksum``\ will sync that table, with the appropriate \ ``WHERE``\ clause, to its master. - This automatically sets "--wait" to 60 and causes changes to be made on the + This automatically sets :option:`--wait` to 60 and causes changes to be made on the master instead of the slave. - If "--sync-to-master" is specified, the tool will assume the server you + If :option:`--sync-to-master` is specified, the tool will assume the server you specified is the slave, and connect to the master as usual to sync. Otherwise, it will try to use \ ``SHOW PROCESSLIST``\ to find slaves of the server @@ -1167,37 +1152,35 @@ This tool accepts additional command-line arguments. Refer to the ---set-vars +.. option:: --set-vars type: string; default: wait_timeout=10000 - Set these MySQL variables. Immediately after connecting to MySQL, this + Set these |MySQL| variables. Immediately after connecting to |MySQL|, this string will be appended to SET and executed. - ---socket +.. option:: --socket short form: -S; type: string Socket file to use for connection. - ---sync-to-master +.. option:: --sync-to-master Treat the DSN as a slave and sync it to its master. Treat the server you specified as a slave. Inspect \ ``SHOW SLAVE STATUS``\ , connect to the server's master, and treat the master as the source and the slave - as the destination. Causes changes to be made on the master. Sets "--wait" - to 60 by default, sets "--lock" to 1 by default, and disables - "--[no]transaction" by default. See also "--replicate", which changes + as the destination. Causes changes to be made on the master. Sets :option:`--wait` + to 60 by default, sets :option:`--lock` to 1 by default, and disables + :option:`--[no]transaction` by default. See also :option:`--replicate`, which changes this option's behavior. ---tables +.. option:: --tables short form: -t; type: hash @@ -1207,11 +1190,11 @@ This tool accepts additional command-line arguments. Refer to the ---timeout-ok +.. option:: --timeout-ok - Keep going if "--wait" fails. + Keep going if :option:`--wait` fails. - If you specify "--wait" and the slave doesn't catch up to the master's + If you specify :option:`--wait` and the slave doesn't catch up to the master's position before the wait times out, the default behavior is to abort. This option makes the tool keep going anyway. \ **Warning**\ : if you are trying to get a consistent comparison between the two servers, you probably don't want to keep @@ -1219,45 +1202,42 @@ This tool accepts additional command-line arguments. Refer to the ---[no]transaction +.. option:: --[no]transaction Use transactions instead of \ ``LOCK TABLES``\ . The granularity of beginning and committing transactions is controlled by - "--lock". This is enabled by default, but since "--lock" is disabled by + :option:`--lock`. This is enabled by default, but since `--lock` is disabled by default, it has no effect. Most options that enable locking also disable transactions by default, so if you want to use transactional locking (via \ ``LOCK IN SHARE MODE``\ and \ ``FOR UPDATE``\ , you must specify \ ``--transaction``\ explicitly. - If you don't specify \ ``--transaction``\ explicitly \ ``pt-table-sync``\ will decide on + If you don't specify \ ``--transaction``\ explicitly \ ` :program:`pt-table-sync```\ will decide on a per-table basis whether to use transactions or table locks. It currently - uses transactions on InnoDB tables, and table locks on all others. + uses transactions on |InnoDB| tables, and table locks on all others. - If \ ``--no-transaction``\ is specified, then \ ``pt-table-sync``\ will not use - transactions at all (not even for InnoDB tables) and locking is controlled - by "--lock". + If \ ``--no-transaction``\ is specified, then :program:`pt-table-sync` will not use + transactions at all (not even for |InnoDB| tables) and locking is controlled + by :option:`--lock`. When enabled, either explicitly or implicitly, the transaction isolation level is set \ ``REPEATABLE READ``\ and transactions are started \ ``WITH CONSISTENT SNAPSHOT``\ . - - ---trim +.. option:: --trim \ ``TRIM()``\ \ ``VARCHAR``\ columns in \ ``BIT_XOR``\ and \ ``ACCUM``\ modes. Helps when - comparing MySQL 4.1 to >= 5.0. + comparing |MySQL| 4.1 to >= 5.0. This is useful when you don't care about the trailing space differences between - MySQL versions which vary in their handling of trailing spaces. MySQL 5.0 and + |MySQL| versions which vary in their handling of trailing spaces. |MySQL| 5.0 and later all retain trailing spaces in \ ``VARCHAR``\ , while previous versions would remove them. - ---[no]unique-checks +.. option:: --[no]unique-checks default: yes @@ -1266,8 +1246,7 @@ This tool accepts additional command-line arguments. Refer to the Specifying \ ``--no-unique-checks``\ will \ ``SET UNIQUE_CHECKS=0``\ . - ---user +.. option:: --user short form: -u; type: string @@ -1275,7 +1254,7 @@ This tool accepts additional command-line arguments. Refer to the ---verbose +.. option:: --verbose short form: -v; cumulative: yes @@ -1285,13 +1264,13 @@ This tool accepts additional command-line arguments. Refer to the ---version +.. option:: --version Show version and exit. ---wait +.. option:: --wait short form: -w; type: time @@ -1299,8 +1278,7 @@ This tool accepts additional command-line arguments. Refer to the Make the master wait for the slave to catch up in replication before comparing the tables. The value is the number of seconds to wait before timing out (see - also "--timeout-ok"). Sets "--lock" to 1 and "--[no]transaction" to 0 - by default. If you see an error such as the following, + also :option:`--timeout-ok`). Sets :option:`--lock` to 1 and :option:`--[no]transaction` to 0 by default. If you see an error such as the following, .. code-block:: perl @@ -1311,14 +1289,14 @@ This tool accepts additional command-line arguments. Refer to the It means the timeout was exceeded and you need to increase it. The default value of this option is influenced by other options. To see what - value is in effect, run with "--help". + value is in effect, run with :option:`--help`. - To disable waiting entirely (except for locks), specify "--wait" 0. This + To disable waiting entirely (except for locks), specify :option:`--wait` 0. This helps when the slave is lagging on tables that are not being synced. ---where +.. option:: --where type: string @@ -1326,12 +1304,12 @@ This tool accepts additional command-line arguments. Refer to the ---[no]zero-chunk +.. option:: --[no]zero-chunk default: yes Add a chunk for rows with zero or zero-equivalent values. The only has an - effect when "--chunk-size" is specified. The purpose of the zero chunk + effect when :option:`--chunk-size` is specified. The purpose of the zero chunk is to capture a potentially large number of zero values that would imbalance the size of the first chunk. For example, if a lot of negative numbers were inserted into an unsigned integer column causing them to be stored as zeros, @@ -1341,9 +1319,8 @@ This tool accepts additional command-line arguments. Refer to the -*********** DSN OPTIONS -*********** +=========== These DSN options are used to create a DSN. Each option is given like @@ -1353,7 +1330,7 @@ if the value contains whitespace it must be quoted. DSN options are comma-separated. See the percona-toolkit manpage for full details. -\* A + * ``A`` dsn: charset; copy: yes @@ -1361,7 +1338,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* D + * ``D`` dsn: database; copy: yes @@ -1369,7 +1346,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* F + * ``F`` dsn: mysql_read_default_file; copy: yes @@ -1377,7 +1354,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* h + * ``h`` dsn: host; copy: yes @@ -1385,7 +1362,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* p + * ``p`` dsn: password; copy: yes @@ -1393,7 +1370,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* P + * ``p`` dsn: port; copy: yes @@ -1401,23 +1378,21 @@ comma-separated. See the percona-toolkit manpage for full details. -\* S + * ``S`` dsn: mysql_socket; copy: yes Socket file to use for connection. - -\* t + * ``t`` copy: yes Table to be synced. - -\* u + * ``u`` dsn: user; copy: yes @@ -1426,12 +1401,11 @@ comma-separated. See the percona-toolkit manpage for full details. -*********** ENVIRONMENT -*********** +=========== -The environment variable \ ``PTDEBUG``\ enables verbose debugging output to STDERR. +The environment variable \ ``PTDEBUG``\ enables verbose debugging output to ``STDERR``. To enable debugging and capture all output to a file, run the tool like: @@ -1444,53 +1418,25 @@ Be careful: debugging output is voluminous and can generate several megabytes of output. -******************* SYSTEM REQUIREMENTS -******************* +=================== -You need Perl, DBI, DBD::mysql, and some core packages that ought to be -installed in any reasonably new version of Perl. +You need *Perl* , ``DBI``, ``DBD::mysql``, and some core packages that ought to be +installed in any reasonably new version of *Perl* . -**** BUGS -**** +==== For a list of known bugs, see `http://www.percona.com/bugs/pt-table-sync `_. 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 @@ -1518,17 +1464,15 @@ You can also get individual tools from the latest release: Replace \ ``TOOL``\ with the name of any tool. -******* AUTHORS -******* +======= -Baron Schwartz +*Baron Schwartz* -*************** ACKNOWLEDGMENTS -*************** +=============== My work is based in part on Giuseppe Maxia's work on distributed databases, @@ -1565,63 +1509,31 @@ also my own work. Another tool that can synchronize tables is the SQLyog Job Agent from webyog. Thanks to Rohit Nadhani, SJA's author, for the conversations about the general -techniques. There is a comparison of pt-table-sync and SJA at +techniques. There is a comparison of :program:`pt-table-sync` and SJA at `http://tinyurl.com/maatkit-vs-sqlyog `_ Thanks to the following people and organizations for helping in many ways: The Rimm-Kaufman Group `http://www.rimmkaufman.com/ `_, -MySQL AB `http://www.mysql.com/ `_, +|MySQL| AB `http://www.mysql.com/ `_, Blue Ridge InternetWorks `http://www.briworks.com/ `_, Percona `http://www.percona.com/ `_, Fabien Coelho, -Giuseppe Maxia and others at MySQL AB, -Kristian Koehntopp (MySQL AB), +Giuseppe Maxia and others at |MySQL| AB, +Kristian Koehntopp (|MySQL| AB), Rohit Nadhani (WebYog), -The helpful monks at Perlmonks, +The helpful monks at *Perl* monks, And others too numerous to mention. - -********************* -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 2007-2011 Baron Schwartz, 2011 Percona Inc. +This program is copyright 2007-2011 *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 -******* +======= - -pt-table-sync 1.0.1 +:program:`pt-table-sync` 1.0.1 diff --git a/docs/user/pt-tcp-model.rst b/docs/user/source/pt-tcp-model.rst similarity index 68% rename from docs/user/pt-tcp-model.rst rename to docs/user/source/pt-tcp-model.rst index ca4f24ed..ad0c500d 100644 --- a/docs/user/pt-tcp-model.rst +++ b/docs/user/source/pt-tcp-model.rst @@ -1,32 +1,35 @@ +.. program:: pt-tcp-model -############ -pt-tcp-model -############ +========================= + :program:`pt-tcp-model` +========================= .. highlight:: perl -**** NAME -**** +==== + + :program:`pt-tcp-model` - Transform tcpdump into metrics that permit performance and scalability modeling. -pt-tcp-model - Transform tcpdump into metrics that permit performance and scalability modeling. - - -******** SYNOPSIS -******** +======== -Usage: pt-tcp-model [OPTION...] [FILE] +Usage +----- -pt-tcp-model parses and analyzes tcpdump files. With no FILE, or when +:: + + pt-tcp-model [OPTION...] [FILE] + +:program:`pt-tcp-model` parses and analyzes tcpdump files. With no FILE, or when FILE is -, it read standard input. Dump TCP requests and responses to a file, capturing only the packet headers to avoid dropped packets, and ignoring any packets without a payload (such as -ack-only packets). Capture port 3306 (MySQL database traffic). Note that to +ack-only packets). Capture port 3306 (|MySQL| database traffic). Note that to avoid line breaking in terminals and man pages, the TCP filtering expression that follows has a line break at the end of the second line; you should omit this from your tcpdump command. @@ -78,9 +81,8 @@ line are normally incomplete observation periods and are aberrant): -***** RISKS -***** +===== The following section is included to inform users about the potential risks, @@ -88,7 +90,7 @@ 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-tcp-model merely reads and transforms its input, printing it to the output. +:program:`pt-tcp-model` merely reads and transforms its input, printing it to the output. It should be very low risk. At the time of this release, we know of no bugs that could cause serious harm @@ -99,12 +101,11 @@ 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-tcp-model `_. -See also "BUGS" for more information on filing bugs and getting help. +See also :ref:`bugs` for more information on filing bugs and getting help. -*********** DESCRIPTION -*********** +=========== This tool recognizes requests and responses in a TCP stream, and extracts the @@ -119,7 +120,7 @@ following format, which should result from the sample shown in the SYNOPSIS: The tool watches for "incoming" packets to the port you specify with the -"--watch-server" option. This begins a request. If multiple inbound packets +:option:`--watch-server` option. This begins a request. If multiple inbound packets follow each other, then by default the last inbound packet seen determines the time at which the request is assumed to begin. This is logical if one assumes that a server must receive the whole SQL statement before beginning execution, @@ -137,14 +138,13 @@ Most types of analysis require processing in either arrival or completion order. Therefore, the second type of processing this tool can do requires that you sort the output from the first stage and supply it as input. -The second type of processing is selected with the "--type" option set to +The second type of processing is selected with the :option:`--type` option set to "requests". In this mode, the tool reads a group of requests and aggregates them, then emits the aggregated metrics. -****** OUTPUT -****** +====== In the default mode (parsing tcpdump output), requests are printed out one per @@ -158,52 +158,52 @@ line, in the following format: The ID is an incrementing number, assigned in arrival order in the original TCP traffic. The start and end timestamps, and the elapsed time, can be customized -with the "--start-end" option. +with the :option:`--start-end` option. -In "--type=requests" mode, the tool prints out one line per time interval as -defined by "--run-time", with the following columns: ts, concurrency, +In :option:`--type=requests` mode, the tool prints out one line per time interval as +defined by :option:`--run-time`, with the following columns: ts, concurrency, throughput, arrivals, completions, busy_time, weighted_time, sum_time, variance_mean, quantile_time, obs_time. A detailed explanation follows: -ts + * ``ts`` The timestamp that defines the beginning of the interval. -concurrency + * ``concurrency`` The average number of requests resident in the server during the interval. -throughput + * ``throughput`` The number of arrivals per second during the interval. -arrivals + * ``arrivals`` The number of arrivals during the interval. -completions + * ``completions`` The number of completions during the interval. -busy_time + * ``busy_time`` The total amount of time during which at least one request was resident in the server during the interval. -weighted_time + * ``weighted_time`` The total response time of all the requests resident in the server during the interval, including requests that neither arrived nor completed during the @@ -211,27 +211,27 @@ weighted_time -sum_time + * ``sum_time`` The total response time of all the requests that arrived in the interval. -variance_mean + * ``variance_mean`` The variance-to-mean ratio (index of dispersion) of the response times of the requests that arrived in the interval. -quantile_time + * ``quantile_time`` The Nth percentile response time for all the requests that arrived in the - interval. See also "--quantile". + interval. See also :option:`--quantile`. -obs_time + * ``obs_time`` The length of the observation time window. This will usually be the same as the interval length, except for the first and last intervals in a file, which might @@ -240,16 +240,15 @@ obs_time -******* OPTIONS -******* +======= This tool accepts additional command-line arguments. Refer to the "SYNOPSIS" and usage information for details. ---config +.. option:: --config type: Array @@ -258,41 +257,41 @@ This tool accepts additional command-line arguments. Refer to the ---help +.. option:: --help Show help and exit. ---progress +.. option:: --progress type: array; default: time,30 - Print progress reports to STDERR. The value is a comma-separated list with two + Print progress reports to ``STDERR``. The value is a comma-separated list with two parts. The first part can be percentage, time, or iterations; the second part specifies how often an update should be printed, in percentage, seconds, or number of iterations. ---quantile +.. option:: --quantile type: float - The percentile for the last column when "--type" is "requests" (default .99). + The percentile for the last column when :option:`--type" is "requests` (default .99). ---run-time +.. option:: --run-time type: float - The size of the aggregation interval in seconds when "--type" is "requests" + The size of the aggregation interval in seconds when :option:`--type" is "requests` (default 1). Fractional values are permitted. ---start-end +.. option:: --start-end type: Array; default: ts,end @@ -318,14 +317,14 @@ This tool accepts additional command-line arguments. Refer to the ---type +.. option:: --type type: string The type of input to parse (default tcpdump). The permitted types are - tcpdump + * `` tcpdump`` The parser expects the input to be formatted with the following options: \ ``-x -n -q -tttt``\ . For example, if you want to capture output from your local machine, @@ -350,31 +349,31 @@ This tool accepts additional command-line arguments. Refer to the > 127.0.0.1.3306: tcp 37 - All MySQL servers running on port 3306 are automatically detected in the + All |MySQL| servers running on port 3306 are automatically detected in the tcpdump output. Therefore, if the tcpdump out contains packets from multiple servers on port 3306 (for example, 10.0.0.1:3306, 10.0.0.2:3306, etc.), all packets/queries from all these servers will be analyzed together as if they were one server. If you're analyzing traffic for a protocol that is not running on port - 3306, see "--watch-server". + 3306, see :option:`--watch-server`. ---version +.. option:: --version Show version and exit. ---watch-server +.. option:: --watch-server type: string; default: 10.10.10.10:3306 - This option tells pt-tcp-model which server IP address and port (such as - "10.0.0.1:3306") to watch when parsing tcpdump for "--type" tcpdump. If you + This option tells :program:`pt-tcp-model` which server IP address and port (such as + "10.0.0.1:3306") to watch when parsing tcpdump for :option:`--type` tcpdump. If you don't specify it, the tool watches all servers by looking for any IP address using port 3306. If you're watching a server with a non-standard port, this won't work, so you must specify the IP address and port to watch. @@ -386,146 +385,55 @@ This tool accepts additional command-line arguments. Refer to the -*********** ENVIRONMENT -*********** +=========== -The environment variable \ ``PTDEBUG``\ enables verbose debugging output to STDERR. +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-tcp-model ... > FILE 2>&1 + PTDEBUG=1 :program:`pt-tcp-model` ... > FILE 2>&1 Be careful: debugging output is voluminous and can generate several megabytes of output. -******************* SYSTEM REQUIREMENTS -******************* +=================== -You need Perl, DBI, DBD::mysql, and some core packages that ought to be -installed in any reasonably new version of Perl. +You need *Perl* , ``DBI``, ``DBD::mysql``, and some core packages that ought to be +installed in any reasonably new version of *Perl* . -**** BUGS -**** +==== For a list of known bugs, see `http://www.percona.com/bugs/pt-tcp-model `_. 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* -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 2011 Baron Schwartz, 2011 Percona Inc. +This program is copyright 2011 *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 -******* +======= - -pt-tcp-model 1.0.1 +:program:`pt-tcp-model` 1.0.1 diff --git a/docs/user/source/pt-trend.rst b/docs/user/source/pt-trend.rst new file mode 100644 index 00000000..d1500566 --- /dev/null +++ b/docs/user/source/pt-trend.rst @@ -0,0 +1,168 @@ +.. program:: pt-trend + + +===================== + :program:`pt-trend` +===================== + +.. highlight:: perl + + +NAME +==== + + :program:`pt-trend` - Compute statistics over a set of time-series data points. + + +SYNOPSIS +======== + + +Usage +----- + +:: + + pt-trend [OPTION...] [FILE ...] + +:program:`pt-trend` reads a slow query log and outputs statistics on it. + + +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. + +:program:`pt-trend` simply reads files give on the command-line. 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-trend `_. + +See also :ref:`bugs` for more information on filing bugs and getting help. + + +DESCRIPTION +=========== + + +You can specify multiple files on the command line. If you don't specify any, +or if you use the special filename \ ``-``\ , lines are read from standard input. + + +OPTIONS +======= + + +This tool accepts additional command-line arguments. Refer to the +"SYNOPSIS" and usage information for details. + + +.. option:: --config + + type: Array + + Read this comma-separated list of config files; if specified, this must be the + first option on the command line. + + + +.. option:: --help + + Show help and exit. + + + +.. option:: --pid + + type: string + + Create the given PID file. The file contains the process ID of the script. + The PID file is removed when the script exits. Before starting, the script + checks if the PID file already exists. If it does not, then the script creates + and writes its own PID to it. If it does, then the script checks the following: + if the file contains a PID and a process is running with that PID, then + the script dies; or, if there is no process running with that PID, then the + script overwrites the file with its own PID and starts; else, if the file + contains no PID, then the script dies. + + + +.. option:: --progress + + type: array; default: time,15 + + Print progress reports to ``STDERR``. The value is a comma-separated list with two + parts. The first part can be percentage, time, or iterations; the second part + specifies how often an update should be printed, in percentage, seconds, or + number of iterations. + + + +.. option:: --version + + Show version and exit. + + + +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 :program:`pt-trend` ... > FILE 2>&1 + + +Be careful: debugging output is voluminous and can generate several megabytes +of output. + + +SYSTEM REQUIREMENTS +=================== + + +You need *Perl* , ``DBI``, ``DBD::mysql``, and some core packages that ought to be +installed in any reasonably new version of *Perl* . + + +BUGS +==== + + +For a list of known bugs, see `http://www.percona.com/bugs/pt-trend `_. + +Please report bugs at `https://bugs.launchpad.net/percona-toolkit `_. + +AUTHORS +======= + + +*Baron Schwartz* + + +COPYRIGHT, LICENSE, AND WARRANTY +================================ + + +This program is copyright 2010-2011 *Baron Schwartz*, 2011 Percona Inc. +Feedback and improvements are welcome. + + +VERSION +======= + +:program:`pt-trend` 1.0.1 + diff --git a/docs/user/pt-upgrade.rst b/docs/user/source/pt-upgrade.rst similarity index 67% rename from docs/user/pt-upgrade.rst rename to docs/user/source/pt-upgrade.rst index 92cddcd9..bfa68db6 100644 --- a/docs/user/pt-upgrade.rst +++ b/docs/user/source/pt-upgrade.rst @@ -1,28 +1,31 @@ +.. program:: pt-upgrade -########## -pt-upgrade -########## +======================= + :program:`pt-upgrade` +======================= .. highlight:: perl -**** NAME -**** +==== + + :program:`pt-upgrade` - Execute queries on multiple servers and check for differences. -pt-upgrade - Execute queries on multiple servers and check for differences. - - -******** SYNOPSIS -******** +======== -Usage: pt-upgrade [OPTION...] DSN [DSN...] [FILE] +Usage +----- -pt-upgrade compares query execution on two hosts by executing queries in the -given file (or STDIN if no file given) and examining the results, errors, +:: + + pt-upgrade [OPTION...] DSN [DSN...] [FILE] + +:program:`pt-upgrade` compares query execution on two hosts by executing queries in the +given file (or ``STDIN`` if no file given) and examining the results, errors, warnings, etc.produced on each. Execute and compare all queries in slow.log on host1 to host2: @@ -40,7 +43,7 @@ Use pt-query-digest to get, execute and compare queries from tcpdump: tcpdump -i eth0 port 3306 -s 65535 -x -n -q -tttt \ | pt-query-digest --type tcpdump --no-report --print \ - | pt-upgrade h=host1 h=host2 + | :program:`pt-upgrade` h=host1 h=host2 Compare only query times on host1 to host2 and host3: @@ -60,9 +63,8 @@ Compare a single query, no slowlog needed: -***** RISKS -***** +===== The following section is included to inform users about the potential risks, @@ -70,7 +72,7 @@ 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-upgrade is a read-only tool that is meant to be used on non-production +:program:`pt-upgrade` is a read-only tool that is meant to be used on non-production servers. It executes the SQL that you give it as input, which could cause undesired load on a production server. @@ -82,18 +84,16 @@ 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-upgrade `_. -See also "BUGS" for more information on filing bugs and getting help. +See also :ref:`bugs` for more information on filing bugs and getting help. -*********** DESCRIPTION -*********** +=========== - -pt-upgrade executes queries from slowlogs on one or more MySQL server to find +:program:`pt-upgrade` executes queries from slowlogs on one or more |MySQL| server to find differences in query time, warnings, results, and other aspects of the querys' execution. This helps evaluate upgrades, migrations and configuration -changes. The comparisons specified by "--compare" determine what +changes. The comparisons specified by :option:`--compare` determine what differences can be found. A report is printed which outlines all the differences found; see "OUTPUT" below. @@ -102,85 +102,82 @@ the results to which the other DSNs are compared. You can "compare" only one host, in which case there will be no differences but the output can be saved to be diffed later against the output of another single host "comparison". -At present, pt-upgrade only reads slowlogs. Use \ ``pt-query-digest --print``\ to +At present, :program:`pt-upgrade` only reads slowlogs. Use \ ``pt-query-digest --print``\ to transform other log formats to slowlog. -DSNs and slowlog files can be specified in any order. pt-upgrade will +DSNs and slowlog files can be specified in any order. :program:`pt-upgrade` will automatically determine if an argument is a DSN or a slowlog file. If no -slowlog files are given and "--query" is not specified then pt-upgrade -will read from \ ``STDIN``\ . +slowlog files are given and :option:`--query` is not specified then :program:`pt-upgrade` +will read from \ ````STDIN````\ . -****** OUTPUT -****** +====== TODO -******* OPTIONS -******* +======= This tool accepts additional command-line arguments. Refer to the "SYNOPSIS" and usage information for details. ---ask-pass +.. option:: --ask-pass - Prompt for a password when connecting to MySQL. + Prompt for a password when connecting to |MySQL|. ---base-dir +.. option:: --base-dir type: string; default: /tmp Save outfiles for the \ ``rows``\ comparison method in this directory. - See the \ ``rows``\ "--compare-results-method". + See the \ ``rows``\ :option:`--compare-results-method`. ---charset +.. option:: --charset short form: -A; type: string - Default character set. If the value is utf8, sets Perl's binmode on - STDOUT to utf8, passes the mysql_enable_utf8 option to DBD::mysql, and - runs SET NAMES UTF8 after connecting to MySQL. Any other value sets - binmode on STDOUT without the utf8 layer, and runs SET NAMES after - connecting to MySQL. + Default character set. If the value is utf8, sets *Perl* 's binmode on + ``STDOUT`` to utf8, passes the mysql_enable_utf8 option to ``DBD::mysql``, and + runs SET NAMES UTF8 after connecting to |MySQL|. Any other value sets + binmode on ``STDOUT`` without the utf8 layer, and runs SET NAMES after + connecting to |MySQL|. ---[no]clear-warnings +.. option:: --[no]clear-warnings default: yes Clear warnings before each warnings comparison. - If comparing warnings ("--compare" includes \ ``warnings``\ ), this option - causes pt-upgrade to execute a successful \ ``SELECT``\ statement which clears + If comparing warnings (:option:`--compare` includes \ ``warnings``\ ), this option + causes :program:`pt-upgrade` to execute a successful \ ``SELECT``\ statement which clears any warnings left over from previous queries. This requires a current - database that pt-upgrade usually detects automatically, but in some cases - it might be necessary to specify "--temp-database". If pt-upgrade can't - auto-detect the current database, it will create a temporary table in the - "--temp-database" called \ ``mk_upgrade_clear_warnings``\ . + database that :program:`pt-upgrade` usually detects automatically, but in some cases + it might be necessary to specify :option:`--temp-database`. If :program:`pt-upgrade` can't auto-detect the current database, it will create a temporary table in the + :option:`--temp-database` called \ ``mk_upgrade_clear_warnings``\ . ---clear-warnings-table +.. option:: --clear-warnings-table type: string - Execute \ ``SELECT \* FROM ... LIMIT 1``\ from this table to clear warnings. + Execute \ ``SELECT FROM ... LIMIT 1``\ from this table to clear warnings. ---compare +.. option:: --compare type: Hash; default: query_times,results,warnings @@ -191,7 +188,7 @@ This tool accepts additional command-line arguments. Refer to the comparisons are available: - query_times + * `` query_times`` Compare query execution times. If this comparison is disabled, the queries are still executed so that other comparisons will work, but the query time @@ -199,37 +196,37 @@ This tool accepts additional command-line arguments. Refer to the - results + * `` results`` Compare result sets to find differences in rows, columns, etc. - What differences can be found depends on the "--compare-results-method" used. + What differences can be found depends on the :option:`--compare-results-method` used. - warnings + * `` warnings`` - Compare warnings from \ ``SHOW WARNINGS``\ . Requires at least MySQL 4.1. + Compare warnings from \ ``SHOW WARNINGS``\ . Requires at least |MySQL| 4.1. ---compare-results-method +.. option:: --compare-results-method type: string; default: CHECKSUM; group: Comparisons - Method to use for "--compare" \ ``results``\ . This option has no effect + Method to use for :option:`--compare` \ ``results``\ . This option has no effect if \ ``--no-compare-results``\ is given. Available compare methods (case-insensitive): - CHECKSUM + * `` CHECKSUM`` Do \ ``CREATE TEMPORARY TABLE \`mk_upgrade\` AS query``\ then \ ``CHECKSUM TABLE \`mk_upgrade\```\ . This method is fast and simple but in - rare cases might it be inaccurate because the MySQL manual says: + rare cases might it be inaccurate because the |MySQL| manual says: .. code-block:: perl @@ -238,16 +235,16 @@ This tool accepts additional command-line arguments. Refer to the the tables are identical. - Requires at least MySQL 4.1. + Requires at least |MySQL| 4.1. - rows + * `` rows`` Compare rows one-by-one to find differences. This method has advantages and disadvantages. Its disadvantages are that it may be slower and it requires writing and reading outfiles from disk. Its advantages are that - it is universal (works for all versions of MySQL), it doesn't alter the query + it is universal (works for all versions of |MySQL|), it doesn't alter the query in any way, and it can find column value differences. The \ ``rows``\ method works as follows: @@ -264,13 +261,13 @@ This tool accepts additional command-line arguments. Refer to the 5. The temporary tables are analyzed to determine the differences. - The outfiles are written to the "--base-dir". + The outfiles are written to the :option:`--base-dir`. ---config +.. option:: --config type: Array @@ -279,13 +276,13 @@ This tool accepts additional command-line arguments. Refer to the ---continue-on-error +.. option:: --continue-on-error Continue working even if there is an error. ---convert-to-select +.. option:: --convert-to-select Convert non-SELECT statements to SELECTs and compare. @@ -298,28 +295,28 @@ This tool accepts additional command-line arguments. Refer to the ---daemonize +.. option:: --daemonize Fork to the background and detach from the shell. POSIX operating systems only. ---explain-hosts +.. option:: --explain-hosts Print connection information and exit. ---filter +.. option:: --filter type: string - Discard events for which this Perl code doesn't return true. + Discard events for which this *Perl* code doesn't return true. - This option is a string of Perl code or a file containing Perl code that gets + This option is a string of *Perl* code or a file containing *Perl* code that gets compiled into a subroutine with one argument: $event. This is a hashref. - If the given value is a readable file, then pt-upgrade reads the entire + If the given value is a readable file, then :program:`pt-upgrade` reads the entire file and uses its contents as the code. The file should not contain a shebang (#!/usr/bin/perl) line. @@ -358,10 +355,10 @@ This tool accepts additional command-line arguments. Refer to the Then specify \ ``--filter filter.txt``\ to read the code from filter.txt. - If the filter code won't compile, pt-upgrade will die with an error. + If the filter code won't compile, :program:`pt-upgrade` will die with an error. If the filter code does compile, an error may still occur at runtime if the code tries to do something wrong (like pattern match an undefined value). - pt-upgrade does not provide any safeguards so code carefully! + :program:`pt-upgrade` does not provide any safeguards so code carefully! An example filter that discards everything but SELECT statements: @@ -386,14 +383,14 @@ This tool accepts additional command-line arguments. Refer to the ---fingerprints +.. option:: --fingerprints Add query fingerprints to the standard query analysis report. This is mostly useful for debugging purposes. ---float-precision +.. option:: --float-precision type: int @@ -404,13 +401,13 @@ This tool accepts additional command-line arguments. Refer to the ---help +.. option:: --help Show help and exit. ---host +.. option:: --host short form: -h; type: string @@ -418,7 +415,7 @@ This tool accepts additional command-line arguments. Refer to the ---iterations +.. option:: --iterations type: int; default: 1 @@ -427,7 +424,7 @@ This tool accepts additional command-line arguments. Refer to the ---limit +.. option:: --limit type: string; default: 95%:20 @@ -441,7 +438,7 @@ This tool accepts additional command-line arguments. Refer to the ---log +.. option:: --log type: string @@ -449,7 +446,7 @@ This tool accepts additional command-line arguments. Refer to the ---max-different-rows +.. option:: --max-different-rows type: int; default: 10 @@ -458,7 +455,7 @@ This tool accepts additional command-line arguments. Refer to the ---order-by +.. option:: --order-by type: string; default: differences:sum @@ -466,7 +463,7 @@ This tool accepts additional command-line arguments. Refer to the ---password +.. option:: --password short form: -p; type: string @@ -474,7 +471,7 @@ This tool accepts additional command-line arguments. Refer to the ---pid +.. option:: --pid type: string @@ -486,7 +483,7 @@ This tool accepts additional command-line arguments. Refer to the ---port +.. option:: --port short form: -P; type: int @@ -494,7 +491,7 @@ This tool accepts additional command-line arguments. Refer to the ---query +.. option:: --query type: string @@ -505,7 +502,7 @@ This tool accepts additional command-line arguments. Refer to the ---reports +.. option:: --reports type: Hash; default: queries,differences,errors,statistics @@ -516,7 +513,7 @@ This tool accepts additional command-line arguments. Refer to the ---run-time +.. option:: --run-time type: time @@ -525,16 +522,16 @@ This tool accepts additional command-line arguments. Refer to the ---set-vars +.. option:: --set-vars type: string; default: wait_timeout=10000,query_cache_type=0 - Set these MySQL variables. Immediately after connecting to MySQL, this + Set these |MySQL| variables. Immediately after connecting to |MySQL|, this string will be appended to SET and executed. ---shorten +.. option:: --shorten type: int; default: 1024 @@ -553,7 +550,7 @@ This tool accepts additional command-line arguments. Refer to the ---socket +.. option:: --socket short form: -S; type: string @@ -561,19 +558,19 @@ This tool accepts additional command-line arguments. Refer to the ---temp-database +.. option:: --temp-database type: string Use this database for creating temporary tables. If given, this database is used for creating temporary tables for the - results comparison (see "--compare"). Otherwise, the current + results comparison (see :option:`--compare`). Otherwise, the current database (from the last event that specified its database) is used. ---temp-table +.. option:: --temp-table type: string; default: mk_upgrade @@ -581,7 +578,7 @@ This tool accepts additional command-line arguments. Refer to the ---user +.. option:: --user short form: -u; type: string @@ -589,22 +586,21 @@ This tool accepts additional command-line arguments. Refer to the ---version +.. option:: --version Show version and exit. ---zero-query-times +.. option:: --zero-query-times Zero the query times in the report. -*********** DSN OPTIONS -*********** +=========== These DSN options are used to create a DSN. Each option is given like @@ -614,7 +610,7 @@ if the value contains whitespace it must be quoted. DSN options are comma-separated. See the percona-toolkit manpage for full details. -\* A + * ``A`` dsn: charset; copy: yes @@ -622,7 +618,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* D + * ``D`` dsn: database; copy: yes @@ -630,7 +626,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* F + * ``F`` dsn: mysql_read_default_file; copy: yes @@ -638,7 +634,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* h + * ``h`` dsn: host; copy: yes @@ -646,7 +642,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* p + * ``p`` dsn: password; copy: yes @@ -654,7 +650,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* P + * ``p`` dsn: port; copy: yes @@ -662,7 +658,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* S + * ``S`` dsn: mysql_socket; copy: yes @@ -670,7 +666,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* u + * ``u`` dsn: user; copy: yes @@ -679,146 +675,57 @@ comma-separated. See the percona-toolkit manpage for full details. -*********** ENVIRONMENT -*********** +=========== -The environment variable \ ``PTDEBUG``\ enables verbose debugging output to STDERR. +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-upgrade ... > FILE 2>&1 + PTDEBUG=1 :program:`pt-upgrade` ... > FILE 2>&1 Be careful: debugging output is voluminous and can generate several megabytes of output. -******************* SYSTEM REQUIREMENTS -******************* +=================== -You need Perl, DBI, DBD::mysql, and some core packages that ought to be -installed in any reasonably new version of Perl. +You need *Perl* , ``DBI``, ``DBD::mysql``, and some core packages that ought to be +installed in any reasonably new version of *Perl* . -**** BUGS -**** +==== For a list of known bugs, see `http://www.percona.com/bugs/pt-upgrade `_. 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 -******* +======= -Daniel Nichter +*Daniel Nichter* -********************* -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 2009-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 -******* +======= - -pt-upgrade 1.0.1 +:program:`pt-upgrade` 1.0.1 diff --git a/docs/user/pt-variable-advisor.rst b/docs/user/source/pt-variable-advisor.rst similarity index 69% rename from docs/user/pt-variable-advisor.rst rename to docs/user/source/pt-variable-advisor.rst index bf97b224..8eca3e14 100644 --- a/docs/user/pt-variable-advisor.rst +++ b/docs/user/source/pt-variable-advisor.rst @@ -1,27 +1,31 @@ +.. program:: pt-variable-advisor -################### -pt-variable-advisor -################### + +================================ + :program:`pt-variable-advisor` +================================ .. highlight:: perl -**** NAME -**** +==== + + :program:`pt-variable-advisor` - Analyze |MySQL| variables and advise on possible problems. -pt-variable-advisor - Analyze MySQL variables and advise on possible problems. - - -******** SYNOPSIS -******** +======== -Usage: pt-variable-advisor [OPTION...] [DSN] +Usage +----- -pt-variable-advisor analyzes variables and advises on possible problems. +:: + + pt-variable-advisor [OPTION...] [DSN] + +:program:`pt-variable-advisor` analyzes variables and advises on possible problems. Get SHOW VARIABLES from localhost: @@ -40,9 +44,8 @@ Get SHOW VARIABLES output saved in vars.txt: -***** RISKS -***** +===== The following section is included to inform users about the potential risks, @@ -50,7 +53,7 @@ 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-variable-advisor reads MySQL's configuration and examines it and is thus +:program:`pt-variable-advisor` reads |MySQL|'s configuration and examines it and is thus very low risk. At the time of this release, we know of no bugs that could cause serious harm to @@ -61,29 +64,26 @@ 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-variable-advisor `_. -See also "BUGS" for more information on filing bugs and getting help. +See also :ref:`bugs` for more information on filing bugs and getting help. -*********** DESCRIPTION -*********** +=========== - -pt-variable-advisor examines \ ``SHOW VARIABLES``\ for bad values and settings +:program:`pt-variable-advisor` examines \ ``SHOW VARIABLES``\ for bad values and settings according to the "RULES" described below. It reports on variables that -match the rules, so you can find bad settings in your MySQL server. +match the rules, so you can find bad settings in your |MySQL| server. -At the time of this release, pt-variable-advisor only examples +At the time of this release, :program:`pt-variable-advisor` only examples \ ``SHOW VARIABLES``\ , but other input sources are planned like \ ``SHOW STATUS``\ and \ ``SHOW SLAVE STATUS``\ . -***** RULES -***** +===== -These are the rules that pt-variable-advisor will apply to SHOW VARIABLES. +These are the rules that :program:`pt-variable-advisor` will apply to SHOW VARIABLES. Each rule has three parts: an ID, a severity, and a description. The rule's ID is a short, unique name for the rule. It usually relates @@ -102,7 +102,7 @@ which is sort of a terse synopsis of the rule's meaning. At a higher verbosity, you'll see subsequent sentences. -auto_increment + * ``auto_increment`` severity: note @@ -113,16 +113,16 @@ auto_increment -concurrent_insert + * ``concurrent_insert`` severity: note - Holes (spaces left by deletes) in MyISAM tables might never be + Holes (spaces left by deletes) in |MyISAM| tables might never be reused. -connect_timeout + * ``connect_timeout`` severity: note @@ -131,7 +131,7 @@ connect_timeout -debug + * ``debug`` severity: crit @@ -140,17 +140,17 @@ debug -delay_key_write + * ``delay_key_write`` severity: warn - MyISAM index blocks are never flushed until necessary. If there is - a server crash, data corruption on MyISAM tables can be much worse than + |MyISAM| index blocks are never flushed until necessary. If there is + a server crash, data corruption on |MyISAM| tables can be much worse than usual. -flush + * ``flush`` severity: warn @@ -158,7 +158,7 @@ flush -flush_time + * ``flush_time`` severity: warn @@ -166,7 +166,7 @@ flush_time -have_bdb + * ``have_bdb`` severity: note @@ -175,7 +175,7 @@ have_bdb -init_connect + * ``init_connect`` severity: note @@ -183,7 +183,7 @@ init_connect -init_file + * ``init_file`` severity: note @@ -191,7 +191,7 @@ init_file -init_slave + * ``init_slave`` severity: note @@ -199,7 +199,7 @@ init_slave -innodb_additional_mem_pool_size + * ``innodb_additional_mem_pool_size`` severity: warn @@ -207,53 +207,53 @@ innodb_additional_mem_pool_size -innodb_buffer_pool_size + * ``innodb_buffer_pool_size`` severity: warn - The InnoDB buffer pool size is unconfigured. In a production + The |InnoDB| buffer pool size is unconfigured. In a production environment it should always be configured explicitly, and the default 10MB size is not good. -innodb_checksums + * ``innodb_checksums`` severity: warn - InnoDB checksums are disabled. Your data is not protected from + |InnoDB| checksums are disabled. Your data is not protected from hardware corruption or other errors! -innodb_doublewrite + * ``innodb_doublewrite`` severity: warn - InnoDB doublewrite is disabled. Unless you use a filesystem that + |InnoDB| doublewrite is disabled. Unless you use a filesystem that protects against partial page writes, your data is not safe! -innodb_fast_shutdown + * ``innodb_fast_shutdown`` severity: warn - InnoDB's shutdown behavior is not the default. This can lead to + |InnoDB|'s shutdown behavior is not the default. This can lead to poor performance, or the need to perform crash recovery upon startup. -innodb_flush_log_at_trx_commit-1 + * ``innodb_flush_log_at_trx_commit-1`` severity: warn - InnoDB is not configured in strictly ACID mode. If there + |InnoDB| is not configured in strictly ACID mode. If there is a crash, some transactions can be lost. -innodb_flush_log_at_trx_commit-2 + * ``innodb_flush_log_at_trx_commit-2`` severity: warn @@ -264,17 +264,17 @@ innodb_flush_log_at_trx_commit-2 -innodb_force_recovery + * ``innodb_force_recovery`` severity: warn - InnoDB is in forced recovery mode! This should be used only + |InnoDB| is in forced recovery mode! This should be used only temporarily when recovering from data corruption or other bugs, not for normal usage. -innodb_lock_wait_timeout + * ``innodb_lock_wait_timeout`` severity: warn @@ -283,26 +283,26 @@ innodb_lock_wait_timeout -innodb_log_buffer_size + * ``innodb_log_buffer_size`` severity: warn - The InnoDB log buffer size generally should not be set larger than - 16MB. If you are doing large BLOB operations, InnoDB is not really a good + The |InnoDB| log buffer size generally should not be set larger than + 16MB. If you are doing large BLOB operations, |InnoDB| is not really a good choice of engines anyway. -innodb_log_file_size + * ``innodb_log_file_size`` severity: warn - The InnoDB log file size is set to its default value, which is not + The |InnoDB| log file size is set to its default value, which is not usable on production systems. -innodb_max_dirty_pages_pct + * ``innodb_max_dirty_pages_pct`` severity: note @@ -311,7 +311,7 @@ innodb_max_dirty_pages_pct -flush_time + * ``flush_time`` severity: warn @@ -320,7 +320,7 @@ flush_time -key_buffer_size + * ``key_buffer_size`` severity: warn @@ -330,7 +330,7 @@ key_buffer_size -large_pages + * ``large_pages`` severity: note @@ -338,7 +338,7 @@ large_pages -locked_in_memory + * ``locked_in_memory`` severity: note @@ -346,7 +346,7 @@ locked_in_memory -log_warnings-1 + * ``log_warnings-1`` severity: note @@ -356,7 +356,7 @@ log_warnings-1 -log_warnings-2 + * ``log_warnings-2`` severity: note @@ -365,7 +365,7 @@ log_warnings-2 -low_priority_updates + * ``low_priority_updates`` severity: note @@ -374,7 +374,7 @@ low_priority_updates -max_binlog_size + * ``max_binlog_size`` severity: note @@ -382,7 +382,7 @@ max_binlog_size -max_connect_errors + * ``max_connect_errors`` severity: note @@ -391,7 +391,7 @@ max_connect_errors -max_connections + * ``max_connections`` severity: warn @@ -402,7 +402,7 @@ max_connections -myisam_repair_threads + * ``myisam_repair_threads`` severity: note @@ -412,7 +412,7 @@ myisam_repair_threads -old_passwords + * ``old_passwords`` severity: warn @@ -421,7 +421,7 @@ old_passwords -optimizer_prune_level + * ``optimizer_prune_level`` severity: warn @@ -430,7 +430,7 @@ optimizer_prune_level -port + * ``port`` severity: note @@ -438,7 +438,7 @@ port -query_cache_size-1 + * ``query_cache_size-1`` severity: note @@ -447,7 +447,7 @@ query_cache_size-1 -query_cache_size-2 + * ``query_cache_size-2`` severity: warn @@ -456,7 +456,7 @@ query_cache_size-2 -read_buffer_size-1 + * ``read_buffer_size-1`` severity: note @@ -465,7 +465,7 @@ read_buffer_size-1 -read_buffer_size-2 + * ``read_buffer_size-2`` severity: warn @@ -477,7 +477,7 @@ read_buffer_size-2 -read_rnd_buffer_size-1 + * ``read_rnd_buffer_size-1`` severity: note @@ -486,7 +486,7 @@ read_rnd_buffer_size-1 -read_rnd_buffer_size-2 + * ``read_rnd_buffer_size-2`` severity: warn @@ -496,7 +496,7 @@ read_rnd_buffer_size-2 -relay_log_space_limit + * ``relay_log_space_limit`` severity: warn @@ -505,7 +505,7 @@ relay_log_space_limit -slave_net_timeout + * ``slave_net_timeout`` severity: warn @@ -517,7 +517,7 @@ slave_net_timeout -slave_skip_errors + * ``slave_skip_errors`` severity: crit @@ -528,7 +528,7 @@ slave_skip_errors -sort_buffer_size-1 + * ``sort_buffer_size-1`` severity: note @@ -537,7 +537,7 @@ sort_buffer_size-1 -sort_buffer_size-2 + * ``sort_buffer_size-2`` severity: note @@ -548,7 +548,7 @@ sort_buffer_size-2 -sql_notes + * ``sql_notes`` severity: note @@ -557,7 +557,7 @@ sql_notes -sync_frm + * ``sync_frm`` severity: warn @@ -566,7 +566,7 @@ sync_frm -tx_isolation-1 + * ``tx_isolation-1`` severity: note @@ -574,7 +574,7 @@ tx_isolation-1 -tx_isolation-2 + * ``tx_isolation-2`` severity: warn @@ -583,18 +583,18 @@ tx_isolation-2 -expire_log_days + * ``expire_log_days`` severity: warn Binary logs are enabled, but automatic purging is not enabled. If you do not purge binary logs, your disk will fill up. If you delete - binary logs externally to MySQL, you will cause unwanted behaviors. - Always ask MySQL to purge obsolete logs, never delete them externally. + binary logs externally to |MySQL|, you will cause unwanted behaviors. + Always ask |MySQL| to purge obsolete logs, never delete them externally. -innodb_file_io_threads + * ``innodb_file_io_threads`` severity: note @@ -602,27 +602,27 @@ innodb_file_io_threads -innodb_data_file_path + * ``innodb_data_file_path`` severity: note - Auto-extending InnoDB files can consume a lot of disk space that is + Auto-extending |InnoDB| files can consume a lot of disk space that is very difficult to reclaim later. Some people prefer to set innodb_file_per_table and allocate a fixed-size file for ibdata1. -innodb_flush_method + * ``innodb_flush_method`` severity: note - Most production database servers that use InnoDB should set + Most production database servers that use |InnoDB| should set innodb_flush_method to O_DIRECT to avoid double-buffering, unless the I/O system is very low performance. -innodb_locks_unsafe_for_binlog + * ``innodb_locks_unsafe_for_binlog`` severity: warn @@ -631,18 +631,18 @@ innodb_locks_unsafe_for_binlog -innodb_support_xa + * ``innodb_support_xa`` severity: warn - MySQL's internal XA transaction support between InnoDB and the - binary log is disabled. The binary log might not match InnoDB's state + |MySQL|'s internal XA transaction support between |InnoDB| and the + binary log is disabled. The binary log might not match |InnoDB|'s state after crash recovery, and replication might drift out of sync due to out-of-order statements in the binary log. -log_bin + * ``log_bin`` severity: warn @@ -651,7 +651,7 @@ log_bin -log_output + * ``log_output`` severity: warn @@ -659,7 +659,7 @@ log_output -max_relay_log_size + * ``max_relay_log_size`` severity: note @@ -667,7 +667,7 @@ max_relay_log_size -myisam_recover_options + * ``myisam_recover_options`` severity: warn @@ -676,7 +676,7 @@ myisam_recover_options -storage_engine + * ``storage_engine`` severity: note @@ -684,7 +684,7 @@ storage_engine -sync_binlog + * ``sync_binlog`` severity: warn @@ -693,7 +693,7 @@ sync_binlog -tmp_table_size + * ``tmp_table_size`` severity: note @@ -704,7 +704,7 @@ tmp_table_size -old mysql version + * ``old mysql version`` severity: warn @@ -712,7 +712,7 @@ old mysql version -end-of-life mysql version + * ``end-of-life mysql version`` severity: note @@ -721,34 +721,33 @@ end-of-life mysql version -******* OPTIONS -******* +======= This tool accepts additional command-line arguments. Refer to the "SYNOPSIS" and usage information for details. ---ask-pass +.. option:: --ask-pass - Prompt for a password when connecting to MySQL. + Prompt for a password when connecting to |MySQL|. ---charset +.. option:: --charset short form: -A; type: string - Default character set. If the value is utf8, sets Perl's binmode on - STDOUT to utf8, passes the mysql_enable_utf8 option to DBD::mysql, and - runs SET NAMES UTF8 after connecting to MySQL. Any other value sets - binmode on STDOUT without the utf8 layer, and runs SET NAMES after - connecting to MySQL. + Default character set. If the value is utf8, sets *Perl* 's binmode on + ``STDOUT`` to utf8, passes the mysql_enable_utf8 option to ``DBD::mysql``, and + runs SET NAMES UTF8 after connecting to |MySQL|. Any other value sets + binmode on ``STDOUT`` without the utf8 layer, and runs SET NAMES after + connecting to |MySQL|. ---config +.. option:: --config type: Array @@ -757,14 +756,14 @@ This tool accepts additional command-line arguments. Refer to the ---daemonize +.. option:: --daemonize Fork to the background and detach from the shell. POSIX operating systems only. ---defaults-file +.. option:: --defaults-file short form: -F; type: string @@ -773,13 +772,13 @@ This tool accepts additional command-line arguments. Refer to the ---help +.. option:: --help Show help and exit. ---host +.. option:: --host short form: -h; type: string @@ -787,7 +786,7 @@ This tool accepts additional command-line arguments. Refer to the ---ignore-rules +.. option:: --ignore-rules type: hash @@ -798,7 +797,7 @@ This tool accepts additional command-line arguments. Refer to the ---password +.. option:: --password short form: -p; type: string @@ -806,7 +805,7 @@ This tool accepts additional command-line arguments. Refer to the ---pid +.. option:: --pid type: string @@ -818,7 +817,7 @@ This tool accepts additional command-line arguments. Refer to the ---port +.. option:: --port short form: -P; type: int @@ -826,16 +825,16 @@ This tool accepts additional command-line arguments. Refer to the ---set-vars +.. option:: --set-vars type: string; default: wait_timeout=10000 - Set these MySQL variables. Immediately after connecting to MySQL, this string + Set these |MySQL| variables. Immediately after connecting to |MySQL|, this string will be appended to SET and executed. ---socket +.. option:: --socket short form: -S; type: string @@ -843,7 +842,7 @@ This tool accepts additional command-line arguments. Refer to the ---source-of-variables +.. option:: --source-of-variables type: string; default: mysql @@ -853,7 +852,7 @@ This tool accepts additional command-line arguments. Refer to the ---user +.. option:: --user short form: -u; type: string @@ -861,7 +860,7 @@ This tool accepts additional command-line arguments. Refer to the ---verbose +.. option:: --verbose short form: -v; cumulative: yes; default: 1 @@ -871,16 +870,15 @@ This tool accepts additional command-line arguments. Refer to the ---version +.. option:: --version Show version and exit. -*********** DSN OPTIONS -*********** +=========== These DSN options are used to create a DSN. Each option is given like @@ -890,7 +888,7 @@ if the value contains whitespace it must be quoted. DSN options are comma-separated. See the percona-toolkit manpage for full details. -\* A + * ``A`` dsn: charset; copy: yes @@ -898,7 +896,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* D + * ``D`` dsn: database; copy: yes @@ -906,7 +904,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* F + * ``F`` dsn: mysql_read_default_file; copy: yes @@ -914,7 +912,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* h + * ``h`` dsn: host; copy: yes @@ -922,7 +920,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* p + * ``p`` dsn: password; copy: yes @@ -930,7 +928,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* P + * ``p`` dsn: port; copy: yes @@ -938,7 +936,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* S + * ``S`` dsn: mysql_socket; copy: yes @@ -946,7 +944,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* u + * ``u`` dsn: user; copy: yes @@ -955,146 +953,56 @@ comma-separated. See the percona-toolkit manpage for full details. -*********** ENVIRONMENT -*********** +=========== -The environment variable \ ``PTDEBUG``\ enables verbose debugging output to STDERR. +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-variable-advisor ... > FILE 2>&1 + PTDEBUG=1 :program:`pt-variable-advisor` ... > FILE 2>&1 Be careful: debugging output is voluminous and can generate several megabytes of output. -******************* SYSTEM REQUIREMENTS -******************* +=================== -You need Perl, DBI, DBD::mysql, and some core packages that ought to be -installed in any reasonably new version of Perl. +You need *Perl* , ``DBI``, ``DBD::mysql``, and some core packages that ought to be +installed in any reasonably new version of *Perl* . -**** BUGS -**** +==== For a list of known bugs, see `http://www.percona.com/bugs/pt-variable-advisor `_. 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 and Daniel Nichter +*Baron Schwartz* and *Daniel Nichter* -********************* -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-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 -******* +======= - -pt-variable-advisor 1.0.1 +:program:`pt-variable-advisor` 1.0.1 diff --git a/docs/user/pt-visual-explain.rst b/docs/user/source/pt-visual-explain.rst similarity index 76% rename from docs/user/pt-visual-explain.rst rename to docs/user/source/pt-visual-explain.rst index 2fa40979..9eff1261 100644 --- a/docs/user/pt-visual-explain.rst +++ b/docs/user/source/pt-visual-explain.rst @@ -1,32 +1,36 @@ +.. program:: pt-visual-explain -################# -pt-visual-explain -################# + +============================== + :program:`pt-visual-explain` +============================== .. highlight:: perl -**** NAME -**** +==== + + :program:`pt-visual-explain` - Format EXPLAIN output as a tree. -pt-visual-explain - Format EXPLAIN output as a tree. - - -******** SYNOPSIS -******** +======== -Usage: pt-visual-explain [OPTION...] [FILE...] +Usage +----- -pt-visual-explain transforms EXPLAIN output into a tree representation of +:: + + pt-visual-explain [OPTION...] [FILE...] + +:program:`pt-visual-explain` transforms EXPLAIN output into a tree representation of the query plan. If FILE is given, input is read from the file(s). With no FILE, or when FILE is -, read standard input. -Examples: - +Examples +-------- .. code-block:: perl @@ -38,9 +42,8 @@ Examples: -***** RISKS -***** +===== The following section is included to inform users about the potential risks, @@ -48,7 +51,7 @@ 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-visual-explain is read-only and very low-risk. +:program:`pt-visual-explain` is read-only and very low-risk. At the time of this release, we know of no bugs that could cause serious harm to users. @@ -58,34 +61,32 @@ 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-visual-explain `_. -See also "BUGS" for more information on filing bugs and getting help. +See also :ref:`bugs` for more information on filing bugs and getting help. -*********** DESCRIPTION -*********** +=========== - -pt-visual-explain reverse-engineers MySQL's EXPLAIN output into a query +:program:`pt-visual-explain` reverse-engineers |MySQL|'s EXPLAIN output into a query execution plan, which it then formats as a left-deep tree -- the same way the -plan is represented inside MySQL. It is possible to do this by hand, or to read +plan is represented inside |MySQL|. It is possible to do this by hand, or to read EXPLAIN's output directly, but it requires patience and expertise. Many people find a tree representation more understandable. -You can pipe input into pt-visual-explain or specify a filename at the +You can pipe input into :program:`pt-visual-explain` or specify a filename at the command line, including the magical '-' filename, which will read from standard input. It can do two things with the input: parse it for something that looks -like EXPLAIN output, or connect to a MySQL instance and run EXPLAIN on the +like EXPLAIN output, or connect to a |MySQL| instance and run EXPLAIN on the input. -When parsing its input, pt-visual-explain understands three formats: tabular +When parsing its input, :program:`pt-visual-explain` understands three formats: tabular like that shown in the mysql command-line client, vertical like that created by using the \G line terminator in the mysql command-line client, and tab separated. It ignores any lines it doesn't know how to parse. -When executing the input, pt-visual-explain replaces everything in the input +When executing the input, :program:`pt-visual-explain` replaces everything in the input up to the first SELECT keyword with 'EXPLAIN SELECT,' and then executes the -result. You must specify "--connect" to execute the input as a query. +result. You must specify :option:`--connect` to execute the input as a query. Either way, it builds a tree from the result set and prints it to standard output. For the following query, @@ -95,8 +96,7 @@ output. For the following query, select * from sakila.film_actor join sakila.film using(film_id); - -pt-visual-explain generates this query plan: +:program:`pt-visual-explain` generates this query plan: .. code-block:: perl @@ -124,15 +124,11 @@ output node -- the last step in the execution plan. In other words, read it like this: -1 - - Table scan the 'film' table, which accesses an estimated 952 rows. + * ``1`` Table scan the 'film' table, which accesses an estimated 952 rows. -2 - - For each row, find matching rows by doing an index lookup into the + * ``2`` For each row, find matching rows by doing an index lookup into the film_actor->idx_fk_film_id index with the value from sakila.film.film_id, then a bookmark lookup into the film_actor table. @@ -140,17 +136,16 @@ like this: For more information on how to read EXPLAIN output, please see `http://dev.mysql.com/doc/en/explain.html `_, and this talk titled "Query -Optimizer Internals and What's New in the MySQL 5.2 Optimizer," from Timour -Katchaounov, one of the MySQL developers: +Optimizer Internals and What's New in the |MySQL| 5.2 Optimizer," from Timour +Katchaounov, one of the |MySQL| developers: `http://maatkit.org/presentations/katchaounov_timour.pdf `_. -******* MODULES -******* +======= -This program is actually a runnable module, not just an ordinary Perl script. +This program is actually a runnable module, not just an ordinary *Perl* script. In fact, there are two modules embedded in it. This makes unit testing easy, but it also makes it easy for you to use the parsing and tree-building functionality if you want. @@ -161,7 +156,7 @@ like EXPLAIN output from it. The synopsis is as follows: .. code-block:: perl - require "pt-visual-explain"; + require :program:`pt-visual-explain`"; my $p = ExplainParser->new(); my $rows = $p->parse("some text"); # $rows is an arrayref of hashrefs. @@ -174,7 +169,7 @@ you. Here's the synopsis: .. code-block:: perl - require "pt-visual-explain"; + require :program:`pt-visual-explain`"; my $e = ExplainTree->new(); my $tree = $e->parse("some text", \%options); my $output = $e->pretty_print($tree); @@ -182,9 +177,8 @@ you. Here's the synopsis: -********* ALGORITHM -********* +========= This section explains the algorithm that converts EXPLAIN into a tree. You may @@ -209,42 +203,30 @@ of relationship the row has to the previous row c) what kind of operation the row represents. -\* - - SIMPLE means there are no subqueries or unions in the whole query. + * SIMPLE means there are no subqueries or unions in the whole query. -\* - - PRIMARY means there are, but this is the outermost SELECT. + * PRIMARY means there are, but this is the outermost SELECT. -\* - - [DEPENDENT] UNION means this result is UNIONed with the previous result (not + * [DEPENDENT] UNION means this result is UNIONed with the previous result (not row; a result might encompass more than one row). -\* - - UNION RESULT terminates a set of UNIONed results. + * UNION RESULT terminates a set of UNIONed results. -\* - - [DEPENDENT|UNCACHEABLE] SUBQUERY means a new sub-scope is opening. This is the + * [DEPENDENT|UNCACHEABLE] SUBQUERY means a new sub-scope is opening. This is the kind of subquery that happens in a WHERE clause, SELECT list or whatnot; it does not return a so-called "derived table." -\* - - DERIVED is a subquery in the FROM clause. + * DERIVED is a subquery in the FROM clause. @@ -355,7 +337,7 @@ The next question is how to find the last row that should be a child node of a UNION or DERIVED. I'll start with DERIVED, because the solution makes UNION easy. -Consider how MySQL numbers the SELECTs sequentially according to their position +Consider how |MySQL| numbers the SELECTs sequentially according to their position in the SQL, left-to-right. Since a DERIVED table encloses everything within it in a scope, which becomes a temporary table, there are only two things to think about: its child subqueries and unions (if any), and its next siblings in the @@ -401,8 +383,8 @@ Here's the output of EXPLAIN: The siblings all have id 1, and the middle one I care about is derived3. -(Notice MySQL doesn't execute them in the order I defined them, which is fine). -Now notice that MySQL prints out the rows in the opposite order I defined the +(Notice |MySQL| doesn't execute them in the order I defined them, which is fine). +Now notice that |MySQL| prints out the rows in the opposite order I defined the subqueries: 6, 3, 2. It always seems to do this, and there might be other methods of finding the scope boundaries including looking for the lower boundary of the next largest sibling, but this is a good enough heuristic. I am forced @@ -425,7 +407,7 @@ includes every row between 3 and 5. Finally, there are non-derived subqueries to deal with as well. In this case I can't look at siblings to find the end of the scope as I did for DERIVED. I -have to trust that MySQL executes depth-first. Here's an example: +have to trust that |MySQL| executes depth-first. Here's an example: .. code-block:: perl @@ -454,22 +436,16 @@ have to trust that MySQL executes depth-first. Here's an example: In order, the tree should be built like this: -\* - - See row 1. + * See row 1. -\* - - See row 2. It's a higher id than 1, so it's a subquery, along with every other + * See row 2. It's a higher id than 1, so it's a subquery, along with every other row whose id is greater than 2. -\* - - Inside this scope, see 2 and 2 and JOIN them. See 4. It's a higher id than 2, + * Inside this scope, see 2 and 2 and JOIN them. See 4. It's a higher id than 2, so it's again a subquery; recurse. After that, see 3, which is also higher; recurse. @@ -529,13 +505,13 @@ Armed with this knowledge, it's possible to use recursion to turn the parent-child relationship between all the rows into a tree representing the execution plan. -MySQL prints the rows in execution order, even the forward and backward +|MySQL| prints the rows in execution order, even the forward and backward references. At any given scope, the rows are processed as a left-deep tree. -MySQL does not do "bushy" execution plans. It begins with a table, finds a +|MySQL| does not do "bushy" execution plans. It begins with a table, finds a matching row in the next table, and continues till the last table, when it emits a row. When it runs out, it backtracks till it can find the next row and repeats. There are subtleties of course, but this is the basic plan. This is -why MySQL transforms all RIGHT OUTER JOINs into LEFT OUTER JOINs and cannot do +why |MySQL| transforms all RIGHT OUTER JOINs into LEFT OUTER JOINs and cannot do FULL OUTER JOIN. This means in any given scope, say @@ -563,10 +539,9 @@ The execution plan looks like a depth-first traversal of this tree: The JOIN might not be a JOIN. It might be a subquery, for example. This comes from the type column of EXPLAIN. The documentation says this is a "join type," -but I think "access type" is more accurate, because it's "how MySQL accesses +but I think "access type" is more accurate, because it's "how |MySQL| accesses rows." - -pt-visual-explain decorates the tree significantly more than just turning + :program:`pt-visual-explain` decorates the tree significantly more than just turning rows into nodes. Each node may get a series of transformations that turn it into a subtree of more than one node. For example, an index scan not marked with 'Using index' must do a bookmark lookup into the table rows; that is a @@ -574,41 +549,40 @@ three-node subtree. However, after the above node-ordering and scoping stuff, the rest of the process is pretty simple. -******* OPTIONS -******* +======= This tool accepts additional command-line arguments. Refer to the "SYNOPSIS" and usage information for details. ---ask-pass +.. option:: --ask-pass - Prompt for a password when connecting to MySQL. + Prompt for a password when connecting to |MySQL|. ---charset +.. option:: --charset short form: -A; type: string - Default character set. If the value is utf8, sets Perl's binmode on - STDOUT to utf8, passes the mysql_enable_utf8 option to DBD::mysql, and - runs SET NAMES UTF8 after connecting to MySQL. Any other value sets - binmode on STDOUT without the utf8 layer, and runs SET NAMES after - connecting to MySQL. + Default character set. If the value is utf8, sets *Perl* 's binmode on + ``STDOUT`` to utf8, passes the mysql_enable_utf8 option to ``DBD::mysql``, and + runs SET NAMES UTF8 after connecting to |MySQL|. Any other value sets + binmode on ``STDOUT`` without the utf8 layer, and runs SET NAMES after + connecting to |MySQL|. ---clustered-pk +.. option:: --clustered-pk Assume that PRIMARY KEY index accesses don't need to do a bookmark lookup to - retrieve rows. This is the case for InnoDB. + retrieve rows. This is the case for |InnoDB|. ---config +.. option:: --config type: Array @@ -617,18 +591,18 @@ This tool accepts additional command-line arguments. Refer to the ---connect +.. option:: --connect - Treat input as a query, and obtain EXPLAIN output by connecting to a MySQL + Treat input as a query, and obtain EXPLAIN output by connecting to a |MySQL| instance and running EXPLAIN on the query. When this option is given, - pt-visual-explain uses the other connection-specific options such as - "--user" to connect to the MySQL instance. If you have a .my.cnf file, + :program:`pt-visual-explain` uses the other connection-specific options such as + :option:`--user` to connect to the |MySQL| instance. If you have a .my.cnf file, it will read it, so you may not need to specify any connection-specific options. ---database +.. option:: --database short form: -D; type: string @@ -636,7 +610,7 @@ This tool accepts additional command-line arguments. Refer to the ---defaults-file +.. option:: --defaults-file short form: -F; type: string @@ -645,7 +619,7 @@ This tool accepts additional command-line arguments. Refer to the ---format +.. option:: --format type: string; default: tree @@ -664,13 +638,13 @@ This tool accepts additional command-line arguments. Refer to the ---help +.. option:: --help Show help and exit. ---host +.. option:: --host short form: -h; type: string @@ -678,7 +652,7 @@ This tool accepts additional command-line arguments. Refer to the ---password +.. option:: --password short form: -p; type: string @@ -686,7 +660,7 @@ This tool accepts additional command-line arguments. Refer to the ---pid +.. option:: --pid type: string @@ -701,7 +675,7 @@ This tool accepts additional command-line arguments. Refer to the ---port +.. option:: --port short form: -P; type: int @@ -709,16 +683,16 @@ This tool accepts additional command-line arguments. Refer to the ---set-vars +.. option:: --set-vars type: string; default: wait_timeout=10000 - Set these MySQL variables. Immediately after connecting to MySQL, this + Set these |MySQL| variables. Immediately after connecting to |MySQL|, this string will be appended to SET and executed. ---socket +.. option:: --socket short form: -S; type: string @@ -726,7 +700,7 @@ This tool accepts additional command-line arguments. Refer to the ---user +.. option:: --user short form: -u; type: string @@ -734,16 +708,15 @@ This tool accepts additional command-line arguments. Refer to the ---version +.. option:: --version Show version and exit. -*********** DSN OPTIONS -*********** +=========== These DSN options are used to create a DSN. Each option is given like @@ -753,7 +726,7 @@ if the value contains whitespace it must be quoted. DSN options are comma-separated. See the percona-toolkit manpage for full details. -\* A + * ``A`` dsn: charset; copy: yes @@ -761,7 +734,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* D + * ``D`` dsn: database; copy: yes @@ -769,7 +742,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* F + * ``F`` dsn: mysql_read_default_file; copy: yes @@ -777,7 +750,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* h + * ``h`` dsn: host; copy: yes @@ -785,7 +758,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* p + * ``p`` dsn: password; copy: yes @@ -793,7 +766,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* P + * ``p`` dsn: port; copy: yes @@ -801,7 +774,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* S + * ``S`` dsn: mysql_socket; copy: yes @@ -809,7 +782,7 @@ comma-separated. See the percona-toolkit manpage for full details. -\* u + * ``u`` dsn: user; copy: yes @@ -818,146 +791,57 @@ comma-separated. See the percona-toolkit manpage for full details. -*********** ENVIRONMENT -*********** +=========== -The environment variable \ ``PTDEBUG``\ enables verbose debugging output to STDERR. +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-visual-explain ... > FILE 2>&1 + PTDEBUG=1 :program:`pt-visual-explain` ... > FILE 2>&1 Be careful: debugging output is voluminous and can generate several megabytes of output. -******************* SYSTEM REQUIREMENTS -******************* +=================== -You need Perl, DBI, DBD::mysql, and some core packages that ought to be -installed in any reasonably new version of Perl. +You need *Perl* , ``DBI``, ``DBD::mysql``, and some core packages that ought to be +installed in any reasonably new version of *Perl* . -**** BUGS -**** +==== For a list of known bugs, see `http://www.percona.com/bugs/pt-visual-explain `_. 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 +*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 2007-2011 Baron Schwartz, 2011 Percona Inc. +This program is copyright 2007-2011 *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 -******* +======= - -pt-visual-explain 1.0.1 + :program:`pt-visual-explain` 1.0.1 diff --git a/docs/user/source/release-notes.rst b/docs/user/source/release-notes.rst new file mode 100644 index 00000000..5071f157 --- /dev/null +++ b/docs/user/source/release-notes.rst @@ -0,0 +1,198 @@ +====================================== + |Percona| |XtraBackup| Release Notes +====================================== + +|Percona| |XtraBackup| 1.6.2 +============================ + +Percona is glad to announce the release of Percona XtraBackup 1.6.2 on 25 July, 2011 (Downloads are available `here `_ and from the `Percona Software Repositories `_). + +This release is purely composed of bug fixes and is the current stable release of |Percona| |Xtrabackup|. + +All of |Percona|'s software is open-source and free, all the details of the release and its development process can be found in the `1.6.2 milestone at Launchpad `_. + +New Options +----------- + +:option:`--version` +~~~~~~~~~~~~~~~~~~~ + + The :option:`--version` option has been added to the |xtrabackup| binary for printing its version. Previously, the version was displayed only while executing the binary without arguments or performing a backup. Bug Fixed: `#610614 `_ (Alexey Kopytov). + +Changes +------- + + * As exporting tables should only be used with :term:`innodb_file_per_table` set in the server, the variable is checked by |xtrabackup| when using the :option:`--export ` option. It will fail before applying the archived log without producing a potentially unusable backup. Bug Fixed: `#758888 `_ (Alexey Kopytov). + +Bugs Fixed +---------- + + * When creating an :term:`InnoDB` with its own tablespace after taking a full backup, if the log files have been flushed, taking an incremental backup based on that full one would not contain the added table. This has been corrected by explicitly creating the tablespace before applying the delta files in such cases. Bug Fixed: `#766607 `_ (Alexey Kopytov). + + * In some cases, |innobackupex| ignored the specified |xtrabackup| binary with the :option:`--ibbackup` option. Bug Fixed: `#729497 `_ (Stewart Smith). + + * Minor file descriptors leaks in error cases were fixed. Bug Fixed: `#803718 `_ (Stewart Smith). + +Other Changes +------------- + + * Improvements and fixes on the XtraBackup Test Suite: `#744303 `_, `#787966 < `_ (Alexey Kopytov) + + * Improvements and fixes on platform-specific distribution: `#785556 `_ (Ignacio Nin) + + * Improvements and fixes on the XtraBackup Documentation: `#745185 `_, `#721339 `_ (Rodrigo Gadea) + +|Percona| |XtraBackup| 1.6 +========================== + +Released on April 12, 2011 (Downloads are available `here `_ and from the `Percona Software Repositories `_.) + +Options Added +------------- + +* Added option :option:`--extra-lsndir` to |innobackupex|. When specified for the backup phase, the option is passed to |xtrabackup|, and :term:`LSN` information is stored with the file in the specified directory. This is needed so that :term:`LSN` information is preserved during stream backup. (Vadim Tkachenko) + +* Added option :option:`--incremental-lsn` to |innobackupex|. If specified, this option is passed directly to the |xtrabackup| binary and :program:`--incremental-basedir` is ignored. (Vadim Tkachenko) + +* Added option :option:`--incremental-dir` to |innobackupex|. This option is passed directly to the |xtrabackup| binary. (Vadim Tkachenko) + +* Added option :option:`--safe-slave-backup` to |innobackupex|. (Daniel Nichter) + +* Added option :option:`--safe-slave-backup-timeout` to |innobackupex|. (Daniel Nichter) + +Other Changes +------------- + +* Eliminated some compiler warnings. (Stewart Smith) + +* Ported |XtraBackup| to |MySQL| 5.1.55, |MySQL| 5.5.9, |Percona Server| 5.1.55-12.6, and |Percona Server| 5.5.9-20.1 code bases. The :command:`xtrabackup_55` binary is now based on |Percona Server| 5.5, rather than |MySQL| 5.5. Support for building against |InnoDB| plugin in |MySQL| 5.1 has been removed. (Alexey Kopytov) + +* Updates were made to the built-in |innobackupex| usage docs. (Baron Schwartz, Fred Linhoss) + +* Added a manual page for |XtraBackup|. (Aleksandr Kuzminsky) + +* Disabled auto-creating :file:`ib_logfile*` when |innobackupex| is called with :option:`--redo-only` or with :option:`--incremental-dir`. If necessary :file:`ib_logfile*` can be created later with :command:`xtrabackup --prepare` call. (Vadim Tkachenko) + +* Fixed |xtrabackup| exit code to improve portability: ``EXIT_SUCCESS`` on success and ``EXIT_FAILURE`` on a failure. (Aleksandr Kuzminsky) + +* For portability, the |XtraBackup| build script now tries to link with ``libaio`` only on Linux. (Aleksandr Kuzminsky) + +Bugs Fixed +---------- + +* `Bug #368945 `_ - When option :option:`--prepare` was specified, an error message was requesting that ``datadir`` be set, even though it's not a required option. (Vadim Tkachenko) + +* `Bug #420181 `_ - The |innobackupex| script now backs up :term:`.CSV` tables. (Valentine Gostev) + +* `Bug #597384 `_ - The ``innobackup`` :option:`--include` option now handles non-|InnoDB| tables. (Vadim Tkachenko) + +* `Bug #606981 `_ - Streaming |InnoDB| files with |tar4ibd| could lead to filesystem hangs when |InnoDB| was configured to access data files with the ``O_DIRECT`` flag. The reason was that |tar4ibd| did not have support for ``O_DIRECT`` and simultaneous ``O_DIRECT`` + non-``O_DIRECT`` access to a file on Linux is disallowed. Fixed |innobackupex| and |tar4ibd| to use ``O_DIRECT`` on input |InnoDB| files if the value of ``innodb_flush_method`` is ``O_DIRECT`` in the |InnoDB| configuration. (Alexey Kopytov) + +* `Bug #646647 `_ - Removed the bogus warning about invalid data in the Perl version string in |innobackupex|. (Baron Schwartz) + +* `Bug #672384 `_ - When no log files can be found in the backup directory while executing :option:`xtrabackup --stats`, a descriptive error message is printed instead of crashing. (Alexey Kopytov) + +* `Bug #688211 `_ - Using the :option:`--password` option with |innobackupex| to specify MySQL passwords containing special shell characters (such as "&") did not work, even when the option value was properly quoted. + +* `Bug #688417 `_ - It's now possible to do incremental backups for compressed |InnoDB| tables. + +* `Bug #701767 `_ - The script ``innobackupex-1.5.1`` was renamed to |innobackupex|. Symbolic link ``innobackupex-1.5.1`` was created for backupward compatibility. (Vadim Tkachenko) + +* `Bug #703070 `_ - ``xtrabackup_55`` crashed with an assertion failure on non-Linux platforms. (Alexey Kopytov) + +* `Bug #703077 `_ - Building |xtrabackup| could fail on some platforms due to an incorrect argument to ``CMake``. Fixed by changing the ``-DWITH_ZLIB`` argument to lowercase, because that's what the ``CMake`` scripts actually expect. (Alexey Kopytov) + +* `Bug #713799 `_ - Dropping a table during a backup process could result in assertion failure in |xtrabackup|. Now it continues with a warning message about the dropped table. (Alexey Kopytov) + +* `Bug #717784 `_ - Performing parallel backups with the :option:`--parallel` option could cause |xtrabackup| to fail with the "cannot mkdir" error. (Alexey Kopytov) + +Percona |XtraBackup| 1.5-Beta +============================= + +Released December 13, 2010 (`downloads `_) + +This release adds additional functionality to Percona |XtraBackup| 1.4, the current general availability version of |XtraBackup|. This is a beta release. + +Functionality Added or Changes +------------------------------ + +* Support for |MySQL| 5.5 databases has been implemented. (Yasufumi Kinoshita) + +* |XtraBackup| can now be built from the |MySQL| 5.1.52, |MySQL| 5.5.7, or |Percona Server| 5.1.53-12 code bases (fixes bug `#683507 `_). (Alexey Kopytov) + +* The program is now distributed as three separate binaries: + + * |xtrabackup| - for use with |Percona Server| with the built-in |InnoDB| plugin + + * :command:`xtrabackup_51` - for use with MySQL 5.0 & 5.1 with built-in |InnoDB| + + * :command:`xtrabackup_55` - for use with |MySQL| 5.5 (this binary is not provided for the FreeBSD platform) + +* Backing up only specific tables can now be done by specifying them in a file, using the :option:`--tables-file`. (Yasufumi Kinoshita & Daniel Nichter) + +* Additional checks were added to monitor the rate the log file is being overwritten, to determine if |XtraBackup| is keeping up. If the log file is being overwritten faster than |XtraBackup| can keep up, a warning is given that the backup may be inconsistent. (Yasufumi Kinoyasu) + +* The |XtraBackup| binaries are now compiled with the ``-O3`` :command:`gcc` option, which may improve backup speed in stream mode in some cases. + +* It is now possible to copy multiple data files concurrently in parallel threads when creating a backup, using the :option:`--parallel` option. See `The xtrabackup Option Reference `_ and `Parallel Backups `_. (Alexey Kopytov) + +Bugs Fixed +---------- + +* `Bug #683507 `_ - |xtrabackup| has been updated to build from the |MySQL| 5.1.52, |MySQL| 5.5.7, or |Percona Server| 5.1.53-12 code bases. (Alexey Kopytov) + +Percona |XtraBackup| 1.4 +======================== + +Released on November 22, 2010 + +Percona |XtraBackup| version 1.4 fixes problems related to incremental backups. If you do incremental backups, it's strongly recommended that you upgrade to this release. + +Functionality Added or Changed +------------------------------ + +* `Incremental backups `_ have changed and now allow the restoration of full backups containing certain rollback transactions that previously caused problems. Please see `Preparing the Backups `_ and the :option:`--apply-log-only`. (From |innobackupex|, the :option:`--redo-only` option should be used.) (Yasufumi Kinoshita) + + * The |XtraBackup| Test Suite was implemented and is now a standard part of each distribution. (Aleksandr Kuzminsky) + +* Other New Features + + * The :option:`--prepare` now reports ``xtrabackup_binlog_pos_innodb`` if the information exists. (Yasufumi Kinoshita) + + * When :option:`--prepare` is used to restore a partial backup, the data dictionary is now cleaned and contains only tables that exist in the backup. (Yasufumi Kinoshita) + + * The :option:`--table` was extended to accept several regular expression arguments, separated by commas. (Yasufumi Kinoshita) + +* Other Changes + + * Ported to the |Percona Server| 5.1.47 code base. (Yasufumi Kinoshita) + + * |XtraBackup| now uses the memory allocators of the host operating system, rather than the built-in |InnoDB| allocators (see `Using Operating System Memory Allocators `_). (Yasufumi Kinoshita) + +Bugs Fixed +---------- + +* `Bug #595770 `_ - XtraBack binaries are now shipped containing debug symbols by default. (Aleksandr Kuzminsky) + +* `Bug #589639 `_ - Fixed a problem of hanging when tablespaces were deleted during the recovery process. (Yasufumi Kinoshita) + +* `Bug #611960 `_ - Fixed a segmentation fault in |xtrabackup|. (Yasufumi Kinoshita) + +* Miscellaneous important fixes related to incremental backups. + +Version 1.3 (unreleased) +======================== + +Major changes: +-------------- + +* Port to |Percona Server| 5.1.47-11 + +* Separate into two binaries - xtrabackup for |Percona Server| and xtrabackup_50 for |MySQL| 5.x. + +Fixed Bugs: +----------- + +* Fixed `Bug #561106 `_: incremental crash + +* Fixed duplicate ``close()`` problem at ``xtrabackup_copy_datafile()``. diff --git a/docs/user/release_notes.rst b/docs/user/source/release_notes.rst similarity index 100% rename from docs/user/release_notes.rst rename to docs/user/source/release_notes.rst diff --git a/docs/user/system_requirements.rst b/docs/user/source/system_requirements.rst similarity index 100% rename from docs/user/system_requirements.rst rename to docs/user/source/system_requirements.rst diff --git a/docs/user/tools.rst b/docs/user/source/tools.rst similarity index 100% rename from docs/user/tools.rst rename to docs/user/source/tools.rst diff --git a/docs/user/version.rst b/docs/user/source/version.rst similarity index 100% rename from docs/user/version.rst rename to docs/user/source/version.rst