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 *min*imum and a *max*imum
   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 <[email protected]>

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

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.