rrdquery.pl

Intro

rrdquery.pl retrieves one datasource from an RRD (round robin database) and optionally filters its values. It is like rrdtool fetch but with projection and optional selection.
Intention for this was to determine whether and when a datasource exceeds a threshold. E.g. if you record your interface error rate and if that interface shows just a couple of times per week some discards or such, then it might be easier to use this Perl script instead of extending the RRD graphics definition or even zooming in and out the graph.

Usage

rrdquery.pl version 4

rrdquery.pl selects data from an RRD file with a SQL like approach where each
consolidation function (CF) represents its own table, and each datasource plus
the timestamp are the columns.
Most commandline options are shared with rrdfetch(1). Additional parameters
are explained below.

Usage:
  rrdquery.pl <rrdfile> --info|-i
  rrdquery.pl <rrdfile> <cf> <filter> [--resolution|-r <resolution>]
              [--start|-s <start>] [--end|-e <end>] [--align-start|-a]
              [--daemon|-d <address>] [--utc|-u]
  rrdquery.pl -h
  rrdquery.pl --help

Description:
  --info, -i   Output the names of all round robin archives (RRAs), the names
               of all datasources, as well as the oldest and latest update
               timestamp found in the round robin database (RRD) <rrdfile>
  --utc, -u    Display each timestamp in UTC time instead of local time
  --help       Display common examples
  -h           Display this help ;-)
  <filter>     Select a datasource and optionally filter rows

Filter syntax:
  FUNC(<dsname>) [<comparator> <value>|IS NULL]

  FUNC(...)     Optional aggregate function, one of COUNT(), SUM(), AVG(),
                MIN(), or MAX() (case insensitive)
  <dsname>      The name of a datasource in <rrdfile> (case sensitive)
  <comparator>  Any of =, !=, <> (same as !=), <, <=, >=, or >
  <value>       An integer or float value
  IS NULL       Output any row where <dsname> is null or NaN (case insensitive)

  Whitespace between <dsname>, <comparator>, and/or <value> may be omitted.
  Check for occurences where <dsname> has a non-NULL value can be achieved by
  specifying <dsname> only.

  If no value within the given time range matches the filter, or if the RRD
  file contains no value within in the time range, then rrdquery.pl prints no
  result.
  The COUNT() aggregate function always prints a result of zero or larger.

Examples

  1. Print all timestamps and values within the last 24 hours where maximum inBytes is larger then 23: 
    rrdquery.pl /var/db/rrd/interface-vmx0.rrd MAX "inBytes > 23"
  2. Print all timestamps and maximum inBytes within the last 2 weeks: 
    rrdquery.pl /var/db/rrd/interface-vmx0.rrd MAX inBytes -s end-2weeks
  3. Print the sum of all average outBytes: 
    rrdquery.pl /var/db/rrd/interface-vmx0.rrd AVERAGE "sum(outBytes)"
  4. Count the occurence of any average outBytes larger or equal than 42: 
    rrdquery.pl /var/db/rrd/interface-vmx0.rrd AVERAGE "count(outBytes) >= 42"
  5. Print all timestamps and values of all minimum inBytes within the last 24 hours: 
    rrdquery.pl /var/db/rrd/interface-vmx0.rrd MIN inBytes
  6. Print all timestamps and (NULL) values where no value has been added to the average consolidation function in the RRD file in February 2023: 
    rrdquery.pl /var/db/rrd/interface-vmx0.rrd AVERAGE inBytes is Null -s 20230201 -e "23:59 28.02.2023"

Files