VBTK::Wrapper - Command line encapsulation and monitoring.
$t = new VBTK::Wrapper ( Interval => 60, Execute => 'ping myhost', Split => undef, Filter => 'bytes from.*time=(\d+)', Ignore => 'PING|^\s*$|^round-trip', SkipLines => 1, VBServerURI => 'http://myvbserver:4712', VBHeader => undef, VBDetail => [ '$time $data' ], LogFile => '/var/log/ping.myhost.log' LogHeader => undef, LogDetail => [ '$time $data' ], RotateLogAt => '12:00am', RotateLogOnEOF => undef, Timeout => undef, TimeoutStatus => undef, Follow => 1, FollowTimeout => 150, FollowHeartbeat => undef, SetRunStatus => undef, NonZeroExitStatus => undef, DebugHeader => 'ping myhost', );
This perl library provides the ability to encapsulate the execution of a command-line program, capturing STDOUT, parsing and filtering it, and searching it for text patterns indicating success or failure. It then can set the status of a vbserver object based on the results.
There are many values to setup when declaring a Wrapper object. To simplify things, most of these values will default appropriately. In addition, several sub-classes are provided which have customized defaults for specific uses. The following sub-classes are provided:
Defaults for monitoring a list of hosts using 'ping'.
Defaults for monitoring disk space using the 'df' command.
Defaults for monitoring system performance using the 'vmstat'.
Defaults for monitoring system hardware status using the 'prtdiag' command. (This is a Sun-specific utility, I think).
Defaults for monitoring DiskSuite volume status. (Sun-specific)
Defaults for monitoring Veritas Volume Manager disk volume status using the 'vxprint' command.
Defaults for monitoring a log file.
Others are sure to follow. If you're interested in adding your own sub-class, just copy and modify some of the existing ones. Eventually, I'll get around to documenting this nicely.
The following methods are supported
The allowed parameters are:
The interval (in seconds) on which the command should be run. If no interval is specifed, then the command will only run once and then the process will exit.
Interval => 60,
A string to be executed on the command line.
Execute => 'ping myhost',
This can be used in place of the 'Execute' parm if the thing you want to monitor is a text file instead of the output of a command. An example of this would be a log file such as /var/adm/messages. If specified, this overrides any value in the 'Execute' paramter. It can be a string, or a pointer to an array.
SourceList => '/var/adm/messages',
A Perl pattern expression indicating how to split the current line being processed into columns which will be placed in the @data array. This is only necessary if you're planning to use the @data variables in your VBDetail parm or later in your rules. The value will be passed in a call to 'split'. If no 'Filter' is specified, then this will default to '\s+'.
Split => '\s+',
A Perl pattern expression which will be used to filter through the incoming data. Only lines matching the pattern will be used. If the pattern contains parenthesis (), then the resulting $1, $2, etc will be used to populate the @data array. However, if a 'Split' pattern is specified, it will always override the data placed in @data.
Filter => 'bytes from.*time=(\d+)',
A Perl pattern expresssion used to filter out incoming data. Lines matching the pattern will be ignored. The 'Ignore' parm will override the 'Filter' parm.
Ignore => '^\s*$',
A number indicating how many lines to skip at the start of the incoming data. For example, the first 3 lines of the 'vmstat' command output should be discarded. A negative value will skip to the end of the first batch of incoming data, so for example a value of '-3' would ignore all but the last 3 rows of the first batch of data. This is useful when tailing a log file where you only want to look at new data being added to the log file.
Skiplines => 3,
A pointer to a subroutine to which incoming data should be passed for pre-processing. The subroutine will be passed a pointer to the @data array as received by the Parser. It will initially be a 1-dimensional array which simply contains the output lines. The subroutine can add/remove rows from the array, alter data, or reformat the array into a 2-dimensional array. If the array is changed to a 2-dimensional array, then any 'Filter', 'Ignore', or 'Split' parms will be ignored, since the data will have already been split. This is a fairly advanced function, so don't use it unless you know what you're doing.
# This has the same effect as using Split => '\s+' PreProcessor = sub { my($data) = @_; @{$data} = map { [ split('\s+',$_) ] } @{$data}; }
A URI which specifies which VB Server to report results to. Defaults to the environment variable $VBURI.
VBServerURI => 'http://myvbserver:4712',
An array containing strings to be used as header lines when transmitting results to the VB Server process.
VBHeader => [ 'Date Response Time Delta Response Time', '---------------- -------------- -------------------' ],
An array containing strings to be used to format the detail lines which will be sent to the VB Server process. These strings can make use of the Perl picture format syntax.
VBDetail => [ '@<<<<<<<<<<<<<<< @>>>>>>>>>>>>> @>>>>>>>>>>>>>>>>>>', '$time $data[0] $delta[0]' ],
The following variables will be set just before these detail lines are evaluated:
The current datestamp in the form YYYYMMDD-HH:MM:SS
The full text of the line currently being parsed.
An array containing the split data. See the Split, Filter, and Pre-Processor Parms for details on how to split the data being parsed into columns.
An array containing the delta's calculated between the current @data and the previous @data. In multi-row output, the row number is used to match up multiple @data arrays with their previous @data values to calulate the deltas. These deltas are most useful when monitoring the change in counters. This is very common in SNMP monitors.
An array containing the same data as in the @delta array, but divided by the number of seconds since the last data retrieval.
A string containing the path to a file where a log file should be written.
LogFile => '/var/log/ping.myhost.log',
Same as VBHeader, but to be used in formatting the log file.
Same as VBDetail, but to be used in formatting the log file.
A string containing a date/time expression indicating when the log file should be rotated. When the log is rotated, the current log will have a timestamp appended to the end of it after which logging will continue to a new file with the original name. The expression will be passed to Date::Manip so it can be just about any recognizable date/time expression.
RotateLogAt => '12:00am',
A boolean (1 or 0) value indicating whether the log should be rotated each time the command finishes or reaches EOF. This is only really useful when using SourceList to tail a log file in 'Follow' mode.
A number indicating the max number of seconds which can elapse before the command being executed is killed and the status of any VBObjects set to the status specified in 'TimeoutStatus'.
Timeout => 120,
The status to which any associated VBObjects should be set if a timeout occurs. Keep in mind that if you leave this set to Timeout, you'll need to include status change actions for the 'Timeout' status when defining your VBObjects. (Defaults to 'Timeout')
TimeoutStatus => 'Warning',
A boolean (0 or 1) indicating whether the Wrapper engine should 'follow' the output of the command being executed, reporting incoming data as it arrives. This option is normally used when executing commands such as 'vmstat 60' which would output stats every 60 seconds, but never terminate. It's also used when tailing a log file with the 'SourceList' parm. (Defaults to 0).
Follow => 1,
A number indicating how many seconds may pass without any incoming data before the command is killed and the status is set to 'TimeoutStatus'. This is used to detect the hang-up or loss of connectivity to commands which are supposed to output data every n seconds. This value is only used if in 'Follow' mode. (Defaults to 'undef')
FollowTimeout => 150,
A boolean (0 or 1) indicating whether the Wrapper engine should force the transmission of a status to the VBServer if 'Interval' seconds have passed with no incoming data. This is usually used when tailing log files, where the stream of data is inconsistent, and although no new data has been appended to the logs, you want the VBServer to know that the monitoring process is still running. (Defaults to 0).
FollowHeartbeat => 1,
A boolean (0 or 1) indicating whether the status of the associated VBObjects should be set to 'Running' during the period that the command is being executed. This is really only used for monitoring long-running processes, such as a nightly backup. I don't use this very often. (Defaults to 0).
SetRunStatus => 1,
A string specifying the status to which any associated VBObjects should be set if the command being executed exits with a non-zero exit code. Setting this to 'Success' means that the non-zero exit code will be ignored, leaving the status to be determined by the VBObject rules and requirements. Note that the code which reads in these status strings only looks at the first character and is case-insensitive, so you could specify ('F','fail','Failure',etc.) and it would always interpret it as 'Failed'. (Defaults to 'Failed')
NonZeroExitStatus => 'Warning',
A string which will be printed to STDOUT as part of debug messages. Four debug levels are available (1-4) by setting the 'VERBOSE' environment variable. This is helpful when trying to debug with several Wrapper objects running under a single unix process.
DebugHeader => 'ping myhost',
The 'addVBObj' is used to define VBObjects which will appear on the VBServer to which status reports are transmitted. See the VBTK::ClientObject class for a list of valid parms and their descriptions.
Brent Henry, vbtoolkit@yahoo.com
Copyright (C) 1996-2002 Brent Henry
This program is free software; you can redistribute it and/or modify it under the terms of version 2 of the GNU General Public License as published by the Free Software Foundation available at: http://www.gnu.org/copyleft/gpl.html
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
To install VBTK, copy and paste the appropriate command in to your terminal.
cpanm
cpanm VBTK
CPAN shell
perl -MCPAN -e shell install VBTK
For more information on module installation, please visit the detailed CPAN module installation guide.