NAME¶

SYNOPSIS¶

RISKS¶

DESCRIPTION¶

  while true; do
    if --variable from --function is greater than --threshold; then
      observations++
      if observations is greater than --cycles; then
        capture diagnostics for --run-time seconds
        exit if --iterations is exceeded
        sleep for --sleep seconds
      done
    done
    clean up data that's older than --retention-time
    sleep for --interval seconds
  done

CONFIGURING¶

  daemonize
  threshold=20

OPTIONS¶

--collect

default: yes; negatable: yes

 

Collect system information. You can negate this option to make the tool watch the system but not actually gather any diagnostic data.

 

See also "--stalk".

--collect-gdb

Collect GDB stacktraces. This is achieved by attaching to MySQL and printing stack traces from all threads. This will freeze the server for some period of time, ranging from a second or so to much longer on very busy systems with a lot of memory and many threads in the server. For this reason, it is disabled by default. However, if you are trying to diagnose a server stall or lockup, freezing the server causes no additional harm, and the stack traces can be vital for diagnosis.

 

In addition to freezing the server, there is also some risk of the server crashing or performing badly after GDB detaches from it.

--collect-oprofile

Collect oprofile data. This is achieved by starting an oprofile session, letting it run for the collection time, and then stopping and saving the resulting profile data in the system's default location. Please read your system's oprofile documentation to learn more about this.

--collect-strace

Collect strace data. This is achieved by attaching strace to the server, which will make it run very slowly until strace detaches. The same cautions apply as those listed in --collect-gdb. You should not enable this option together with --collect-gdb, because GDB and strace can't attach to the server process simultaneously.

--collect-tcpdump

Collect tcpdump data. This option causes tcpdump to capture all traffic on all interfaces for the port on which MySQL is listening. You can later use pt-query-digest to decode the MySQL protocol and extract a log of query traffic from it.

--config

type: string

 

Read this comma-separated list of config files. If specified, this must be the first option on the command line.

--cycles

type: int; default: 5

 

The number of times the trigger condition must be true before collecting data. This helps prevent false positives, and makes the trigger condition less likely to fire when the problem recovers quickly.

--daemonize

Daemonize the tool. This causes the tool to fork into the background and log its output as specified in --log.

--dest

type: string; default: /var/lib/pt-stalk

 

Where to store the diagnostic data. Each time the tool collects data, it writes to a new set of files, which are named with the current system timestamp.

--disk-bytes-free

type: size; default: 100M

 

Don't collect data if the disk has less than this much free space. This prevents the tool from filling up the disk with diagnostic data.

 

If the "--dest" directory contains a previously captured sample of data, the tool will measure its size and use that as an estimate of how much data is likely to be gathered this time, too. It will then be even more pessimistic, and will refuse to collect data unless the disk has enough free space to hold the sample and still have the desired amount of free space. For example, if you'd like 100MB of free space and the previous diagnostic sample consumed 100MB, the tool won't collect any data unless the disk has 200MB free.

 

Valid size value suffixes are k, M, G, and T.

--disk-pct-free

type: int; default: 5

 

Don't collect data if the disk has less than this percent free space. This prevents the tool from filling up the disk with diagnostic data.

 

This option works similarly to "--disk-bytes-free" but specifies a percentage margin of safety instead of a bytes margin of safety. The tool honors both options, and will not collect any data unless both margins are satisfied.

--function

type: string; default: status

 

Specifies what to watch for a diagnostic trigger. The default value watches SHOW GLOBAL STATUS, but you can also watch SHOW PROCESSLIST or supply a plugin file with your own custom code. This function supplies the value of "--variable", which is then compared against "--threshold" to see if the trigger condition is met. Additional options may be required as well; see below. Possible values:

   trg_plugin() {
      mysql $EXT_ARGV -e "SHOW ENGINE INNODB STATUS" \
        | grep -c "has waited at"
   }

--help

Print help and exit.

--interval

type: int; default: 1

 

Interval between checks for the diagnostic trigger.

--iterations

type: int

 

Exit after collecting diagnostics this many times. By default, the tool will continue to watch the server forever, but this is useful for scenarios where you want to capture once and then exit, for example.

--log

type: string; default: /var/log/pt-stalk.log

 

Print all output to this file when daemonized.

--match

type: string

 

The pattern to use when watching SHOW PROCESSLIST. See the documentation for "--function" for details.

--notify-by-email

type: string

 

Send mail to this list of addresses when data is collected.

--pid

type: string; default: /var/run/pt-stalk.pid

 

Create a PID file when daemonized.

--prefix

type: string

 

The filename prefix for diagnostic samples. By default, samples have a timestamp prefix based on the current local time, such as 2011_12_06_14_02_02, which is December 6, 2011 at 14:02:02.

--retention-time

type: int; default: 30

 

Number of days to retain collected samples. Any samples that are older will be purged.

--run-time

type: int; default: 30

 

How long the tool will collect data when it triggers. This should not be longer than "--sleep". It is usually not necessary to change this; if the default 30 seconds hasn't gathered enough diagnostic data, running longer is not likely to do so. In fact, in many cases a shorter collection period is appropriate.

--sleep

type: int; default: 300

 

How long to sleep after collecting data. This prevents the tool from triggering continuously, which might be a problem if the collection process is intrusive. It also prevents filling up the disk or gathering too much data to analyze reasonably.

--stalk

default: yes; negatable: yes

 

Watch the server and wait for the trigger to occur. You can negate this option to make the tool immediately gather any diagnostic data once and exit. This is useful if a problem is already happening, but pt-stalk is not running, so you only want to collect diagnostic data.

 

If this option is negate, "--daemonize", "--log", "--pid", and other stalking-related options have no effect; the tool simply collects diagnostic data and exits. Safeguard options, like "--disk-bytes-free" and "--disk-pct-free", are still respected.

 

See also "--collect".

--threshold

type: int; default: 25

 

The threshold at which the diagnostic trigger should fire. See "--function" for details.

--variable

type: string; default: Threads_running

 

The variable to compare against the threshold. See "--function" for details.

--version

Print tool's version and exit.

ENVIRONMENT¶

SYSTEM REQUIREMENTS¶

BUGS¶

•

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

DOWNLOADING¶

   wget percona.com/get/percona-toolkit.tar.gz
   wget percona.com/get/percona-toolkit.rpm
   wget percona.com/get/percona-toolkit.deb

   wget percona.com/get/TOOL

AUTHORS¶

ABOUT PERCONA TOOLKIT¶

COPYRIGHT, LICENSE, AND WARRANTY¶

VERSION¶