VBTK::Tcp - Tcp Listener Monitoring
$o = new VBTK::Pop3 ( Host => 'pop3.nowhere.com', User => 'myuser', Password => 'mypass' ); $o->addVBObj ( VBObjName => '.external.pop3.nowhere', ); &VBTK::runAll;
This perl library provides the ability to do simple monitoring of a POP3 server. It uses the Mail::POP3Client library (available from CPAN) to connect to a POP server, check the connection status, and disconnect. It measures the elapsed time for this and stores it. It can also retrieve messages from the mailbox and determine the latency of the message delivery from the message headers. If the connection attempt fails of takes longer than 'Timeout' seconds, then the status of the corresponding VBObjects will be set to the 'ErrorStatus' value.
Note that the 'new VBTK::Pop3' and '$o->addVBObj' lines just initialize and register the objects. It's the &VBTK::runAll which starts the monitoring.
The following methods are available to the common user:
The allowed parameters are as follows.
The interval (in seconds) on which the POP3 retrieval should be attempted. (Defaults to 300)
Interval => 300,
A string containing the pop3 host to connect to. (Required)
Host => 'myhost',
A number indicating the port to connect to. (Defaults to 110)
Port => 110,
A string containing the username to use when connecting. (Required)
User => 'me',
A string containing the password to use when connecting. (Required)
Password => 'mypass',
A string containing a perl pattern-matching expression. If this is set, the library will retrieve and delete messages in the pop3 account which have a subject line matching this expression. It will also attempt to calculate the delivery latency of the retrieved messages.
Note that if this string is specified, the monitoring process will not send a status to the VB Server until a message matching the filter arrives. It will continue to connect to the POP3 server on the specified interval, but will not transmit a status until a message arrives. So if the process which is sending the messages dies, or some other problem prevents mail from being delivered, then the VB Object for this process will probably expire. This is a good thing, if what you're trying to monitor is the full cycle of sending an email, having it be delivered, and then retrieving it from the POP3 account.
This library is commonly used along with a VBTK::Smtp process. The VBTK::Smtp process sends mail every $Interval seconds, and the VBTK::Pop3 process gathers it every $Interval seconds. If anything breaks in between then the VBObject associated with this VBTK::Pop3 process will either get set to 'Failed' or 'Expired', and either way you can be notified.
An array containing strings to be used as header lines when transmitting results to the VB Server process. (Defaults to the following)
VBHeader => [ 'Time Retrieval (sec) Round-trip (sec) Error', '----------------- --------------- ---------------- -----' ]
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. Be sure to either use single-quotes or escape out the '$' vars so that they don't get evaluated until later. (Defaults to the following)
VBDetail => [ '@<<<<<<<<<<<<<<<< @>>>>>>>>>>>>>> @>>>>>>>>>>>>>>> @>>>>', '$time, $data[0], $data[1], $data[2]' ];
The following variables will be set just before these detail lines are evaluated:
A datestamp of the form YYYYMMDD-HH:MM:SS
An array, which contains the retrieval time in seconds, the round-trip time in seconds, and an error count. The round-trip time will always be 0 unless the 'RetrieveFilter' parm is set.
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.
A URI which specifies which VB Server to report results to. Defaults to the environment variable $VBURI.
VBServerURI => 'http://vbserver:4712',
A string containing the path to a file where a log file should be written. Leave blank if no log file is desired. (Defaults to undef).
LogFile => '/var/log/pop3.nowhere.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. (Defaults to 12:00am)
RotateLogAt => '12:00am',
A string containing a status to which any VBObjects should be set if there is an error while attempting to connect to the POP3 server. (Defaults to Warning).
ErrorStatus => 'Warning',
The 'addVBObj' is used to define VBObjects which will appear on the VBServer to which status reports are transmitted. This method calls VBTK::Parser::addVBObj after defaulting unspecified parameters to best support monitoring a POP3 server. For a detailed description of the addVBObj parameters, see VBTK::Parser. The defaults are as follows. If you like all the defaults then you don't have to pass in any parms, except for the 'VBObjName' parm which is required.
This is a required parm.
VBObjName => ".myhost.pop3",
TextHistoryLimit => 30,
Reverse the text, so that we see the most recently reported lines first.
ReverseText => 1,
Limit to storing the last 30 status changes
StatusHistoryLimit => 30,
StatusUpgradeRules => 'Upgrade to Failed if Warning occurs 3 times in <Interval * 4> seconds',
ExpireAfter => (<Interval> * 4) seconds
Description = qq( This object monitors the SMTP server <Host:Port>. If will set the status to warning if it is unable to connect to the POP3 server or if response times become unacceptable. );
Save the response time, round-trip time, and error count into the Rrd database so that we can graph them.
RrdColumns => [ '$data[0]', '$data[1]', '$data[3]' ],
In addition to passing these defaults on in a call to VBTK::Parser::addVBObj, this method captures the resulting VBTK::ClientObject pointer ($vbObj) and makes the following calls to '$vbObj->addGraphGroup':
$vbObj->addGraphGroup ( GroupNumber => 1, DataSourceList => ':0,:1', Labels => 'retrieval time (sec),round-trip time (sec)', Title => 'POP3 Svr <Host:Port>', ); $vbObj->addGraphGroup ( GroupNumber => 2, DataSourceList => ':2', Labels => 'errors', Title => 'POP3 Svr <Host:Port>', );
This defines two graphGroups for the VBObject. See VBTK::ClientObject for details on the 'addGraphGroup' method.
The following private methods are used internally. Do not try to use them unless you know what you are doing.
To be documented...
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.