| RRD::Simple - Simple interface to create and store data in RRD files |
RRD::Simple - Simple interface to create and store data in RRD files
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 arbitary data values in the RRD file for 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
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.
my $rrd = RRD::Simple->new(
file => "myfile.rrd",
rrdtool => "/usr/local/rrdtool-1.2.11/bin/rrdtool",
cf => [ qw(AVERAGE MAX) ],
default_dstype => "GAUGE",
);
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 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 the $RRD::Simple::DEFAULT_DSTYPE manpage.
$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 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.
$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.
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).
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).
$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.
$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).
my %rtn = $rrd->graph($rrdfile,
destination => "/path/to/write/graph/images",
basename => "graph_basename",
timestamp => "both", # graph, rrd, both or none
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. Daily, weekly, monthly, annual and 3year graphs will be created if there is enough data in the RRD file to accomodate 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 ``-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 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 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 exmaple, 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).
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.
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.
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.
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.
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.
source_drawtypes option.
Valid values are 1, 2 and 3 (pixels).
Common RRD graph options are:
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.
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).
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).
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).
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.
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.
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.
the RRDTool::OO manpage, RRDs, http://www.rrdtool.org, examples/*.pl, http://search.cpan.org/src/NICOLAW/RRD-Simple-1.43/examples/, http://rrd.me.uk
$Id: Simple.pm 988 2007-03-04 23:51:22Z nicolaw $
Nicola Worthington <nicolaw@cpan.org>
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 )
Copyright 2005,2006,2007 Nicola Worthington.
This software is licensed under The Apache Software License, Version 2.0.
http://www.apache.org/licenses/LICENSE-2.0
| RRD::Simple - Simple interface to create and store data in RRD files |