NAME

VBTK::Http - Database Monitoring

SYNOPSIS

  $d = new VBTK::DBI (
    Interval       => 60,
    DSN            => 'myoracle.world',
    User           => 'mylogin',
    Auth           => 'mypasswd',
    Attr           => 'Oracle',
    VBHeader       => undef,
    VBDetail       => [ '$data' ],
    VBServerURI    => 'http://myvbserver:4712',
    SqlClause      => 'select count(*) from v$sessions'
  );

  $d->addVBObj (
    VBObjName         => '.oracle.db.logincount',
    Rules             => [
      '$data[0] > 20' => 'Warning',
      '$data[0] > 40' => 'Failed' ],
    ExpireAfter       => '3 min',
    Description       => qq(
      This object monitors the number of users logged into the database),
  );

  &VBTK::runAll;

DESCRIPTION

This perl library provides the ability to do simple monitoring of any database accessible with the perl DBI module, using select statements. It makes use of connection pooling, so that multiple SQL statements being run against the same database will share a single connection.

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

SUB-CLASSES

There are many values to setup when declaring a DBI 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 currently provided:

VBTK::DBI::OraLogins

Defaults for monitoring connections and blocked processes in an Oracle database.

VBTK::DBI::OraTableSpace

Defaults for monitoring tablespace free-space and fragmentation in an Oracle database.

Others will follow. If you're interested in adding your own sub-class, just copy and modify one of the existing ones. Eventually, I'll get around to documenting this nicely, but it's pretty self-explanatory.

PUBLIC METHODS

The following methods are available to the common user:

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

The allowed parameters are as follows.

Interval

The interval (in seconds) on which the SQL query should be attempted. (Defaults to 60)

    Interval => 60,
DSN

A string containing the DSN to connect to. See the perl DBI man pages for details on the DSN. This is the 1st parameter passed to new DBI. (Required)

    DSN => 'myoracle.world',
User

A string containing the userid to connect with. See the perl DBI man pages for details on the User string. This is the 2nd parameter passed to 'new DBI( )'.

If no value is specified, then the VBTK::DBI module will look in the file specified by the environment variable $VBPSWD and use the first line specified there. $VBPSWD defaults to '$VBHOME/conf/.pswd' if not set in the environment. The $VBPSWD file should have a format of 'dsn userid password' with one entry per line.

    User => 'myuserid',
Auth

A string containing the authorization string/password to connect with. See the DBI man pages for details on the Auth string. This is the 3rd parameter passed to 'new DBI( )'.

If no value is specified, then the VBTK::DBI module will look in the file specified by the environment variable $VBPSWD for a row with a userid and DSN which match those specified in 'User' and 'DSN'. $VBPSWD defaults to '$VBHOME/conf/.pswd' if not set in the environment. The $VBPSWD file should have a format of 'dsn userid password' with one entry per line.

    Auth => 'mypassword',
Attr

A string containing the Attribute settings to connect with. See the DBI man pages for details on the Attr string. This is the 4th parameter passed to 'new DBI( )'.

    Attr => 'Oracle',
VBHeader

An array containing strings to be used as header lines when transmitting results to the VB Server process. (Defaults to 'none')

     VBHeader => [ 
        'Time              Number of logins',
        '----------------- ----------------' ];
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. Be sure to either use single-quotes or escape out the '$' vars so that they don't get evaluated until later.

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

The following variables will be set just before these detail lines are evaluated:

$time

A datestamp of the form YYYYMMDD-HH:MM:SS

@data

An array of arrays containing the rows and columns of the data retrieved in the SQL query.

@delta

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.

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. This will be an array of arrays containing the rows and columns as retrieved from the executed SQL. The PreProcessor subroutine can then alter the data, remove rows, add summary rows, etc. A common use for this would be to ignore rows you didn't want to appear in the output.

    # Only include rows where $data[0] is > 0.
    PreProcessor = sub {
        my($data) = @_;
        @{$data} = grep($_->[0] > 0,@{$data});
    }
VBServerURI

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

    VBServerURI => 'http://myvbserver:4712',
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/oracle.logincount.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',
ErrorStatus

A string containing a status to which any VBObjects should be set if there is an error while attempting to connect to the database or run the SQL. (Defaults to Failed).

    ErrorStatus => 'Warning',
SqlClause

A string containing the SQL statement to execute. The resulting rows and columns will be loaded into the @data array for processing.

    SQL => 'select count(*) from v$session',
$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.

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
VBTK::DBI::OraLogins
VBTK::DBI::OraTableSpace
VBTK::Server
VBTK::Parser
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.