NAME

VBTK::Http - Web server monitoring

SYNOPSIS

  $t = new VBTK::Http ( 
    URL => 'http://www.testhost.com');

  $t->addVBObj (
    VBObjName         => '.external.http.testhost.resp',
    BaselineVBObjName => '.external.http.testhost.baseline' );

  &VBTK::runAll;

DESCRIPTION

This perl library provides the ability to do simple monitoring of a web page. This data-gatherer class is a little different in that it is setup to make use of two separate VBObjects by default.

The primary VBObject records response time and success of retrieval. A second BaselineVBObjName can be specified which gathers the actual HTML from the URL and compares it to a previously stored baseline. This allows the detection of undesired content changes or error pages.

Note that the 'new VBTK::Http' and '$t->addVBObj' lines just initialize and register the objects. It's the &VBTK::runAll which starts the monitoring.

PUBLIC METHODS

The following methods are available to the common user:

$s = new VBTK::Http (<parm1> => <val1>, <parm2> => <val2>, ...)

The allowed parameters are as follows. Note that some of these parms affect the response time VBObject, while others affect the BaselineVBObject.

Interval

The interval (in seconds) on which a connection attempt should be made to the specified URL. (Defaults to 60)

    Interval => 60,
URL

A string containing a URL to connect to. (Required)

    URL => 'http://www.testhost.com',
CheckImages

A boolean (0 or 1) which determines if images in the retrieved page should also be retrieved and their checksum calculated. (Not Yet Implemented)

    CheckImages => 0,
Filter

A Perl pattern expression which will be used to filter through the retrieved HTML. Only lines matching the pattern will be included in the baseline object. You must specify a 'BaselineVBObjName' in order for this to have any affect.

    Filter => '<img',
Ignore

A Perl pattern expresssion used to filter out lines of HTML. Lines matching the pattern will be ignored. The 'Ignore' parm will override the 'Filter' parm. This only affects the object specified in 'BaselineVBObjName'.

    Ignore => '^\s*$',
PreProcessor

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 which will contain lines of HTML as retrieved from the specified URL. The PreProcessor subroutine can then alter the data as necessary. A common use for this is in hiding data which changes with every request, such as a 'jsession=' session id, so that the baseline diff does not show the HTML as having changed since the last request.

    # Hide changing jsession values so the baseline will be consistent
    PreProcessor = sub {
        my($data) = @_;
        @{$data} = grep(s/jsessionid=\w+/jsessionid=-removed-;/g,@{$data});
    }
VBServerURI

A URI which specifies which VB Server to report results to. Defaults to the environment variable $VBURI.

    VBServerURI => 'http://myvbserver:4712',
VBHeader

An array containing strings to be used as header lines when transmitting results to the VB Server process. This only affects the response time VBObject in this case. Defaults to the following:

    VBHeader => [ 'Time              Resp Time (sec)',
                  '----------------- ---------------' ];
VBDetail

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. This only affects the response time VBObject in this case. The only useful variable here is '$data[0]' which get the response time in seconds. Defaults to:

    VBDetail => [ '@<<<<<<<<<<<<<<<< @>>>>>>>>>>>>>>',
                  '$time,            $data[0]' ],
LogFile

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/http.testhost.log',
LogHeader

Same as VBHeader, but to be used in formatting the log file.

LogDetail

Same as VBDetail, but to be used in formatting the log file.

RotateLogAt

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',
Timeout

A number indicating the max number of seconds which can elapse before the connection attempt is killed and the status of any VBObjects set to the status specified in 'ErrorStatus'. (Defaults to 15).

    Timeout => 15,
ErrorStatus

The status to which any associated VBObjects should be set if the HTTP request fails or times out. (Defaults to 'Warning')

    ErrorStatus => 'Warning',
DebugHeader

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 Http objects running under a single unix process. (Defaults to the URL)

    DebugHeader => 'URL1',
AllowCookies

A boolean value (0 or 1) indicating whether the client should make use of cookies when requesting URL's. The cookies are only stored in memory, so restarting the client causes them to be cleared out, but it helps if you're monitoring a web site which would otherwise allocate you a new session with every request. (Defaults to 1).

$o = $s->addVBObj(<parm1> => <val1>, <parm2> => <val2>, ...)

The 'addVBObj' is used to define VBObjects which will appear on the VBServer to which status reports are transmitted. See VBTK::Parser for a detailed description of the main parameters. This class is special, however in that it makes use of two VBObjects by default. The usual parameters correspond to the response time VBObject. These are described in VBTK::Parser. An additional 4 parameters are used by the baseline VBObject as follows:

BaselineVBObjName

Same as 'VBObjName' but for the Baseline VBObject. This is required to make use of any of the baseline functionality. (Defaults to none).

    BaselineVBObjName => '.external.http.rmthost.baseline',
BaselineDiffStatus

A string containing a status to which the baseline VBObject should be set if there are differences between the retrieved text and the baseline. If this is not set, then no baseline comparison will be done. (Defaults to none).

    BaselineDiffStatus => 'Warning',
BaselineRules

Same as 'Rules' (See VBTK::Parser) but for the Baseline VBObject. No splitting is done on the data coming into the baseline VBObject, so the only really useful variable which you can use in 'BaselineRules' is '$data', which is the full text of the current line of HTML. This is useful for looking for error messages or other unwanted text in the HTML.

    BaselineRules => [
        '$data =~ /error|warn/i' => 'Warning' ],
BaselineRequirements

Same as 'Requirements' (See VBTK::Parser), but for the baseline VBObject. No splitting is done on the data coming into the baseline VBObject, so the only really useful variable which you can use in 'BaselineRequirements' is '$data', which is the full text of the current line of HTML. This is useful for ensuring that the retrieved HTML contains certain text which you know should be there every time.

    BaselineRequirements => [
        '$data =~ /success/i' => 'Warning' ],

PRIVATE METHODS

The following private methods are used internally. Do not try to use them unless you know what you are doing.

To be documented...

SEE ALSO

VBTK::Wrapper VBTK::ClientObject

AUTHOR

Brent Henry, vbtoolkit@yahoo.com

COPYRIGHT

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.