NAME

rrdpoller - Retrieve RRD file data and apply some threshold algorithm

SYNOPSIS

rrdpoller [OPTIONS] list|ls filename

rrdpoller [OPTIONS] get filename datasource [offset=time] [cf=func-name] [and|or command...]

rrdpoller [OPTIONS] exact filename datasource value [and|or command...]

rrdpoller [OPTIONS] boundaries filename datasource [min=number] [max=number] [and|or command...]

rrdpoller [OPTIONS] relation filename datasource [<|>]threshold[%] [target=filename] [compare-ds=datasource] [offset=time] [and|or command...]

rrdpoller [OPTIONS] quotient filename datasource [<|>]threshold[%] [target=filename] [target-ds=datasource] [offset=time] [and|or command...]

rrdpoller [OPTIONS] hunt filename datasource roll [parent=filename] [parent-ds=datasource] [and|or command...]

DESCRIPTION

rrdpoller allows you to poll RRD files and get current value of a given datasource. Additionally it implement some advanced checks able to use past values to decide if the current one is out of threshold or not.

The main purpose of this tool is to do the interface between an existing monitoring system like BigBrother, Nagios or Mon and a set of RRD graphs generated by some specialized data collectors like rrdcollect, Cricket and such. Thus you can build a very modular monitoring/trend architecture without the need of double polling.

EXAMPLES

Those examples are fictive, they doesn't represent real numbers. It's just to let you figure out what you can do with each algorithm.

rrdpoller ls host1-net.rrd

Returns the whole list of datasources contained in the file.

rrdpoller get host1-load.rrd 1min_avg

Get the current value of the 1min_avg datasource of the host1-load.rrd file.

rrdpoller --proxy http://xmlrpc.monserver.com:8080/ get host1-load.rrd 1min_avg

Same as precedent but querying a remove daemon (see rrdpollerd).

rrdpoller exact host1-service.rrd http 1

Get the current value of the http datasource of the host1-load.rrd file and return false if not equal to 1.

rrdpoller boundaries host1-load.rrd 5min_avg max=15

Get the current value of the 5min_avg datasource of the host1-load.rrd file and return false if greater than 15.

rrdpoller relation host1-disk.rrd usage 100000 offset=1min

Compare the current usage datasource value of the host1-disk.rrd file with the same datasource 1 minute ago and return false if the delta is greater than 100000.

rrdpoller quotient host1-mem.rrd usage 90% target-ds=total

Compare the current usage datasource of the host1-mem.rrd file and divide it by the total datasource of the same file. The command returns false if the obtained percentage is greater than 90%.

rrdpoller hunt pop2.rrd users 40 target=pop1.rrd

If the users datasource of the pop2.rrd file is non-zero and the same datasource of the pop1.rrd hasn't yet reach 40, the command will return false.

rrdpoller quotient host1-mem.rrd high_mem,low_mem,+ 90% target-ds=low_total,high_total,+

Same as former quotient example but using RPN datasource feature. Here the high_mem and the low_mem datasources will be summed then the low_total and the high_total too before to do the quotient computation.

rrdpoller different mysql-slave.rrd insert,update,delete,+ 0 or equal mysql-master.rrd insert,update,delete,+ 0

First test will fail if the sum of inserts, updates and deletes is equal to 0. If failed, the second test will verify if the same sum is also equal to 0 on the master and will finally fail if not. Thus we can verify that the MySQL replication is running.

COMMAND SYNTAX

The rrdpoller is followed by one of its sub-command and related arguments (See below). Sub-commands arguments are key=value pair and can alternatively be written as --key value pair for backward compatibility. Since version 1.5.0, several sub-commands can be chained together with special keywords and and or. Each sub-commands return a result, one by line in the order they have been called. When several sub-commands are chained, all sub-commands are executed, even if the first have failed and the second was chained with the and keyword. You can change this behavior with the --lazy option, but don't expect to see the result of sub-commands that doesn't have been executed then.

COMMON OPTIONS

--proxy URL

If you use this option, the rrdpoller command will turn into an XML-RPC client and will ask send all RRD queries to a remote rrdpoller daemon (see rrdpollerd for more information).

--max-last seconds

If this option is specified with an integer, the test will return false if the last updated row is older than X seconds. The exit code will be 2 if this test fails instead of 1 for normal tests.

--lazy

If several sub-commands are chained with the and or or keywords, don't exec all sub-command if the expression doesn't need it.

--quiet

Don't print sub-command results. Implies --lazy

SUB-COMMANDS

All sub-commands needs at least the too first arguments filename and datasource (except for list command). Except for the get and list commands (which doesn't perform a test), all sub-command will change the rrdpoller return code to false (1) if the test fails. All sub-commands will print the given datasource value of the given filename on the standard output.

The datasource can be an RPN expression (see Math::RPN) as well as all other datasource options. Note that the Math::RPN module have to be installed in order to use this feature.

list|ls filename

This command list all datasources of the given file.

get filename datasource [OPTIONS]

This sub-command the last inserted value in the given datasource of the given RRD filename. You can get an older value by giving an offset that will be expressed as: <last_inserted_time> - <offset>.

options:

offset=time

Makes the get command to retrieve an earlier value. It substract the value of time to the timestamp of the last value inserted in the datasource. The time can be expressed in second (ie 60) or in RRD time reference specification format (see "TIME REFERENCE SPECIFICATION" in rrdfetch).

cf=func-name

Default consolidation function is AVERAGE. This option allow you to change it to whichever you want.

exact filename datasource exact

This threshold allows you to monitor the datasource for an exact match. This is useful in cases where an enumerated (or boolean) SNMP object instruments a condition where a transition to a specific state requires attention. For example, a datasource might return either true(1) or false(2), depending on whether or not a power supply has failed.

boundaries filename datasource [OPTIONS]

This threshold takes too optional values, a minimum and a maximum value. If the datasource strays outside of this interval, the test fail.

options:

min=number

If current value is lower than number, the test fail

max=number

If current value is greater than number, the test fail

relation filename datasource [<|>]threshold[%] [OPTIONS]

A relation threshold considers the difference between two datasources (possibly from different RRD files), or alternatively, the difference between two temporally distinct values for the same datasource. The difference can be expressed as absolute value, or as a percentage of the second datasource (comparison) value. This difference is compared to a threshold argument with either the greater than (>) or lesser than (<) operator. The criteria fails when the expression (<absolute or relative difference> <either greater-than or less-than> <threshold>) evaluates to false.

The threshold number, optionally preceded by the greater than (>) or less than (<) symbol, and optionally followed by the symbol percent (%). If omitted, greater than is used by default and the expression: difference > threshold, is evaluated. "<10%", ">1000", "50%", and "500" are all examples of valid thresholds.

options:

target=filename

The path of the comparison RRD file. This argument is optional and if omitted the first RRD file is also taken as the comparison target.

target-ds=datasource

The name of the comparison datasource. This datasource must belong to the comparison RRD file. This argument is optional and if omitted the first datasource name is also taken as the comparison datasource name. If the value is a number, the value is considered as a fix value and is taked for the comparison.

offset=time

The temporal offset to go back from the first value to fetch the comparison datasource value. Note that a data source value must exist in the RRD file for that exact offset. If This argument is optional and if omitted, it is set to 0. The time value can be expressed in second (ie 60) or in RRD time reference specification format (see "TIME REFERENCE SPECIFICATION" in rrdfetch).

quotient filename datasource [<|>]threshold[%] [OPTIONS]

Quotient thresholds are similar to relation thresholds, except that they consider the quotient of two data sources, or alternatively, the same data source at two different time points. For a quotient monitor threshold, the value of the first data source is computed as a percentage of the second data source value (such as 10 (first datasource) is 50% of 20 (second datasource)). This percentage is then compared to a threshold argument with either the greater than (>) or less than (<) operator. The criteria fails when the expression (<percentage> <either greater-than or less-than> <threshold>) evaluates to false.

The threshold number, optionally preceded by the greater than (>) or less than (<) symbol and followed by the symbol percent (%). If omitted, greater than is used by default and the expression: difference > threshold, is evaluated. "<10%" and "50%" are all examples of valid thresholds.

options:

target=filename

The path of the comparison RRD file. This argument is optional and if omitted the first RRD file is also taken as the comparison target.

target-ds=datasource

The name of the comparison datasource. This datasource must belong to the comparison RRD file. This argument is optional and if omitted the first datasource name is also taken as the comparison datasource name. If the value is a number, the value is considered as a fix value and is taked for the comparison.

offset=time

The temporal offset to go back from the first value to fetch the comparison datasource value. Note that a data source value must exist in the RRD file for that exact offset. If This argument is optional and if omitted, it is set to 0. The time value can be expressed in second (ie 60) or in RRD time reference specification format (see "TIME REFERENCE SPECIFICATION" in rrdfetch).

hunt roll [OPTIONS]

The hunt threshold is designed for the situation where the data source serves as an overflow for another data source; that is, if one data source (the parent) is at or near capacity, then traffic will begin to appear on this (the monitored) data source. One application of hunt monitor thresholds is to identify premature rollover in a set of modem banks configured to hunt from one to the next. Specifically, the criteria of the hunt monitor threshold fails if the value of the monitored data source is non-zero and the current value of the parent data source falls below a specified capacity threshold.

The roll argument is the threshold of the parent data source. Generally this should be slightly less than the maximum capacity of the target.

options:

parent=filename

The path of the comparison RRD file. This argument is optional and if omitted the first RRD file is also taken as the comparison target.

parent-ds=datasource

The name of the comparison datasource. This datasource must belong to the comparison RRD file. This argument is optional and if omitted the first datasource name is also taken as the comparison datasource name. If the value is a number, the value is considered as a fix value and is taked for the comparison.

EXIT STATUS

0

Successful test

1

Performed test returned a false value

2

The max-last was reached

255

An exception was thrown

AUTHOR

Olivier Poitrey <rs@rhapsodyk.net>

LICENCE

rrdpoller retrieves RRD file data and apply some threshold algorithm. Copyright (C) 2004 Olivier Poitrey

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

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.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

SEE ALSO

RRD::Query, RRD::Threshold, rrdtool, RRDs, rrdpollerd

cpanm RRD::Query

perl -MCPAN -e shell
install RRD::Query