Copy and format for POD docu from Aspersa User's Manual to forked Aspersa tools.

bin/pt-stalk

@@ -51,7 +51,7 @@ MAYBE_EMPTY=${MAYBE_EMPTY:-no}
 
 # This is the location of the 'collect' script.
 if [ -z "${COLLECT}" ]; then
-   COLLECT="${HOME}/bin/collect";
+   COLLECT="${HOME}/bin/pt-collect";
 fi
 
 # This is where to store the collected data.
@@ -167,52 +167,155 @@ done
 
 =head1 NAME
 
-pt-stalk - Watch MySQL and run the 'collect' program when some condition becomes true.
+pt-stalk - Wait for a condition to occur then begin collecting data.
 
 =head1 SYNOPSIS
 
-Usage: pt-stalk [OPTION...]
+Usage: pt-stalk
+
+pt-stalk watches for a condition to become true, and when it does, executes
+a script.  By default it executes L<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.
 
 =head1 DESCRIPTION
 
-By default, it watches for a too-many-connections condition.
-This is a good script to run in a screen session.  It's separate from the
-'collect' script because that lets you change 'collect' without stopping
-and restarting this one.
+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:
+
+=over
+
+=item 1.
+
+Loop infinitely, sleeping between iterations.
+
+=item 2.
+
+In each iteration, run some command and get the output.
+
+=item 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.
+
+=back
+
+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.
 
-=head1 DOWNLOADING
+=head1 CONFIGURING
 
-Visit L<http://www.percona.com/software/percona-toolkit/> to download the
-latest release of Percona Toolkit.  Or, get the latest release from the
-command line:
+If the file F<pt-stalk.conf> exists in the current working directory, then
+L<"ENVIRONMENT"> variables are imported from it.  For example, the config
+file has the format:
 
-   wget percona.com/get/percona-toolkit.tar.gz
+   INTERVAL=10
+   GDB=yes
 
-   wget percona.com/get/percona-toolkit.rpm
+See L<"ENVIRONMENT">.
 
-   wget percona.com/get/percona-toolkit.deb
+=head1 OPTIONS
 
-You can also get individual tools from the latest release:
-
-   wget percona.com/get/TOOL
-
-Replace C<TOOL> with the name of any tool.
+This tool does not have any command-line options, but see
+L<"ENVIRONMENT"> and L<"CONFIGURING">.
 
 =head1 ENVIRONMENT
 
-The environment variable C<PTDEBUG> enables verbose debugging output to STDERR.
-To enable debugging and capture all output to a file, run the tool like:
+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 F<pt-stalk.conf> config file (see L<"CONFIGURING">).
 
-   PTDEBUG=1 pt-stalk ... > FILE 2>&1
+=over
 
-Be careful: debugging output is voluminous and can generate several megabytes
-of output.
+=item THRESHOLD (default 100)
+
+This is the max number of <whatever> we want to tolerate.
+
+=item VARIABLE (default Threads_connected}
+
+This is the thing to check for.
+
+=item CYCLES (default 1)
+
+How many times must the condition be met before the script will fire?
+
+=item GDB (default no)
+
+Collect GDB stacktraces?
+
+=item OPROFILE (default yes)
+
+Collect oprofile data?
+
+=item STRACE (default no)
+
+Collect strace data?
+
+=item TCPDUMP (default yes)
+
+Collect tcpdump data?
+
+=item EMAIL
+
+Send mail to this list of addresses when the script triggers.
+
+=item MYSQLOPTIONS
+
+Any options to pass to mysql/mysqladmin, such as -u, -p, etc
+
+=item INTERVAL (default 30)
+
+This is the interval between checks.
+
+=item 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".
+
+=item COLLECT (default ${HOME}/bin/pt-collect)
+
+This is the location of the 'collect' script.
+
+=item DEST (default ${HOME}/collected/)
+
+This is where to store the collected data.
+
+=item DURATION (default 30)
+
+How long to collect statistics data for?  Make sure that this isn't longer
+than SLEEP.
+
+=item SLEEP (default DURATION * 10)
+
+How long to sleep after collecting?
+
+=item PCT_THRESHOLD (default 95)
+
+Bail out if the disk is more than this %full.
+
+=item MB_THRESHOLD (default 100)
+
+Bail out if the disk has less than this many MB free.
+
+=item PURGE (default 30)
+
+Remove samples after this many days.
+
+=back
 
 =head1 SYSTEM REQUIREMENTS
 
-You need Bash.
+This tool requires Bash v3 or newer.
 
 =head1 BUGS
 
@@ -238,6 +341,24 @@ Include the following information in your bug report:
 If possible, include debugging output by running the tool with C<PTDEBUG>;
 see L<"ENVIRONMENT">.
 
+=head1 DOWNLOADING
+
+Visit L<http://www.percona.com/software/percona-toolkit/> to download the
+latest release of Percona Toolkit.  Or, get the latest release from the
+command line:
+
+   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:
+
+   wget percona.com/get/TOOL
+
+Replace C<TOOL> with the name of any tool.
+
 =head1 AUTHORS
 
 Baron Schwartz, Justin Swanhart, and Fernando Ipar