/ 
VBTK-0.20
River stage zero No dependents
/ VBTK::Parser

NAME

VBTK::Parser - Class for handling parsing and processing of incoming data

SYNOPSIS

Do not access this class directly. It is called by the major data-gathering classes (Wrapper, Snmp, Dbi, Http, Tcp, Smtp, Pop3, etc.) to handle the parsing of data and client-side processing of VBObjects.

# Associate a VBObject with a data-gathering object
$vbObj = $obj->addVBObj(
  VBObjName           => ".myhost.cpu",
  TextHistoryLimit    => 50,
  ReverseText         => 1,
  Rules               => {
    '($data[1] > 3)'   => 'Warn',
    '($data[1] > 6)'   => 'Fail',
    '($data[22] <= 0)' => 'Warn' },
  StatusHistoryLimit  => 30,
  StatusChangeActions => undef,
  StatusUpgradeRules  => 'Upgrade to Failed if Warning occurs 2 times in 6 min',
  ExpireAfter         => '10 min',
  Description         => 'This object monitors CPU utilization on myhost',
  RrdColumns          => [ '$data[19]', '$data[20]', '$data[0]', '$data[11]' ],
);

# Add a graph group to the VBObject
$vbObj->addGraphGroup (
  GroupNumber    => 1,
  DataSourceList => undef,
  Labels         => 'user,system,runQueue,scanRate',
  Title          => "myhost cpu",
);

DESCRIPTION

This perl library is used by the data-gathering classes ( VBTK::Wrapper, VBTK::Snmp, VBTK::Tcp, VBTK::Http, and VBTK::DBI) to handle the definition and client-side processing of VBObjects. Do not attempt to call this class directly unless you are developing a new data-gathering class. Instead, use the 'addVBObj' method of the corresponding data-gathering class.

See VBTK::ClientObject for details on how to define graph groups for these VB objects.

PUBLIC METHODS

The following methods are available to the common user:

$vbObj = $obj->addVBObj (<parm1> => <val1>, <parm2> => <val2>, ...)

This initializes and returns a pointer to a VBTK::ClientObject object which will be used by the corresponding data-gathering class to report data to the VBServer. You should call this on the data-gathering class, not directly on the VBTK::Parser class. The allowed parameters are listed below.

Once the VBTK::ClientObject object has been defined, you will probably want to add graph groups to it so that graphs will be displayed in the VBServer web interface. For details on how to define graphs, see the 'addGraphGroup' method description in the VBTK::ClientObject.

VBObjName

A string containing a name which uniquely identifies this data. All corresponding data will appear on the VBServer web interface under this name. Should be of the form 'a.b.c ...'. The segments of the name make up the hierarchy under which is it stored in the VBServer. The web interface grid can show three levels of name segments at a time. Lower levels are rolled up into groups with the worst status being shown in the group. This allows the user to see the status of all objects at a glance, while still being able to drill down through the hierarchy to view details of individual objects.

For example, if you have two objects named 'sfo.myhost.cpu.idle' and 'sfo.myhost.cpu.user', they would both be grouped together as 'sfo.myhost.cpu' when looking at the top level of the web interface. Clicking on 'sfo.myhost.cpu', would then drill down and show you the 'idle' and 'user' sub objects. This can continue for 'n' levels.

Typically, a good naming scheme is: <location>.<host>.<service>[.optional]. If you name all your objects this way, then each matrix will represent a location, with the hosts as rows, and services as columns. You'll have to experiment with naming your objects to get the layout you want.

Note that if you leave the first segment off and start your object name with '.', then the VBServer will prepend it's 'ObjectPrefix' string to the object name. This is very nice if you have a common script which you run on machines in different locations. (Required)

VBObjName => '.myhost.cpu.idle'
Filter

A string containing a Perl expression involving the '$data', '@data', '@delta', or '@rate' variables, which, if specified must evaluate to true or the row will be ignored by the VBObject. See the 'Rules' parm for more details on these variables. (Defaults to none.)

# Ignore all rows unless $data[1] > 0
Filter => '$data[1] > 0',
TextHistoryLimit

A number indicating how many lines of Ascii text to preserve from previously reported data when transmitting a VBObject to the VBServer. This is useful when monitoring CPU time or tailling log files since it allows you to see the most recent (n) number of lines of output together. If not specified, then only the newly-arrived data is shown. (Defaults to undef).

TextHistoryLimit => 50,
ReverseText

A boolean (0 or 1) indicating whether rows should be displayed in reverse order. This is typically used together with the 'TextHistoryLimit' option so that as multiple rows accumulate, the most recent rows are shown at the top of the web interface. (Defaults to 0).

ReverseText => 1,
Rules

A pointer to a hash containing pairs of perl expressions and statuses. The expressions can make use of '$data', '@data', '@delta', or '@rate'. If the expression evaluates to true, then the object will be set to the specified status. If multiple rules are specified, they will all be evaluated, with the object being set to the highest (worst) status. For example:

Rules => {
    # Set to Failed if the line of text contains 'error' or 'fail'
    '$data =~ /error|fail/i' => 'Failed',
    # Set to Warning if column 0 is > 120
    '$data[0] > 120'         => 'Warn',
    # Set to Warning if column 4 is > 55
    '$delta[4] > 55'         => 'Warn' },

The allowed variables are as follows. (Defaults to none)

$data

The full text of the line currently being parsed.

@data

An array containing the split data. See the Split, Filter, and Pre-Processor Parms of the corresponding data-gathering class for details on how the data will be split.

@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. This is very common in SNMP monitors.

@rate

An array containing the same data as in the @delta array, but divided by the number of seconds since the last data retrieval.

$time

The current timestamp in the format YYYYMMDD-HH:MM:SS

Requirements

A pointer to a hash containing perl expressions and statuses. This is similar to the 'Rules' parm, except that the specified status will only be assigned to the VBObject if NO row in the current result set results in the expression being true. The same variables '$data', '@data', '@delta', and '@rate' are available to use in the expressions. For example:

Requirements => {
    '$data =~ /Success/' => 'Warning' },

In this example, the requirement is that at least one row of the current result set passed from the data-gatherer class must have the word 'Success' in it. If no matching row is found, then the status will be set to 'Warning'. (Defaults to none)

StatusHistoryLimit

A number indicating how many entries to maintain in the status history list for the web interface. (Defaults to 20)

StatusHistoryLimit => 30,
StatusChangeActions

A pointer to a hash containing pairs of statuses and action names. When a object's status changes, this hash is checked for the new status and all corresponding actions are triggered. Since actions are defined in the VBServer config, it's usually easier to use templates on the VBServer to setup this list rather than do it on the client. See the VBTK::Server for more details. (Defaults to none)

StatusChangeActions => {
    Failed   => 'emailme,pageme',
    Warning  => 'emailme' },
StatusUpgradeRules

A string or a pointer to an array of strings containing upgrade rule definitions. Upgrade rules are used to upgrade the status if a lower status occurs some number of times in a specified time period. This is useful for ignoring sporadic errors, such as a ping packet getting lost. The string should have a format as shown below. (Defaults to none)

Upgrade to <New Status> if <Test Status> occurs <Count> times in <Time Expression>

For example:

StatusUpgradeRules => 'Upgrade to Fail if Warn occurs 3 times in 10 min',
ExpireAfter

A string containing a time expression which indicates how long the VBServer should wait from the last status report before setting the status to 'Expired'. This is used to keep track of all monitoring processes and ensure that they are running. It's usually a good idea to set the expire time to 3 times the interval or more. Actions can be assigned to the 'Expired' status using the 'StatusChangeActions' parm. (Defaults to none)

ExpireAfter => '20 min',
Description

A string containing a description of this VBObject. This description will be shown on the web interface under the 'Info' tab. This is a good place to put instructions and notes about what to do if this object's status get's set to a non-Success status. (Defaults to none)

BaselineDiffStatus

A string containing a status to set the VBObject to if there is a difference between the reported text and the baseline text. If this status is specified, then a link will appear on the web interface which allows the user to select a history entry and set it as the baseline. All subsequent batches of data sent to the VBServer will be compared against this baseline with 'diff' and if any differences are found, the status will be set to the 'BaselineDiffStatus'. This is useful for monitoring the output of commands which should not change, such as machine hardware status (prtdiag) or disk volume layouts. Another use is in monitoring a web server where you want to be sure that not only can you connect, but also that the HTML is the same as when you last assigned the baseline. That way you'll know if your web site get's hacked, or someone breaks the home page, etc. (Defaults to none)

RrdColumns

A pointer to an array of strings containing perl expressions to be evaluated with the resulting values being stored in an associated Rrd library. If specified, then this will cause the VBServer to maintain an Rrd library for this object which is updated with every passed batch of data. The perl expressions can only make use of the '$time', '$data', '@data', '@delta', or '@rate' variables. See the 'Rules' parm for more details on theses variables. (Defaults to none.)

RrdColumns => [ '$data[0]', 'int($data[1]/100)' ],

Note that if you change the number of columns in this list, you will have to rebuild the Rrd library. This is done by deleting the existing library in the vbobj directory on the VBServer and then restarting the client process. In doing this, you will lose all historical data in the Rrd library.

RrdTimeCol

A string containing a perl expression to be used as the 'time' value in calls to 'rrd update'. If the 'RrdColumns' parms is set, then the VBServer will maintain an Rrd database which can be used to generate graphs. (Defaults to '$time', which is the current timestamp in a format of YYYYMMDD-HH:MM:SS)

RrdTimeCol => '$time',

Note that this parm is limited to using just the '$time', '$data', and '@data' variables. (Defaults to none)

RrdFilter

A string containing a Perl expression involving the '$data', '@data', '@delta', or '@rate' variables, which, if specified must evaluate to true or the row will not be added to the Rrd library. This is completely independent from the 'Filter' parm described above, so usually if you set one, you'll want to set the other the same. Otherwise you wouldn't see the same data in the text and in the Rrd graphs. See the 'Rules' parm above for more details on these variables. (Defaults to none.)

# Ignore all rows unless $data[1] > 0
Filter => '$data[1] > 0',
RrdMin

A number indicating the MIN value to be passed to the Rrd library. Any values passed to the Rrd library which are lower than this will be ignored. (Defaults to 0)

RrdMin => 0,
RrdMax

A number indicating the MAX value to be passed to the Rrd library. Any values passed to the Rrd library which are higher than this will be ignored. (Defaults to none)

RrdMax => 100,
RrdXFF

A number indicating the XFF to be used for the Rrd library. See the Rrd man page for details. (Defaults to 0.5)

RrdXFF => 0.5,
RrdCF

A string indicating which consolidation function should be used for the Rrd library. See the Rrd man page for details. (Defaults to 'AVERAGE')

RrdDST

A string indicating which DST option to use for the Rrd library. See the Rrd man page for details. (Defaults to 'GAUGE')

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::Snmp
VBTK::Tcp
VBTK::Http
VBTK::DBI
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.