Provided by: librrd-simple-perl_1.44-1_all bug

NAME

       RRD::Simple - Simple interface to create and store data in RRD files

SYNOPSIS

        use strict;
        use RRD::Simple ();

        # Create an interface object
        my $rrd = RRD::Simple->new( file => "myfile.rrd" );

        # Create a new RRD file with 3 data sources called
        # bytesIn, bytesOut and faultsPerSec.
        $rrd->create(
                    bytesIn => "GAUGE",
                    bytesOut => "GAUGE",
                    faultsPerSec => "COUNTER"
                );

        # Put some arbitrary data values in the RRD file for the same
        # 3 data sources called bytesIn, bytesOut and faultsPerSec.
        $rrd->update(
                    bytesIn => 10039,
                    bytesOut => 389,
                    faultsPerSec => 0.4
                );

        # Generate graphs:
        # /var/tmp/myfile-daily.png, /var/tmp/myfile-weekly.png
        # /var/tmp/myfile-monthly.png, /var/tmp/myfile-annual.png
        my %rtn = $rrd->graph(
                    destination => "/var/tmp",
                    title => "Network Interface eth0",
                    vertical_label => "Bytes/Faults",
                    interlaced => ""
                );
        printf("Created %s\n",join(", ",map { $rtn{$_}->[0] } keys %rtn));

        # Return information about an RRD file
        my $info = $rrd->info;
        require Data::Dumper;
        print Data::Dumper::Dumper($info);

        # Get unixtime of when RRD file was last updated
        my $lastUpdated = $rrd->last;
        print "myfile.rrd was last updated at " .
              scalar(localtime($lastUpdated)) . "\n";

        # Get list of data source names from an RRD file
        my @dsnames = $rrd->sources;
        print "Available data sources: " . join(", ", @dsnames) . "\n";

        # And for the ultimately lazy, you could create and update
        # an RRD in one go using a one-liner like this:
        perl -MRRD::Simple=:all -e"update(@ARGV)" myfile.rrd bytesIn 99999

DESCRIPTION

       RRD::Simple provides a simple interface to RRDTool's RRDs module.  This module does not
       currently offer a "fetch" method that is available in the RRDs module.

       It does however create RRD files with a sensible set of default RRA (Round Robin Archive)
       definitions, and can dynamically add new data source names to an existing RRD file.

       This module is ideal for quick and simple storage of data within an RRD file if you do not
       need to, nor want to, bother defining custom RRA definitions.

METHODS

   new
        my $rrd = RRD::Simple->new(
                file => "myfile.rrd",
                rrdtool => "/usr/local/rrdtool-1.2.11/bin/rrdtool",
                tmpdir => "/var/tmp",
                cf => [ qw(AVERAGE MAX) ],
                default_dstype => "GAUGE",
                on_missing_ds => "add",
            );

       The "file" parameter is currently optional but will become mandatory in future releases,
       replacing the optional $rrdfile parameters on subsequent methods. This parameter specifies
       the RRD filename to be used.

       The "rrdtool" parameter is optional. It specifically defines where the "rrdtool" binary
       can be found. If not specified, the module will search for the "rrdtool" binary in your
       path, an additional location relative to where the "RRDs" module was loaded from, and in
       /usr/local/rrdtool*.

       The "tmpdir" parameter is option and is only used what automatically adding a new data
       source to an existing RRD file. By default any temporary files will be placed in your
       default system temp directory (typically /tmp on Linux, or whatever your TMPDIR
       environment variable is set to). This parameter can be used for force any temporary files
       to be created in a specific directory.

       The "rrdtool" binary is only used by the "add_source" method, and only under certain
       circumstances. The "add_source" method may also be called automatically by the "update"
       method, if data point values for a previously undefined data source are provided for
       insertion.

       The "cf" parameter is optional, but when specified expects an array reference. The "cf"
       parameter defines which consolidation functions are used in round robin archives (RRAs)
       when creating new RRD files. Valid values are AVERAGE, MIN, MAX and LAST. The default
       value is AVERAGE and MAX.

       The "default_dstype" parameter is optional. Specifying the default data source type (DST)
       through the new() method allows the DST to be localised to the $rrd object instance rather
       than be global to the RRD::Simple package.  See $RRD::Simple::DEFAULT_DSTYPE.

       The "on_missing_ds" parameter is optional and will default to "add" when not defined. This
       parameter will determine what will happen if you try to insert or update data for a data
       source name that does not exist in the RRD file. Valid values are "add", "ignore" and
       "die".

   create
        $rrd->create($rrdfile, $period,
                source_name => "TYPE",
                source_name => "TYPE",
                source_name => "TYPE"
            );

       This method will create a new RRD file on disk.

       $rrdfile is optional and will default to using the RRD filename specified by the "new"
       constructor method, or "$0.rrd". (Script basename with the file extension of .rrd).

       $period is optional and will default to "year". Valid options are "hour",
       "6hour"/"quarterday", "12hour"/"halfday", "day", "week", "month", "year", "3years" and
       "mrtg". Specifying a data retention period value will change how long data will be
       retained for within the RRD file. The "mrtg" scheme will try and mimic the data retention
       period used by MRTG v2.13.2 (<http://people.ee.ethz.ch/~oetiker/webtools/mrtg/>.

       The "mrtg" data retention period uses a data stepping resolution of 300 seconds (5
       minutes) and heartbeat of 600 seconds (10 minutes), whereas all the other data retention
       periods use a data stepping resolution of 60 seconds (1 minute) and heartbeat of 120
       seconds (2 minutes).

       Each data source name should specify the data source type. Valid data source types (DSTs)
       are GAUGE, COUNTER, DERIVE and ABSOLUTE. See the section regrading DSTs at
       <http://oss.oetiker.ch/rrdtool/doc/rrdcreate.en.html> for further information.

       RRD::Simple will croak and die if you try to create an RRD file that already exists.

   update
        $rrd->update($rrdfile, $unixtime,
                source_name => "VALUE",
                source_name => "VALUE",
                source_name => "VALUE"
            );

       This method will update an RRD file by inserting new data point values in to the RRD file.

       $rrdfile is optional and will default to using the RRD filename specified by the "new"
       constructor method, or "$0.rrd". (Script basename with the file extension of .rrd).

       $unixtime is optional and will default to "time()" (the current unixtime).  Specifying
       this value will determine the date and time that your data point values will be stored
       against in the RRD file.

       If you try to update a value for a data source that does not exist, it will automatically
       be added for you. The data source type will be set to whatever is contained in the
       $RRD::Simple::DEFAULT_DSTYPE variable. (See the VARIABLES section below).

       If you explicitly do not want this to happen, then you should check that you are only
       updating pre-existing data source names using the "sources" method.  You can manually add
       new data sources to an RRD file by using the "add_source" method, which requires you to
       explicitly set the data source type.

       If you try to update an RRD file that does not exist, it will attept to create the RRD
       file for you using the same behaviour as described above. A warning message will be
       displayed indicating that the RRD file is being created for you if have perl warnings
       turned on.

   last
        my $unixtime = $rrd->last($rrdfile);

       This method returns the last (most recent) data point entry time in the RRD file in UNIX
       time (seconds since the epoch; Jan 1st 1970). This value should not be confused with the
       last modified time of the RRD file.

       $rrdfile is optional and will default to using the RRD filename specified by the "new"
       constructor method, or "$0.rrd". (Script basename with the file extension of .rrd).

   sources
        my @sources = $rrd->sources($rrdfile);

       This method returns a list of all of the data source names contained within the RRD file.

       $rrdfile is optional and will default to using the RRD filename specified by the "new"
       constructor method, or "$0.rrd". (Script basename with the file extension of .rrd).

   add_source
        $rrd->add_source($rrdfile,
                source_name => "TYPE"
            );

       You may add a new data source to an existing RRD file using this method. Only one data
       source name can be added at a time. You must also specify the data source type.

       $rrdfile is optional and will default to using the RRD filename specified by the "new"
       constructor method, or "$0.rrd". (Script basename with the file extension of .rrd).

       This method can be called internally by the "update" method to automatically add missing
       data sources.

   rename_source
        $rrd->rename_source($rrdfile, "old_datasource", "new_datasource");

       You may rename a data source in an existing RRD file using this method.

       $rrdfile is optional and will default to using the RRD filename specified by the "new"
       constructor method, or "$0.rrd". (Script basename with the file extension of .rrd).

   graph
        my %rtn = $rrd->graph($rrdfile,
                destination => "/path/to/write/graph/images",
                basename => "graph_basename",
                timestamp => "both", # graph, rrd, both or none
                periods => [ qw(week month) ], # omit to generate all graphs
                sources => [ qw(source_name1 source_name2 source_name3) ],
                source_colors => [ qw(ff0000 aa3333 000000) ],
                source_labels => [ ("My Source 1", "My Source Two", "Source 3") ],
                source_drawtypes => [ qw(LINE1 AREA LINE) ],
                line_thickness => 2,
                extended_legend => 1,
                rrd_graph_option => "value",
                rrd_graph_option => "value",
                rrd_graph_option => "value"
            );

       This method will render one or more graph images that show the data in the RRD file.

       The number of image files that are created depends on the retention period of the RRD
       file. Hourly, 6 hourly, 12 hourly, daily, weekly, monthly, annual and 3year graphs will be
       created if there is enough data in the RRD file to accommodate them.

       The image filenames will start with either the basename of the RRD file, or whatever is
       specified by the "basename" parameter. The second part of the filename will be "-hourly",
       "-6hourly", "-12hourly", "-daily", "-weekly", "-monthly", "-annual" or "-3year" depending
       on the period that is being graphed.

       $rrdfile is optional and will default to using the RRD filename specified by the "new"
       constructor method, or "$0.rrd". (Script basename with the file extension of .rrd).

       Graph options specific to RRD::Simple are:

       destination
           The "destination" parameter is optional, and it will default to the same path location
           as that of the RRD file specified by $rrdfile. Specifying this value will force the
           resulting graph images to be written to this path location. (The specified path must
           be a valid directory with the sufficient permissions to write the graph images).

       basename
           The "basename" parameter is optional. This parameter specifies the basename of the
           graph image files that will be created. If not specified, it will default to the name
           of the RRD file. For example, if you specify a basename name of "mygraph", the
           following graph image files will be created in the "destination" directory:

            mygraph-daily.png
            mygraph-weekly.png
            mygraph-monthly.png
            mygraph-annual.png

           The default file format is "png", but this can be explicitly specified using the
           standard RRDs options. (See below).

       timestamp
            my %rtn = $rrd->graph($rrdfile,
                    timestamp => "graph", # graph, rrd, both or none
                );

           The "timestamp" parameter is optional, but will default to "graph". This parameter
           specifies which "last updated" timestamps should be added to the bottom right hand
           corner of the graph.

           Valid values are: "graph" - the timestamp of when the graph was last rendered will be
           used, "rrd" - the timestamp of when the RRD file was last updated will be used, "both"
           - both the timestamps of when the graph and RRD file were last updated will be used,
           "none" - no timestamp will be used.

       periods
           The "periods" parameter is an optional list of periods that graphs should be generated
           for. If omitted, all possible graphs will be generated and not restricted to any
           specific subset. See the create method for a list of valid time periods.

       sources
           The "sources" parameter is optional. This parameter should be an array of data source
           names that you want to be plotted. All data sources will be plotted by default.

       source_colors
            my %rtn = $rrd->graph($rrdfile,
                    source_colors => [ qw(ff3333 ff00ff ffcc99) ],
                );

            %rtn = $rrd->graph($rrdfile,
                    source_colors => { source_name1 => "ff3333",
                                       source_name2 => "ff00ff",
                                       source_name3 => "ffcc99", },
                );

           The "source_colors" parameter is optional. This parameter should be an array or hash
           of hex triplet colors to be used for the plotted data source lines. A selection of
           vivid primary colors will be set by default.

       source_labels
            my %rtn = $rrd->graph($rrdfile,
                    sources => [ qw(source_name1 source_name2 source_name3) ],
                    source_labels => [ ("My Source 1","My Source Two","Source 3") ],
                );

            %rtn = $rrd->graph($rrdfile,
                    source_labels => { source_name1 => "My Source 1",
                                       source_name2 => "My Source Two",
                                       source_name3 => "Source 3", },
                );

           The "source_labels" parameter is optional. The parameter should be an array or hash of
           labels to be placed in the legend/key underneath the graph. An array can only be used
           if the "sources" parameter is also specified, since the label index position in the
           array will directly relate to the data source index position in the "sources" array.

           The data source names will be used in the legend/key by default if no "source_labels"
           parameter is specified.

       source_drawtypes
            my %rtn = $rrd->graph($rrdfile,
                    source_drawtypes => [ qw(LINE1 AREA LINE) ],
                );

            %rtn = $rrd->graph($rrdfile,
                    source_colors => { source_name1 => "LINE1",
                                       source_name2 => "AREA",
                                       source_name3 => "LINE", },
                );

            %rtn = $rrd->graph($rrdfile,
                    sources => [ qw(system user iowait idle) ]
                    source_colors => [ qw(AREA STACK STACK STACK) ],
                );

           The "source_drawtypes" parameter is optional. This parameter should be an array or
           hash of drawing/plotting types to be used for the plotted data source lines. By
           default all data sources are drawn as lines (LINE), but data sources may also be drawn
           as filled areas (AREA). Valid values are, LINE, LINEn (where n represents the
           thickness of the line in pixels), AREA or STACK.

       line_thickness
           Specifies the thickness of the data lines drawn on the graphs for any data sources
           that have not had a specific line thickness already specified using the
           "source_drawtypes" option.  Valid values are 1, 2 and 3 (pixels).

       extended_legend
           If set to boolean true, prints more detailed information in the graph legend by adding
           the minimum, maximum and last values recorded on the graph for each data source.

       Common RRD graph options are:

       title
           A horizontal string at the top of the graph.

       vertical_label
           A vertically placed string at the left hand side of the graph.

       width
           The width of the canvas (the part of the graph with the actual data and such). This
           defaults to 400 pixels.

       height
           The height of the canvas (the part of the graph with the actual data and such). This
           defaults to 100 pixels.

       For examples on how to best use the "graph" method, refer to the example scripts that are
       bundled with this module in the examples/ directory. A complete list of parameters can be
       found at <http://people.ee.ethz.ch/~oetiker/webtools/rrdtool/doc/index.en.html>.

   retention_period
        my $seconds = $rrd->retention_period($rrdfile);

       This method will return the maximum period of time (in seconds) that the RRD file will
       store data for.

       $rrdfile is optional and will default to using the RRD filename specified by the "new"
       constructor method, or "$0.rrd". (Script basename with the file extension of .rrd).

   info
        my $info = $rrd->info($rrdfile);

       This method will return a complex data structure containing details about the RRD file,
       including RRA and data source information.

       $rrdfile is optional and will default to using the RRD filename specified by the "new"
       constructor method, or "$0.rrd". (Script basename with the file extension of .rrd).

   heartbeat
        my $heartbeat = $rrd->heartbeat($rrdfile, "dsname");
        my @rtn = $rrd->heartbeat($rrdfile, "dsname", 600);

       This method will return the current heartbeat of a data source, or set a new heartbeat of
       a data source.

       $rrdfile is optional and will default to using the RRD filename specified by the "new"
       constructor method, or "$0.rrd". (Script basename with the file extension of .rrd).

VARIABLES

   $RRD::Simple::DEBUG
       Debug and trace information will be printed to STDERR if this variable is set to 1
       (boolean true).

       This variable will take its value from $ENV{DEBUG}, if it exists, otherwise it will
       default to 0 (boolean false). This is a normal package variable and may be safely modified
       at any time.

   $RRD::Simple::DEFAULT_DSTYPE
       This variable is used as the default data source type when creating or adding new data
       sources, when no other data source type is explicitly specified.

       This variable will take its value from $ENV{DEFAULT_DSTYPE}, if it exists, otherwise it
       will default to "GAUGE". This is a normal package variable and may be safely modified at
       any time.

EXPORTS

       You can export the following functions if you do not wish to go through the extra effort
       of using the OO interface:

        create
        update
        last_update (synonym for the last() method)
        sources
        add_source
        rename_source
        graph
        retention_period
        info
        heartbeat

       The tag "all" is available to easily export everything:

        use RRD::Simple qw(:all);

       See the examples and unit tests in this distribution for more details.

SEE ALSO

       RRD::Simple::Examples, RRDTool::OO, RRDs, <http://www.rrdtool.org>, examples/*.pl,
       http://search.cpan.org/src/NICOLAW/RRD-Simple-1.44/examples/
       <http://search.cpan.org/src/NICOLAW/RRD-Simple-1.44/examples/>, <http://rrd.me.uk>

VERSION

       $Id: Simple.pm 1100 2008-01-24 17:39:35Z nicolaw $

AUTHOR

       Nicola Worthington <nicolaw@cpan.org>

       <http://perlgirl.org.uk>

       If you like this software, why not show your appreciation by sending the author something
       nice from her Amazon wishlist
       <http://www.amazon.co.uk/gp/registry/1VZXC59ESWYK0?sort=priority>?  (
       http://www.amazon.co.uk/gp/registry/1VZXC59ESWYK0?sort=priority )

COPYRIGHT

       Copyright 2005,2006,2007,2008 Nicola Worthington.

       This software is licensed under The Apache Software License, Version 2.0.

       http://www.apache.org/licenses/LICENSE-2.0 <http://www.apache.org/licenses/LICENSE-2.0>