Merge lp:~daniel-nichter/percona-toolkit/bash-tool-libs.

t/lib/samples/bash/collect001.txt

@@ -0,0 +1,33 @@
+2011_12_05-df
+2011_12_05-disk-space
+2011_12_05-diskstats
+2011_12_05-hostname
+2011_12_05-innodbstatus1
+2011_12_05-innodbstatus2
+2011_12_05-interrupts
+2011_12_05-iostat
+2011_12_05-iostat-overall
+2011_12_05-log_error
+2011_12_05-lsof
+2011_12_05-meminfo
+2011_12_05-mpstat
+2011_12_05-mpstat-overall
+2011_12_05-mutex-status1
+2011_12_05-mutex-status2
+2011_12_05-mysqladmin
+2011_12_05-netstat
+2011_12_05-netstat_s
+2011_12_05-opentables1
+2011_12_05-opentables2
+2011_12_05-output
+2011_12_05-processlist
+2011_12_05-procstat
+2011_12_05-procvmstat
+2011_12_05-ps
+2011_12_05-slabinfo
+2011_12_05-stacktrace
+2011_12_05-sysctl
+2011_12_05-top
+2011_12_05-variables
+2011_12_05-vmstat
+2011_12_05-vmstat-overall

t/lib/samples/bash/diskspace001.txt

@@ -0,0 +1,2 @@
+Filesystem   1024-blocks     Used Available Capacity  Mounted on
+/dev/disk0s2   118153176 94409664  23487512    81%    /

t/lib/samples/bash/dummy.sh

@@ -0,0 +1,4 @@
+#!/bin/sh
+
+# This is a dummy script for testing the Bash libs.  t/lib/bashLibs.t
+# calls "util/test-bash-functions dummy.sh <lib-test-files.sh>".

t/lib/samples/bash/help001.txt

@@ -0,0 +1,30 @@
+Usage: pt-stalk [OPTIONS] [-- MYSQL_OPTIONS]
+
+For more information, 'man pt-stalk' or 'perldoc /Users/daniel/p/bash-tool-libs/t/lib/samples/bash/po001.sh'.
+
+Command line options:
+
+--help
+  Print help and exit.
+
+--int-opt
+  Int option without a default.
+
+--int-opt2
+  Int option with a default.
+
+--noption
+  Negatable option.
+
+--string-opt
+  String option without a default.
+
+--string-opt2
+  String option with a default.
+
+--typeless-option
+  Just an option.
+
+--version
+  Print tool's version and exit.
+

t/lib/samples/bash/po001.sh

@@ -0,0 +1,308 @@
+#!/usr/bin/env bash
+
+# This is a fake script for testing the parse_options.sh lib.
+exit 0;
+
+# ############################################################################
+# Documentation
+# ############################################################################
+:<<'DOCUMENTATION'
+=pod
+
+=head1 NAME
+
+pt-stalk - Wait for a condition to occur then begin collecting data.
+
+=head1 SYNOPSIS
+
+Usage: pt-stalk [OPTIONS] [-- MYSQL_OPTIONS]
+
+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 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:
+L<http://www.percona.com/bugs/pt-stalk>.
+
+See also L<"BUGS"> for more information on filing bugs and getting help.
+
+=head1 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:
+
+=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 CONFIGURING
+
+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:
+
+   INTERVAL=10
+   GDB=yes
+
+See L<"ENVIRONMENT">.
+
+=head1 OPTIONS
+
+=over
+
+=item --string-opt
+
+type: string
+
+String option without a default.
+
+=item --string-opt2
+
+type: string; default: foo
+
+String option with a default.
+
+=item --typeless-option
+
+Just an option.
+
+=item --noption
+
+default: yes; negatable: yes
+
+Negatable option.
+
+=item --int-opt
+
+type: int
+
+Int option without a default.
+
+=item --int-opt2
+
+type: int; default: 42
+
+Int option with a default.
+
+=item --version
+
+short form: -v
+
+Print tool's version and exit.
+
+=item --help
+
+Print help and exit.
+
+=back
+
+=head1 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 F<pt-stalk.conf> config file (see L<"CONFIGURING">).
+
+=over
+
+=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
+
+This tool requires Bash v3 or newer.
+
+=head1 BUGS
+
+For a list of known bugs, see L<http://www.percona.com/bugs/pt-stalk>.
+
+Please report bugs at L<https://bugs.launchpad.net/percona-toolkit>.
+Include the following information in your bug report:
+
+=over
+
+=item * Complete command-line used to run the tool
+
+=item * Tool L<"--version">
+
+=item * MySQL version of all servers involved
+
+=item * Output from the tool including STDERR
+
+=item * Input files (log/dump/config files, etc.)
+
+=back
+
+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
+
+=head1 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
+L<http://www.percona.com/software/> for more software developed by Percona.
+
+=head1 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.
+
+=head1 VERSION
+
+pt-stalk 1.0.1
+
+=cut
+
+DOCUMENTATION

t/lib/samples/bash/po002.sh

@@ -0,0 +1,212 @@
+#!/usr/bin/env bash
+
+:
+
+# ############################################################################
+# Documentation
+# ############################################################################
+:<<'DOCUMENTATION'
+=pod
+
+=head1 NAME
+
+pt-stalk - Wait for a condition to occur then begin collecting data.
+
+=head1 OPTIONS
+
+=over
+
+=item --collect
+
+default: yes; negatable: yes
+
+Collect system information.
+
+=item --collect-gdb
+
+Collect GDB stacktraces.
+
+=item --collect-oprofile
+
+Collect oprofile data.
+
+=item --collect-strace
+
+Collect strace data.
+
+=item --collect-tcpdump
+
+Collect tcpdump data.
+
+=item --cycles
+
+type: int; default: 5
+
+Number of times condition must be met before triggering collection.
+
+=item --daemonize
+
+default: yes; negatable: yes
+
+Daemonize the tool.
+
+=item --dest
+
+type: string
+
+Where to store collected data.
+
+=item --disk-byte-limit
+
+type: int; default: 100
+
+Exit if the disk has less than this many MB free.
+
+=item --disk-pct-limit
+
+type: int; default: 5
+
+Exit if the disk is less than this %full.
+
+=item --execute-command
+
+type: string; default: pt-collect
+
+Location of the C<pt-collect> tool.
+
+=item --function
+
+type: string; default: status
+
+Built-in function name or plugin file name which returns the value of C<VARIABLE>.
+
+Possible values are:
+
+=over
+
+=item * status
+
+Grep the value of C<VARIABLE> from C<mysqladmin extended-status>.
+
+=item * processlist
+
+Count the number of processes in C<mysqladmin processlist> whose
+C<VARIABLE> column matches C<MATCH>.  For example:
+
+   TRIGGER_FUNCTION="processlist" \
+   VARIABLE="State"               \
+   MATCH="statistics"             \
+   THRESHOLD="10"
+
+The above triggers when more than 10 processes are in the "statistics" state.
+C<MATCH> must be specified for this trigger function.
+
+=item * magic
+
+TODO
+
+=item * plugin file name
+
+A plugin file allows you to specify a custom trigger function.  The plugin
+file must contain a function called C<trg_plugin>.  For example:
+
+   trg_plugin() {
+      # Do some stuff.
+      echo "$value"
+   }
+
+The last output if the function (its "return value") must be a number.
+This number is compared to C<THRESHOLD>.  All L<"ENVIRONMENT"> variables
+are available to the function.
+
+Do not alter the tool's existing global variables.  Prefix any plugin-specific
+global variables with "PLUGIN_".
+
+=back
+
+=item --help
+
+Print help and exit.
+
+=item --interval
+
+type: int; default: 1
+
+Interval between checks.
+
+=item --iterations
+
+type: int
+
+Exit after triggering C<pt-collect> this many times.  By default, the tool
+will collect as many times as it's triggered.
+
+=item --log
+
+type: string; default: /var/log/pt-stalk.log
+
+Print all output to this file when daemonized.
+
+=item --match
+
+type: string
+
+Match pattern for C<processles> L<"--function">.
+
+=item --notify-by-email
+
+type: string
+
+Send mail to this list of addresses when C<pt-collect> triggers.
+
+=item --pid FILE
+
+type: string; default: /var/run/pt-stalk.pid
+
+Create a PID file when daemonized.
+
+=item --retention-time
+
+type: int; default: 30
+
+Remove samples after this many days.
+
+=item --run-time
+
+type: int; default: 30
+
+How long to collect statistics data for?
+
+Make sure that this isn't longer than SLEEP.
+
+=item --sleep
+
+type: int; default: 300
+
+How long to sleep after collecting?
+
+=item --threshold N
+
+type: int; default: 25
+
+Max number of C<N> to tolerate.
+
+=item --variable NAME
+
+type: string; default: Threads_running
+
+This is the thing to check for.
+
+=item --version
+
+Print tool's version and exit.
+
+=back
+
+=head1 ENVIRONMENT
+
+No env vars used.
+
+=cut
+
+DOCUMENTATION