The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
RRDTool-Creator-1.0
River stage zero No dependents
++
/ RRDTool::Creator

NAME

RRDTool::Creator - Creators for round robin databases (RRD)

COMPONENTS

RRDTool::Creator - A generic abstract creator for round robin databases (RRD)

RRDTool::Creator::HourPDP - creates a RRD with a default archive of primary points for an hour

RRDTool::Creator::DayPDP - creates a RRD with a default archive of primary points for a day

RRDTool::Creator::WeekPDP - creates a RRD with a default archive of primary points for a week

RRDTool::Creator::MonthPDP - creates a RRD with a default archive of primary points for a month

RRDTool::Creator::QuarterPDP - creates a RRD with a default archive of primary points for a quarter

RRDTool::Creator::YearPDP - creates a RRD with a default archive of primary points for a year

SYNOPSIS

  use RRDTool::Creator::DayPDP ; 

  # make a creator
  $creator = new RRDTool::Creator::DayPDP(-step => "30mn") ; 
  
  # add data sources in the specifications of the RRD
  $creator->add_DS(
            -ds_name => "cpu"
            , -DST => "GAUGE"
            , -min => 0
            , -max => 100
            ) ;
  
  $creator->add_DS(
            -ds_name => "swap"
            , -DST => "GAUGE"
            ) ;

  # add archives in the specifications of the RRD
  $creator->add_RRA(-duration => "week") ;
  $creator->add_RRA(-duration => "month") ;

  # add some consolidation functions in the specifications of the RRD
  $creator->add(-CF => "MAX") ;
  $creator->add(-CF => "AVERAGE") ;

  # create the RRD file
  $creator->create(-filename => "/var/rrdtool/vmstat.rrd") ;

DESCRIPTION

The RRDTool::Creator objects are specific creators for different kind of RRD files. They are based on the Round Robin Database Tool (http://www.rrdtool.org) and on the Perl module RRDTool::OO.

NOTES

RRDTool::Creator tries to be compatible with both the official RRDTool documentation and the RRDTool::OO module. It is why some functions and some arguments have two possible names (in this case, the main name is conform to the official documentation and the auxiliary one is for compatibility with the RRDTool::OO module).

COMMON METHODS

add_data_source

See add_DS

add_DS (auxiliary name: add_data_source)

Add a data source in the RRD specifications. Its arguments are :

ds_name (auxiliary name: name)

(mandatory) The name of the data source.

DST (auxiliary name: type)

(mandatory) The data source type : GAUGE, COUNTER, DERIVE or ABSOLUTE (see http://www.rrdtool.org).

heartbeat

(optionnal) The maximum number of seconds that may pass between two updates of this data source before the value of the data source is assumed to be *UNKNOWN*. Default is 2*step.

min

(optionnal) The expected minimum value for data supplied by a data source. Any value outside the defined range will be regarded as *UNKNOWN*. Default is "U" for unknown.

max

(optionnal) The expected maximum value for data supplied by a data source. Any value outside the defined range will be regarded as *UNKNOWN*. Default is "U" for unknown.

    $creator->add_DS(
                -ds_name => "cpu"
                , -DST => "GAUGE"
                , -min => 0
                , -max => 100
                ) ;

add_compute_DS (not yet implemented)

Add a data source with computed primary data points (it is a DS with DST equal to COMPUTE) in the RRD specifications. Its arguments are :

ds_name (auxiliary name: name)

(mandatory) The name of the data source.

rpn_expression

(mandatory) RPN expression that defines formula to compute PDP of this DS.

add_RRA (auxiliary name: add_archive)

Add a round robin archive in the RRD specifications.

duration

(mandatory) The duration of the archive. Possible values are : "day", "week", "month", "quarter" and "year".

xff

(optionnal) The xfiles factor (see <http://www.rrdtool.org>)

    $creator->add_RRA(-duration => "day") ;

add

Add some global attributes in the RRD specifications.

CF (auxiliary name: cfunc)

Add a consolidation function (AVERAGE, MIN, MAX, LAST... - see <http://www.rrdtool.org>), for each RRA (except the default RRA) in the RRD specifications.

    $creator->add(-CF => "AVERAGE") ;

compile

Compute the argument for the function create of the underlaying RRDTool::OO object. Useful for debugging, this function also allows to customize the command passed to rrdtool. Return this argument (a list).

    @args = $creator->compile() ;

create

Create the RRD on the disk.

filename (auxiliary name: file)

(mandatory) The name of the file to create.

OO_create_arg

(optionnal) The argument passed to the function create of the underlaying RRDTool::OO object (this is the value returned by the previous function compile). In normal case, this argument isn't provided, and its value is compiled from the current stored data.

    $creator->create(-filename => "/tmp/15s.rrd") ;

which can be break up to :

    @args = $creator->compile() ;
    # possible manual modification on @args here...
    $creator->create(-filename => "/tmp/15s.rrd", OO_create_arg => \@args) ;

SUB-OBJECTS

Each sub-objects of RRDTool::Creator creates a RRD with one default archive (RRA) made of primary data points (PDP). More RAA can then be added. The constructor neads an argument named step which is the period of acquisition. The time unit of the step depends of the sub-object.

RRDTool::Creator::HourPDP

The default RRA stores primary data points for an hour. More RRA can be added for a day, a week, a month, a quarter and a year. The created RRD is for an acquisition period much less than an hour, typically about some seconds or a few minutes. So, the step unit for its constructor argument is second(s) or minute(mn).

    $creator = new RRDTool::Creator::HourPDP(-step => "30s") ;
    $creator->add_RRA(-duration => "day") ;
    $creator->add_RRA(-duration => "week") ;
    $creator->add_RRA(-duration => "month") ;
    $creator->add_RRA(-duration => "quarter") ;
    $creator->add_RRA(-duration => "year") ;

RRDTool::Creator::DayPDP

The default RRA stores primary data points for a day. More RRA can be added for a week, a month, a quarter and a year. The created RRD is for an acquisition period much less than a day, typically about some minutes or a few hours. So, the natural step units for its constructor argument are the minute(mn) and hour(h), although second(s) is allowed.

    $creator = RRDTool::Creator::DayPDP(-step => "10mn") ;
    $creator->add_RRA(-duration => "week") ;
    $creator->add_RRA(-duration => "month") ;
    $creator->add_RRA(-duration => "quarter") ;
    $creator->add_RRA(-duration => "year") ;

RRDTool::Creator::WeekPDP

The default RRA stores primary data points for a week. More RRA can be added for a month, a quarter and a year. The created RRD is for an acquisition period much less than a week, typically about some hours. So, the natural step unit for its constructor argument is the hour(h), although second(s), minute(mn) and day(d) are allowed.

    $creator = RRDTool::Creator::WeekPDP(-step => "4h") ;
    $creator->add_RRA(-duration => "month") ;
    $creator->add_RRA(-duration => "quarter") ;
    $creator->add_RRA(-duration => "year") ;

RRDTool::Creator::MonthPDP

The default RRA stores primary data points for a month. More RRA can be added for a quarter and a year. The created RRD is for an acquisition period much less than a month, typically about some hours or a few days. So, the natural step unit for its constructor argument are hour(h) and day(d), although second(s), minute(m) and week(w) are allowed.

    $creator = RRDTool::Creator::MonthPDP(-step => "1d") ;
    $creator->add_RRA(-duration => "quarter") ;
    $creator->add_RRA(-duration => "year") ;

RRDTool::Creator::QuarterPDP

The default RRA stores primary data points for a quarter. More RRA can be added for a year. The created RRD is for an acquisition period much less than a quarter, typically about some days or a few weeks. So, the natural step unit for its constructor argument are day(d) and week(w), although second(s), minute(m), hour(h) and month(m) are allowed.

    $creator = RRDTool::Creator::QuarterPDP(-step => "3d") ;
    $creator->add_RRA(-duration => "year") ;

RRDTool::Creator::YearPDP

The default RRA stores primary data points for a year. No more RRA can be added. The created RRD is for an acquisition period much less than a year, typically about some days, a few weeks or months. So, the natural step unit for its constructor argument are day(d), week(w) and month(m), although second(s), minute(m), hour(h) and quarter(q) are allowed.

    $creator = RRDTool::Creator::YearPDP(-step => "1w") ;

EXAMPLES

EXAMPLE 1

To create a RRD to store percent cpu load and swap use, gathering every 10mn, with the aim of graphing average and max values daily, weekly, monthly and yearly :

    $creator = new RRDTool::Creator::DayPDP(-step => "10mn") ;
    $creator->add_DS(
                -ds_name => "cpu"
                , -DST => "GAUGE"
                , -min => 0
                , -max => 100
                ) ;
    $creator->add_DS(
                -ds_name => "swap"
                , -DST => "GAUGE"
                , -min => 0
                ) ;
    $creator->add(-CF => "AVERAGE") ;
    $creator->add(-CF => "MAX") ;
    $creator->add_RRA(-duration => "week") ;
    $creator->add_RRA(-duration => "month") ;
    $creator->add_RRA(-duration => "year") ;
    $creator->create(-filename => "vmstat.rrd") ;

EXAMPLE 2

To create a RRD to store number of spams and total mails received every days, with the aim of graphing average and max values quarterly and yearly :

    $creator = new RRDTool::Creator::QuarterPDP(-step => "1d") ;
    $creator->add_DS(
                -ds_name => "spams"
                , -DST => "GAUGE"
                , -min => 0
                ) ;
    $creator->add_DS(
                -ds_name => "mails"
                , -DST => "GAUGE"
                , -min => 0
                ) ;
    $creator->add(-CF => "AVERAGE") ;
    $creator->add(-CF => "MAX") ;
    $creator->add_RRA(-duration => "year") ;
    $creator->create(-filename => "mail.rrd") ;

EXAMPLE 3

To create a RRD to store disk usage every 4 hours, with the aim of graphing max values weekly and yearly :

    $creator = new RRDTool::Creator::WeekPDP(-step => "4h") ;
    $creator->add_DS(
                -ds_name => "/home"
                , -DST => "GAUGE"
                , -min => 0
                , -max => 100
                ) ;
    $creator->add_DS(
                -ds_name => "/var"
                , -DST => "GAUGE"
                , -min => 0
                , -max => 100
                ) ;
    $creator->add(-CF => "MAX") ;
    $creator->add_RRA(-duration => "year") ;
    $creator->create(-filename => "df.rrd") ;

SEE ALSO

http://www.rrdtool.org/doc, RRDTool::OO

AUTHOR

Jacquelin Charbonnel, <jacquelin.charbonnel at math.cnrs.fr>

BUGS

Please report any bugs or feature requests to bug-RRDTool-Creator at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=RRDTool-Creator. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc RRDTool-Creator

You can also look for information at:

COPYRIGHT & LICENSE

Copyright Jacquelin Charbonnel < jacquelin.charbonnel at math.cnrs.fr >

This software is governed by the CeCILL-C license under French law and abiding by the rules of distribution of free software. You can use, modify and/ or redistribute the software under the terms of the CeCILL-C license as circulated by CEA, CNRS and INRIA at the following URL "http://www.cecill.info".

As a counterpart to the access to the source code and rights to copy, modify and redistribute granted by the license, users are provided only with a limited warranty and the software's author, the holder of the economic rights, and the successive licensors have only limited liability.

In this respect, the user's attention is drawn to the risks associated with loading, using, modifying and/or developing or reproducing the software by the user in light of its specific status of free software, that may mean that it is complicated to manipulate, and that also therefore means that it is reserved for developers and experienced professionals having in-depth computer knowledge. Users are therefore encouraged to load and test the software's suitability as regards their requirements in conditions enabling the security of their systems and/or data to be ensured and, more generally, to use and operate it in the same conditions as regards security.

The fact that you are presently reading this means that you have had knowledge of the CeCILL-C license and that you accept its terms.