14
pt-variable-advisor - Analyze MySQL variables and advise on possible problems.
22
Usage: pt-variable-advisor [OPTION...] [DSN]
24
pt-variable-advisor analyzes variables and advises on possible problems.
26
Get SHOW VARIABLES from localhost:
31
pt-variable-advisor localhost
34
Get SHOW VARIABLES output saved in vars.txt:
39
pt-variable-advisor --source-of-variables vars.txt
48
The following section is included to inform users about the potential risks,
49
whether known or unknown, of using this tool. The two main categories of risks
50
are those created by the nature of the tool (e.g. read-only tools vs. read-write
51
tools) and those created by bugs.
53
pt-variable-advisor reads MySQL's configuration and examines it and is thus
56
At the time of this release, we know of no bugs that could cause serious harm to
59
The authoritative source for updated information is always the online issue
60
tracking system. Issues that affect this tool will be marked as such. You can
61
see a list of such issues at the following URL:
62
`http://www.percona.com/bugs/pt-variable-advisor <http://www.percona.com/bugs/pt-variable-advisor>`_.
64
See also "BUGS" for more information on filing bugs and getting help.
72
pt-variable-advisor examines \ ``SHOW VARIABLES``\ for bad values and settings
73
according to the "RULES" described below. It reports on variables that
74
match the rules, so you can find bad settings in your MySQL server.
76
At the time of this release, pt-variable-advisor only examples
77
\ ``SHOW VARIABLES``\ , but other input sources are planned like \ ``SHOW STATUS``\
78
and \ ``SHOW SLAVE STATUS``\ .
86
These are the rules that pt-variable-advisor will apply to SHOW VARIABLES.
87
Each rule has three parts: an ID, a severity, and a description.
89
The rule's ID is a short, unique name for the rule. It usually relates
90
to the variable that the rule examines. If a variable is examined by
91
several rules, then the rules' IDs are numbered like "-1", "-2", "-N".
93
The rule's severity is an indication of how important it is that this
94
rule matched a query. We use NOTE, WARN, and CRIT to denote these
97
The rule's description is a textual, human-readable explanation of
98
what it means when a variable matches this rule. Depending on the
99
verbosity of the report you generate, you will see more of the text in
100
the description. By default, you'll see only the first sentence,
101
which is sort of a terse synopsis of the rule's meaning. At a higher
102
verbosity, you'll see subsequent sentences.
109
Are you trying to write to more than one server in a dual-master or
110
ring replication configuration? This is potentially very dangerous and in
111
most cases is a serious mistake. Most people's reasons for doing this are
112
actually not valid at all.
120
Holes (spaces left by deletes) in MyISAM tables might never be
129
A large value of this setting can create a denial of service
138
Servers built with debugging capability should not be used in
139
production because of the large performance impact.
147
MyISAM index blocks are never flushed until necessary. If there is
148
a server crash, data corruption on MyISAM tables can be much worse than
157
This option might decrease performance greatly.
165
This option might decrease performance greatly.
173
The BDB engine is deprecated. If you aren't using it, you should
174
disable it with the skip_bdb option.
182
The init_connect option is enabled on this server.
190
The init_file option is enabled on this server.
198
The init_slave option is enabled on this server.
202
innodb_additional_mem_pool_size
206
This variable generally doesn't need to be larger than 20MB.
210
innodb_buffer_pool_size
214
The InnoDB buffer pool size is unconfigured. In a production
215
environment it should always be configured explicitly, and the default
216
10MB size is not good.
224
InnoDB checksums are disabled. Your data is not protected from
225
hardware corruption or other errors!
233
InnoDB doublewrite is disabled. Unless you use a filesystem that
234
protects against partial page writes, your data is not safe!
242
InnoDB's shutdown behavior is not the default. This can lead to
243
poor performance, or the need to perform crash recovery upon startup.
247
innodb_flush_log_at_trx_commit-1
251
InnoDB is not configured in strictly ACID mode. If there
252
is a crash, some transactions can be lost.
256
innodb_flush_log_at_trx_commit-2
260
Setting innodb_flush_log_at_trx_commit to 0 has no performance
261
benefits over setting it to 2, and more types of data loss are possible.
262
If you are trying to change it from 1 for performance reasons, you should
263
set it to 2 instead of 0.
267
innodb_force_recovery
271
InnoDB is in forced recovery mode! This should be used only
272
temporarily when recovering from data corruption or other bugs, not for
277
innodb_lock_wait_timeout
281
This option has an unusually long value, which can cause
282
system overload if locks are not being released.
286
innodb_log_buffer_size
290
The InnoDB log buffer size generally should not be set larger than
291
16MB. If you are doing large BLOB operations, InnoDB is not really a good
292
choice of engines anyway.
300
The InnoDB log file size is set to its default value, which is not
301
usable on production systems.
305
innodb_max_dirty_pages_pct
309
The innodb_max_dirty_pages_pct is lower than the default. This can
310
cause overly aggressive flushing and add load to the I/O system.
318
This setting is likely to cause very bad performance every
327
The key buffer size is unconfigured. In a production
328
environment it should always be configured explicitly, and the default
329
8MB size is not good.
337
Large pages are enabled.
345
The server is locked in memory with --memlock.
353
Log_warnings is disabled, so unusual events such as statements
354
unsafe for replication and aborted connections will not be logged to the
363
Log_warnings must be set greater than 1 to log unusual events such
364
as aborted connections.
372
The server is running with non-default lock priority for updates.
373
This could cause update queries to wait unexpectedly for read queries.
381
The max_binlog_size is smaller than the default of 1GB.
389
max_connect_errors should probably be set as large as your platform
398
If the server ever really has more than a thousand threads running,
399
then the system is likely to spend more time scheduling threads than
400
really doing useful work. This variable's value should be considered in
401
light of your workload.
405
myisam_repair_threads
409
myisam_repair_threads > 1 enables multi-threaded repair, which is
410
relatively untested and is still listed as beta-quality code in the
411
official documentation.
419
Old-style passwords are insecure. They are sent in plain text
424
optimizer_prune_level
428
The optimizer will use an exhaustive search when planning complex
429
queries, which can cause the planning process to take a long time.
437
The server is listening on a non-default port.
445
The query cache does not scale to large sizes and can cause unstable
446
performance when larger than 128MB, especially on multi-core machines.
454
The query cache can cause severe performance problems when it is
455
larger than 256MB, especially on multi-core machines.
463
The read_buffer_size variable should generally be left at its
464
default unless an expert determines it is necessary to change it.
472
The read_buffer_size variable should not be larger than 8MB. It
473
should generally be left at its default unless an expert determines it is
474
necessary to change it. Making it larger than 2MB can hurt performance
475
significantly, and can make the server crash, swap to death, or just
476
become extremely unstable.
480
read_rnd_buffer_size-1
484
The read_rnd_buffer_size variable should generally be left at its
485
default unless an expert determines it is necessary to change it.
489
read_rnd_buffer_size-2
493
The read_rnd_buffer_size variable should not be larger than 4M. It
494
should generally be left at its default unless an expert determines it is
495
necessary to change it.
499
relay_log_space_limit
503
Setting relay_log_space_limit is relatively rare, and could cause
504
an increased risk of previously unknown bugs in replication.
512
This variable is set too high. This is too long to wait before
513
noticing that the connection to the master has failed and retrying. This
514
should probably be set to 60 seconds or less. It is also a good idea to
515
use pt-heartbeat to ensure that the connection does not appear to time out
516
when the master is simply idle.
524
You should not set this option. If replication is having errors,
525
you need to find and resolve the cause of that; it is likely that your
526
slave's data is different from the master. You can find out with
535
The sort_buffer_size variable should generally be left at its
536
default unless an expert determines it is necessary to change it.
544
The sort_buffer_size variable should generally be left at its
545
default unless an expert determines it is necessary to change it. Making
546
it larger than a few MB can hurt performance significantly, and can make
547
the server crash, swap to death, or just become extremely unstable.
555
This server is configured not to log Note level warnings to the
564
It is best to set sync_frm so that .frm files are flushed safely to
565
disk in case of a server crash.
573
This server's transaction isolation level is non-default.
581
Most applications should use the default REPEATABLE-READ transaction
582
isolation level, or in a few cases READ-COMMITTED.
590
Binary logs are enabled, but automatic purging is not enabled. If
591
you do not purge binary logs, your disk will fill up. If you delete
592
binary logs externally to MySQL, you will cause unwanted behaviors.
593
Always ask MySQL to purge obsolete logs, never delete them externally.
597
innodb_file_io_threads
601
This option is useless except on Windows.
605
innodb_data_file_path
609
Auto-extending InnoDB files can consume a lot of disk space that is
610
very difficult to reclaim later. Some people prefer to set
611
innodb_file_per_table and allocate a fixed-size file for ibdata1.
619
Most production database servers that use InnoDB should set
620
innodb_flush_method to O_DIRECT to avoid double-buffering, unless the I/O
621
system is very low performance.
625
innodb_locks_unsafe_for_binlog
629
This option makes point-in-time recovery from binary logs, and
630
replication, untrustworthy if statement-based logging is used.
638
MySQL's internal XA transaction support between InnoDB and the
639
binary log is disabled. The binary log might not match InnoDB's state
640
after crash recovery, and replication might drift out of sync due to
641
out-of-order statements in the binary log.
649
Binary logging is disabled, so point-in-time recovery and
650
replication are not possible.
658
Directing log output to tables has a high performance impact.
666
A custom max_relay_log_size is defined.
670
myisam_recover_options
674
myisam_recover_options should be set to some value such as
675
BACKUP,FORCE to ensure that table corruption is noticed.
683
The server is using a non-standard storage engine as default.
691
Binary logging is enabled, but sync_binlog isn't configured so that
692
every transaction is flushed to the binary log for durability.
700
The effective minimum size of in-memory implicit temporary tables
701
used internally during query execution is min(tmp_table_size,
702
max_heap_table_size), so max_heap_table_size should be at least as large
711
These are the recommended minimum version for each major release: 3.23, 4.1.20, 5.0.37, 5.1.30.
715
end-of-life mysql version
719
Every release older than 5.1 is now officially end-of-life.
729
This tool accepts additional command-line arguments. Refer to the
730
"SYNOPSIS" and usage information for details.
735
Prompt for a password when connecting to MySQL.
741
short form: -A; type: string
743
Default character set. If the value is utf8, sets Perl's binmode on
744
STDOUT to utf8, passes the mysql_enable_utf8 option to DBD::mysql, and
745
runs SET NAMES UTF8 after connecting to MySQL. Any other value sets
746
binmode on STDOUT without the utf8 layer, and runs SET NAMES after
755
Read this comma-separated list of config files; if specified, this must be the
756
first option on the command line.
760
--[no]continue-on-error
764
Continue working even if there is an error.
770
Fork to the background and detach from the shell. POSIX
771
operating systems only.
777
short form: -F; type: string
779
Only read mysql options from the given file. You must give an absolute
792
short form: -h; type: string
802
Ignore these rule IDs.
804
Specify a comma-separated list of rule IDs (e.g. LIT.001,RES.002,etc.)
811
short form: -p; type: string
813
Password to use when connecting.
821
Create the given PID file when daemonized. The file contains the process
822
ID of the daemonized instance. The PID file is removed when the
823
daemonized instance exits. The program checks for the existence of the
824
PID file when starting; if it exists and the process with the matching PID
825
exists, the program exits.
831
short form: -P; type: int
833
Port number to use for connection.
839
type: string; default: wait_timeout=10000
841
Set these MySQL variables. Immediately after connecting to MySQL, this string
842
will be appended to SET and executed.
848
short form: -S; type: string
850
Socket file to use for connection.
854
--source-of-variables
856
type: string; default: mysql
858
Read \ ``SHOW VARIABLES``\ from this source. Possible values are "mysql", "none"
859
or a file name. If "mysql" is specified then you must also specify a DSN
866
short form: -u; type: string
868
User for login if not current user.
874
short form: -v; cumulative: yes; default: 1
876
Increase verbosity of output. At the default level of verbosity, the
877
program prints only the first sentence of each rule's description. At
878
higher levels, the program prints more of the description.
884
Show version and exit.
894
These DSN options are used to create a DSN. Each option is given like
895
\ ``option=value``\ . The options are case-sensitive, so P and p are not the
896
same option. There cannot be whitespace before or after the \ ``=``\ and
897
if the value contains whitespace it must be quoted. DSN options are
898
comma-separated. See the percona-toolkit manpage for full details.
903
dsn: charset; copy: yes
905
Default character set.
911
dsn: database; copy: yes
919
dsn: mysql_read_default_file; copy: yes
921
Only read default options from the given file
935
dsn: password; copy: yes
937
Password to use when connecting.
945
Port number to use for connection.
951
dsn: mysql_socket; copy: yes
953
Socket file to use for connection.
961
User for login if not current user.
971
Visit `http://www.percona.com/software/ <http://www.percona.com/software/>`_ to download the latest release of
972
Percona Toolkit. Or, to get the latest release from the command line:
977
wget percona.com/latest/percona-toolkit/PKG
980
Replace \ ``PKG``\ with \ ``tar``\ , \ ``rpm``\ , or \ ``deb``\ to download the package in that
981
format. You can also get individual tools from the latest release:
986
wget percona.com/latest/percona-toolkit/TOOL
989
Replace \ ``TOOL``\ with the name of any tool.
997
The environment variable \ ``PTDEBUG``\ enables verbose debugging output to STDERR.
998
To enable debugging and capture all output to a file, run the tool like:
1001
.. code-block:: perl
1003
PTDEBUG=1 pt-variable-advisor ... > FILE 2>&1
1006
Be careful: debugging output is voluminous and can generate several megabytes
1015
You need Perl, DBI, DBD::mysql, and some core packages that ought to be
1016
installed in any reasonably new version of Perl.
1024
For a list of known bugs, see `http://www.percona.com/bugs/pt-variable-advisor <http://www.percona.com/bugs/pt-variable-advisor>`_.
1026
Please report bugs at `https://bugs.launchpad.net/percona-toolkit <https://bugs.launchpad.net/percona-toolkit>`_.
1027
Include the following information in your bug report:
1030
\* Complete command-line used to run the tool
1038
\* MySQL version of all servers involved
1042
\* Output from the tool including STDERR
1046
\* Input files (log/dump/config files, etc.)
1050
If possible, include debugging output by running the tool with \ ``PTDEBUG``\ ;
1059
Baron Schwartz and Daniel Nichter
1062
*********************
1063
ABOUT PERCONA TOOLKIT
1064
*********************
1067
This tool is part of Percona Toolkit, a collection of advanced command-line
1068
tools developed by Percona for MySQL support and consulting. Percona Toolkit
1069
was forked from two projects in June, 2011: Maatkit and Aspersa. Those
1070
projects were created by Baron Schwartz and developed primarily by him and
1071
Daniel Nichter, both of whom are employed by Percona. Visit
1072
`http://www.percona.com/software/ <http://www.percona.com/software/>`_ for more software developed by Percona.
1075
********************************
1076
COPYRIGHT, LICENSE, AND WARRANTY
1077
********************************
1080
This program is copyright 2010-2011 Percona Inc.
1081
Feedback and improvements are welcome.
1083
THIS PROGRAM IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
1084
WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
1085
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
1087
This program is free software; you can redistribute it and/or modify it under
1088
the terms of the GNU General Public License as published by the Free Software
1089
Foundation, version 2; OR the Perl Artistic License. On UNIX and similar
1090
systems, you can issue \`man perlgpl' or \`man perlartistic' to read these
1093
You should have received a copy of the GNU General Public License along with
1094
this program; if not, write to the Free Software Foundation, Inc., 59 Temple
1095
Place, Suite 330, Boston, MA 02111-1307 USA.
1103
Percona Toolkit v1.0.0 released 2011-08-01
added
removed
docs/user/pt-variable-advisor.rst
