From 4c474fd23fb918cbf4690f9a09beb1a99050e757 Mon Sep 17 00:00:00 2001 From: Daniel Nichter Date: Wed, 3 Oct 2012 11:28:19 -0600 Subject: [PATCH 1/3] Add --plugin and hooks to pt-stalk. --- bin/pt-stalk | 86 ++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 84 insertions(+), 2 deletions(-) diff --git a/bin/pt-stalk b/bin/pt-stalk index b4f301b8..d9a858a6 100755 --- a/bin/pt-stalk +++ b/bin/pt-stalk @@ -932,6 +932,30 @@ TOOL="pt-stalk" OKTORUN=1 ITER=1 +# ########################################################################### +# Plugin hooks +# ########################################################################### + +before_stalk_hook() { + : +} + +before_collect_hook() { + : +} + +after_collect_hook() { + : +} + +after_collect_sleep_hook() { + : +} + +after_stalk_hook() { + : +} + # ########################################################################### # Subroutines # ########################################################################### @@ -1136,6 +1160,9 @@ stalk() { log "pt-stalk ran with $RAN_WITH" >> "$OPT_DEST/$prefix-trigger" last_prefix="$prefix" + # Plugin hook: + before_collect_hook + # Fork and background the collect subroutine which will # run for --run-time seconds. We (the parent) sleep # while its collecting (hopefully --sleep is longer than @@ -1143,7 +1170,11 @@ stalk() { ( collect "$OPT_DEST" "$prefix" ) >> "$OPT_DEST/$prefix-output" 2>&1 & - log "Collector PID $!" + local collector_pid=$! + log "Collector PID $collector_pid" + + # Plugin hook: + after_collect_hook $collector_pid else # There will not be enough disk space, so do not collect. warn "Collect canceled because there will not be enough disk space after collecting another $margin MB" @@ -1156,6 +1187,9 @@ stalk() { ITER=$((ITER + 1)) cycles_true=0 sleep_ok "$OPT_SLEEP" "Sleeping $OPT_SLEEP seconds after collect" + + # Plugin hook: + after_collect_sleep_hook else # Trigger/check/value is ok, sleep until next check. sleep_ok "$OPT_INTERVAL" @@ -1178,7 +1212,7 @@ main() { # Note: $$ is the parent's PID, but we're a child proc. # Bash 4 has $BASHPID but we can't rely on that. Consequently, # we don't know our own PID. See the usage of $! below. - RAN_WITH="--function=$OPT_FUNCTION --variable=$OPT_VARIABLE --threshold=$OPT_THRESHOLD --match=$OPT_MATCH --cycles=$OPT_CYCLES --interval=$OPT_INTERVAL --iterations=$OPT_ITERATIONS --run-time=$OPT_RUN_TIME --sleep=$OPT_SLEEP --dest=$OPT_DEST --prefix=$OPT_PREFIX --notify-by-email=$OPT_NOTIFY_BY_EMAIL --log=$OPT_LOG --pid=$OPT_PID" + RAN_WITH="--function=$OPT_FUNCTION --variable=$OPT_VARIABLE --threshold=$OPT_THRESHOLD --match=$OPT_MATCH --cycles=$OPT_CYCLES --interval=$OPT_INTERVAL --iterations=$OPT_ITERATIONS --run-time=$OPT_RUN_TIME --sleep=$OPT_SLEEP --dest=$OPT_DEST --prefix=$OPT_PREFIX --notify-by-email=$OPT_NOTIFY_BY_EMAIL --log=$OPT_LOG --pid=$OPT_PID --plugin=$OPT_PLUGIN" log "Starting $0 $RAN_WITH" @@ -1190,9 +1224,15 @@ main() { # Make a secure tmpdir. mk_tmpdir + # Plugin hook: + before_stalk_hook + # Stalk while oktorun. stalk + # Plugin hook: + after_stalk_hook + # Clean up. rm_tmpdir remove_pid_file "$OPT_PID" @@ -1217,6 +1257,15 @@ if [ "${0##*/}" = "$TOOL" ] \ option_error "Invalid --function value: $OPT_FUNCTION" fi + # Verify and source the --plugin. + if [ "$OPT_PLUGIN" ]; then + if [ -f "$OPT_PLUGIN" ]; then + . "$OPT_PLUGIN" + else + option_error "Invalid --plugin value: $OPT_PLUGIN is not a file" + fi + fi + if [ -z "$OPT_STALK" -a "$OPT_COLLECT" ]; then # Not stalking; do immediate collect once. OPT_ITERATIONS=1 @@ -1611,6 +1660,39 @@ type: string; default: /var/run/pt-stalk.pid Create a PID file when daemonized. +=item --plugin + +type: string + +Load a plugin script to hook into the tool and extend is functionality. + +=over + +=item before_stalk_hook + +Called before stalking. + +=item before_collect_hook + +Called when the stalk condition is triggered, before running a collector +process as a backgrounded subshell. + +=item after_collect_hook + +Called after running a collector process. The PID of the collector process +is passed as the first argument. + +=item after_collect_sleep_hook + +Called after sleeping L<"--sleep"> seconds for the collector process to finish. + +=item after_stalk_hook + +Called after stalking. Since pt-stalk stalks forever by default, +this hook is only called if L<"--iterations"> is specified. + +=back + =item --prefix type: string From c0bafdead9f455c567748e3102266bf0a1b0d0f9 Mon Sep 17 00:00:00 2001 From: Daniel Nichter Date: Wed, 3 Oct 2012 11:51:03 -0600 Subject: [PATCH 2/3] Test --plugin. --- bin/pt-stalk | 4 +- t/pt-stalk/plugin.t | 74 +++++++++++++++++++++++++++++++++ t/pt-stalk/samples/plugin001.sh | 21 ++++++++++ 3 files changed, 98 insertions(+), 1 deletion(-) create mode 100644 t/pt-stalk/plugin.t create mode 100644 t/pt-stalk/samples/plugin001.sh diff --git a/bin/pt-stalk b/bin/pt-stalk index d9a858a6..63e2c8f7 100755 --- a/bin/pt-stalk +++ b/bin/pt-stalk @@ -1680,11 +1680,13 @@ process as a backgrounded subshell. =item after_collect_hook Called after running a collector process. The PID of the collector process -is passed as the first argument. +is passed as the first argument. This hook is called before +C. =item after_collect_sleep_hook Called after sleeping L<"--sleep"> seconds for the collector process to finish. +This hook is called after C. =item after_stalk_hook diff --git a/t/pt-stalk/plugin.t b/t/pt-stalk/plugin.t new file mode 100644 index 00000000..964b88f4 --- /dev/null +++ b/t/pt-stalk/plugin.t @@ -0,0 +1,74 @@ +#!/usr/bin/env perl + +BEGIN { + die "The PERCONA_TOOLKIT_BRANCH environment variable is not set.\n" + unless $ENV{PERCONA_TOOLKIT_BRANCH} && -d $ENV{PERCONA_TOOLKIT_BRANCH}; + unshift @INC, "$ENV{PERCONA_TOOLKIT_BRANCH}/lib"; +}; + +use strict; +use warnings FATAL => 'all'; +use English qw(-no_match_vars); +use Test::More; +use Time::HiRes qw(sleep); + +use PerconaTest; +use DSNParser; +use Sandbox; + +my $dp = new DSNParser(opts=>$dsn_opts); +my $sb = new Sandbox(basedir => '/tmp', DSNParser => $dp); +my $dbh = $sb->get_dbh_for('master'); + +if ( !$dbh ) { + plan skip_all => 'Cannot connect to sandbox master'; +} + +my $cnf = "/tmp/12345/my.sandbox.cnf"; +my $pid_file = "/tmp/pt-stalk.pid.$PID"; +my $log_file = "/tmp/pt-stalk.log.$PID"; +my $dest = "/tmp/pt-stalk.collect.$PID"; +my $output; +my $retval; +my $pid; + +diag(`rm $pid_file 2>/dev/null`); +diag(`rm $log_file 2>/dev/null`); +diag(`mkdir $dest`); + +# We'll have to watch Uptime since it's the only status var that's going +# to be predictable. +my (undef, $uptime) = $dbh->selectrow_array("SHOW STATUS LIKE 'Uptime'"); +my $threshold = $uptime + 2; + +$retval = system("$trunk/bin/pt-stalk --iterations 1 --dest $dest --variable Uptime --threshold $threshold --cycles 1 --run-time 2 --pid $pid_file --plugin $trunk/t/pt-stalk/samples/plugin001.sh -- --defaults-file=$cnf >$log_file 2>&1"); + +PerconaTest::wait_until(sub { !-f $pid_file }); + +is( + $retval >> 8, + 0, + "Exit 0" +); + +foreach my $hook (qw( + before_stalk_hook + before_collect_hook + after_collect_hook + after_collect_sleep_hook + after_stalk_hook +)) { + ok( + -f "$dest/$hook", + "$hook called" + ); +} + +# ############################################################################# +# Done. +# ############################################################################# +diag(`rm $pid_file 2>/dev/null`); +diag(`rm $log_file 2>/dev/null`); +diag(`rm -rf $dest 2>/dev/null`); +ok($sb->ok(), "Sandbox servers") or BAIL_OUT(__FILE__ . " broke the sandbox"); +done_testing; diff --git a/t/pt-stalk/samples/plugin001.sh b/t/pt-stalk/samples/plugin001.sh new file mode 100644 index 00000000..65063548 --- /dev/null +++ b/t/pt-stalk/samples/plugin001.sh @@ -0,0 +1,21 @@ +#!/bin/sh + +before_stalk_hook() { + date >> "$OPT_DEST/before_stalk_hook" +} + +before_collect_hook() { + date >> "$OPT_DEST/before_collect_hook" +} + +after_collect_hook() { + date >> "$OPT_DEST/after_collect_hook" +} + +after_collect_sleep_hook() { + date >> "$OPT_DEST/after_collect_sleep_hook" +} + +after_stalk_hook() { + date >> "$OPT_DEST/after_stalk_hook" +} From 7ac44ba53ae049e65810da86821102b785bfced2 Mon Sep 17 00:00:00 2001 From: Daniel Nichter Date: Wed, 3 Oct 2012 12:31:36 -0600 Subject: [PATCH 3/3] Document --plugin. Remove _hook suffix. --- bin/pt-stalk | 65 +++++++++++++++++++++++---------- t/pt-stalk/plugin.t | 12 +++--- t/pt-stalk/samples/plugin001.sh | 20 +++++----- 3 files changed, 61 insertions(+), 36 deletions(-) diff --git a/bin/pt-stalk b/bin/pt-stalk index 63e2c8f7..5eb2d524 100755 --- a/bin/pt-stalk +++ b/bin/pt-stalk @@ -936,23 +936,23 @@ ITER=1 # Plugin hooks # ########################################################################### -before_stalk_hook() { +before_stalk() { : } -before_collect_hook() { +before_collect() { : } -after_collect_hook() { +after_collect() { : } -after_collect_sleep_hook() { +after_collect_sleep() { : } -after_stalk_hook() { +after_stalk() { : } @@ -1040,12 +1040,12 @@ trg_processlist() { oktorun() { if [ $OKTORUN -eq 0 ]; then - EXIT_REASON="OKTORUN is false" + [ -z "$EXIT_REASON" ] && EXIT_REASON="OKTORUN is false" return 1 # stop running fi if [ -n "$OPT_ITERATIONS" ] && [ $ITER -gt $OPT_ITERATIONS ]; then - EXIT_REASON="no more iterations" + [ -z "$EXIT_REASON" ] && EXIT_REASON="no more iterations" return 1 # stop running fi @@ -1161,7 +1161,7 @@ stalk() { last_prefix="$prefix" # Plugin hook: - before_collect_hook + before_collect # Fork and background the collect subroutine which will # run for --run-time seconds. We (the parent) sleep @@ -1174,7 +1174,7 @@ stalk() { log "Collector PID $collector_pid" # Plugin hook: - after_collect_hook $collector_pid + after_collect $collector_pid else # There will not be enough disk space, so do not collect. warn "Collect canceled because there will not be enough disk space after collecting another $margin MB" @@ -1189,7 +1189,7 @@ stalk() { sleep_ok "$OPT_SLEEP" "Sleeping $OPT_SLEEP seconds after collect" # Plugin hook: - after_collect_sleep_hook + after_collect_sleep else # Trigger/check/value is ok, sleep until next check. sleep_ok "$OPT_INTERVAL" @@ -1225,13 +1225,13 @@ main() { mk_tmpdir # Plugin hook: - before_stalk_hook + before_stalk # Stalk while oktorun. stalk # Plugin hook: - after_stalk_hook + after_stalk # Clean up. rm_tmpdir @@ -1664,37 +1664,62 @@ Create a PID file when daemonized. type: string -Load a plugin script to hook into the tool and extend is functionality. +Load a plugin to hook into the tool and extend is functionality. +The specified file does not need to be executable, nor does its first line +need to be shebang line. It only needs to define one or more of these +Bash functions: =over -=item before_stalk_hook +=item before_stalk Called before stalking. -=item before_collect_hook +=item before_collect Called when the stalk condition is triggered, before running a collector process as a backgrounded subshell. -=item after_collect_hook +=item after_collect Called after running a collector process. The PID of the collector process is passed as the first argument. This hook is called before -C. +C. -=item after_collect_sleep_hook +=item after_collect_sleep Called after sleeping L<"--sleep"> seconds for the collector process to finish. -This hook is called after C. +This hook is called after C. -=item after_stalk_hook +=item after_stalk Called after stalking. Since pt-stalk stalks forever by default, this hook is only called if L<"--iterations"> is specified. =back +For example, a very simple plugin that touches a file when a collector +process is triggered: + + before_colllect() { + touch /tmp/foo + } + +Since the plugin is completely sourced (imported) into the tool's namespace, +be careful not to define other functions or global variables that already +exist in the tool. You should prefix all plugin-specific functions and +global variables with C or C. + +Plugins have access to all command line options but they should not modify +them. Each option is a global variable like C<$OPT_DEST> which corresponds +to L<"--dest">. Therefore, the global variable for each command line option +is C plus the option name in all caps with hyphens replaced by +underscores. + +Plugins can stop the tool by setting the global variable C +to C<1>. In this case, the global variable C should also +be set to indicate why the tool was stopped. + =item --prefix type: string diff --git a/t/pt-stalk/plugin.t b/t/pt-stalk/plugin.t index 964b88f4..53f019e8 100644 --- a/t/pt-stalk/plugin.t +++ b/t/pt-stalk/plugin.t @@ -52,15 +52,15 @@ is( ); foreach my $hook (qw( - before_stalk_hook - before_collect_hook - after_collect_hook - after_collect_sleep_hook - after_stalk_hook + before_stalk + before_collect + after_collect + after_collect_sleep + after_stalk )) { ok( -f "$dest/$hook", - "$hook called" + "$hook hook called" ); } diff --git a/t/pt-stalk/samples/plugin001.sh b/t/pt-stalk/samples/plugin001.sh index 65063548..e2e3e6eb 100644 --- a/t/pt-stalk/samples/plugin001.sh +++ b/t/pt-stalk/samples/plugin001.sh @@ -1,21 +1,21 @@ #!/bin/sh -before_stalk_hook() { - date >> "$OPT_DEST/before_stalk_hook" +before_stalk() { + date >> "$OPT_DEST/before_stalk" } -before_collect_hook() { - date >> "$OPT_DEST/before_collect_hook" +before_collect() { + date >> "$OPT_DEST/before_collect" } -after_collect_hook() { - date >> "$OPT_DEST/after_collect_hook" +after_collect() { + date >> "$OPT_DEST/after_collect" } -after_collect_sleep_hook() { - date >> "$OPT_DEST/after_collect_sleep_hook" +after_collect_sleep() { + date >> "$OPT_DEST/after_collect_sleep" } -after_stalk_hook() { - date >> "$OPT_DEST/after_stalk_hook" +after_stalk() { + date >> "$OPT_DEST/after_stalk" }