.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
. if \nF \{
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "RRD::Simple 3pm"
.TH RRD::Simple 3pm "2016-09-10" "perl v5.22.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
RRD::Simple \- Simple interface to create and store data in RRD files
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& 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\en",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)) . "\en";
\&
\& # Get list of data source names from an RRD file
\& my @dsnames = $rrd\->sources;
\& print "Available data sources: " . join(", ", @dsnames) . "\en";
\&
\& # 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
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
RRD::Simple provides a simple interface to RRDTool's RRDs module.
This module does not currently offer a \f(CW\*(C`fetch\*(C'\fR method that is
available in the RRDs module.
.PP
It does however create \s-1RRD\s0 files with a sensible set of default \s-1RRA
\&\s0(Round Robin Archive) definitions, and can dynamically add new
data source names to an existing \s-1RRD\s0 file.
.PP
This module is ideal for quick and simple storage of data within an
\&\s-1RRD\s0 file if you do not need to, nor want to, bother defining custom
\&\s-1RRA\s0 definitions.
.SH "METHODS"
.IX Header "METHODS"
.SS "new"
.IX Subsection "new"
.Vb 8
\& 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",
\& );
.Ve
.PP
The \f(CW\*(C`file\*(C'\fR parameter is currently optional but will become mandatory in
future releases, replacing the optional \f(CW$rrdfile\fR parameters on subsequent
methods. This parameter specifies the \s-1RRD\s0 filename to be used.
.PP
The \f(CW\*(C`rrdtool\*(C'\fR parameter is optional. It specifically defines where the
\&\f(CW\*(C`rrdtool\*(C'\fR binary can be found. If not specified, the module will search for
the \f(CW\*(C`rrdtool\*(C'\fR binary in your path, an additional location relative to where
the \f(CW\*(C`RRDs\*(C'\fR module was loaded from, and in /usr/local/rrdtool*.
.PP
The \f(CW\*(C`tmpdir\*(C'\fR parameter is option and is only used what automatically adding
a new data source to an existing \s-1RRD\s0 file. By default any temporary files
will be placed in your default system temp directory (typically /tmp on Linux,
or whatever your \s-1TMPDIR\s0 environment variable is set to). This parameter can
be used for force any temporary files to be created in a specific directory.
.PP
The \f(CW\*(C`rrdtool\*(C'\fR binary is only used by the \f(CW\*(C`add_source\*(C'\fR method, and only
under certain circumstances. The \f(CW\*(C`add_source\*(C'\fR method may also be called
automatically by the \f(CW\*(C`update\*(C'\fR method, if data point values for a previously
undefined data source are provided for insertion.
.PP
The \f(CW\*(C`cf\*(C'\fR parameter is optional, but when specified expects an array
reference. The \f(CW\*(C`cf\*(C'\fR parameter defines which consolidation functions are
used in round robin archives (RRAs) when creating new \s-1RRD\s0 files. Valid
values are \s-1AVERAGE, MIN, MAX\s0 and \s-1LAST.\s0 The default value is \s-1AVERAGE\s0 and
\&\s-1MAX.\s0
.PP
The \f(CW\*(C`default_dstype\*(C'\fR parameter is optional. Specifying the default data
source type (\s-1DST\s0) through the \fInew()\fR method allows the \s-1DST\s0 to be localised
to the \f(CW$rrd\fR object instance rather than be global to the RRD::Simple package.
See \f(CW$RRD::Simple::DEFAULT_DSTYPE\fR.
.PP
The \f(CW\*(C`on_missing_ds\*(C'\fR parameter is optional and will default to \*(L"add\*(R" 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 \s-1RRD\s0 file. Valid values are \*(L"add\*(R", \*(L"ignore\*(R" and \*(L"die\*(R".
.SS "create"
.IX Subsection "create"
.Vb 5
\& $rrd\->create($rrdfile, $period,
\& source_name => "TYPE",
\& source_name => "TYPE",
\& source_name => "TYPE"
\& );
.Ve
.PP
This method will create a new \s-1RRD\s0 file on disk.
.PP
\&\f(CW$rrdfile\fR is optional and will default to using the \s-1RRD\s0 filename specified
by the \f(CW\*(C`new\*(C'\fR constructor method, or \f(CW\*(C`$0.rrd\*(C'\fR. (Script basename with the file
extension of .rrd).
.PP
\&\f(CW$period\fR is optional and will default to \f(CW\*(C`year\*(C'\fR. Valid options are \f(CW\*(C`hour\*(C'\fR,
\&\f(CW\*(C`6hour\*(C'\fR/\f(CW\*(C`quarterday\*(C'\fR, \f(CW\*(C`12hour\*(C'\fR/\f(CW\*(C`halfday\*(C'\fR, \f(CW\*(C`day\*(C'\fR, \f(CW\*(C`week\*(C'\fR, \f(CW\*(C`month\*(C'\fR,
\&\f(CW\*(C`year\*(C'\fR, \f(CW\*(C`3years\*(C'\fR and \f(CW\*(C`mrtg\*(C'\fR. Specifying a data retention period value will
change how long data will be retained for within the \s-1RRD\s0 file. The \f(CW\*(C`mrtg\*(C'\fR
scheme will try and mimic the data retention period used by \s-1MRTG\s0 v2.13.2
(.
.PP
The \f(CW\*(C`mrtg\*(C'\fR 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).
.PP
Each data source name should specify the data source type. Valid data source
types (DSTs) are \s-1GAUGE, COUNTER, DERIVE\s0 and \s-1ABSOLUTE.\s0 See the section
regrading DSTs at
for further information.
.PP
RRD::Simple will croak and die if you try to create an \s-1RRD\s0 file that already
exists.
.SS "update"
.IX Subsection "update"
.Vb 5
\& $rrd\->update($rrdfile, $unixtime,
\& source_name => "VALUE",
\& source_name => "VALUE",
\& source_name => "VALUE"
\& );
.Ve
.PP
This method will update an \s-1RRD\s0 file by inserting new data point values
in to the \s-1RRD\s0 file.
.PP
\&\f(CW$rrdfile\fR is optional and will default to using the \s-1RRD\s0 filename specified
by the \f(CW\*(C`new\*(C'\fR constructor method, or \f(CW\*(C`$0.rrd\*(C'\fR. (Script basename with the file
extension of .rrd).
.PP
\&\f(CW$unixtime\fR is optional and will default to \f(CW\*(C`time()\*(C'\fR (the current unixtime).
Specifying this value will determine the date and time that your data point
values will be stored against in the \s-1RRD\s0 file.
.PP
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 \f(CW$RRD::Simple::DEFAULT_DSTYPE\fR variable. (See the
\&\s-1VARIABLES\s0 section below).
.PP
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 \f(CW\*(C`sources\*(C'\fR method.
You can manually add new data sources to an \s-1RRD\s0 file by using the \f(CW\*(C`add_source\*(C'\fR
method, which requires you to explicitly set the data source type.
.PP
If you try to update an \s-1RRD\s0 file that does not exist, it will attept to create
the \s-1RRD\s0 file for you using the same behaviour as described above. A warning
message will be displayed indicating that the \s-1RRD\s0 file is being created for
you if have perl warnings turned on.
.SS "last"
.IX Subsection "last"
.Vb 1
\& my $unixtime = $rrd\->last($rrdfile);
.Ve
.PP
This method returns the last (most recent) data point entry time in the \s-1RRD\s0
file in \s-1UNIX\s0 time (seconds since the epoch; Jan 1st 1970). This value should
not be confused with the last modified time of the \s-1RRD\s0 file.
.PP
\&\f(CW$rrdfile\fR is optional and will default to using the \s-1RRD\s0 filename specified
by the \f(CW\*(C`new\*(C'\fR constructor method, or \f(CW\*(C`$0.rrd\*(C'\fR. (Script basename with the file
extension of .rrd).
.SS "sources"
.IX Subsection "sources"
.Vb 1
\& my @sources = $rrd\->sources($rrdfile);
.Ve
.PP
This method returns a list of all of the data source names contained within
the \s-1RRD\s0 file.
.PP
\&\f(CW$rrdfile\fR is optional and will default to using the \s-1RRD\s0 filename specified
by the \f(CW\*(C`new\*(C'\fR constructor method, or \f(CW\*(C`$0.rrd\*(C'\fR. (Script basename with the file
extension of .rrd).
.SS "add_source"
.IX Subsection "add_source"
.Vb 3
\& $rrd\->add_source($rrdfile,
\& source_name => "TYPE"
\& );
.Ve
.PP
You may add a new data source to an existing \s-1RRD\s0 file using this method. Only
one data source name can be added at a time. You must also specify the data
source type.
.PP
\&\f(CW$rrdfile\fR is optional and will default to using the \s-1RRD\s0 filename specified
by the \f(CW\*(C`new\*(C'\fR constructor method, or \f(CW\*(C`$0.rrd\*(C'\fR. (Script basename with the file
extension of .rrd).
.PP
This method can be called internally by the \f(CW\*(C`update\*(C'\fR method to automatically
add missing data sources.
.SS "rename_source"
.IX Subsection "rename_source"
.Vb 1
\& $rrd\->rename_source($rrdfile, "old_datasource", "new_datasource");
.Ve
.PP
You may rename a data source in an existing \s-1RRD\s0 file using this method.
.PP
\&\f(CW$rrdfile\fR is optional and will default to using the \s-1RRD\s0 filename specified
by the \f(CW\*(C`new\*(C'\fR constructor method, or \f(CW\*(C`$0.rrd\*(C'\fR. (Script basename with the file
extension of .rrd).
.SS "graph"
.IX Subsection "graph"
.Vb 10
\& 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"
\& );
.Ve
.PP
This method will render one or more graph images that show the data in the
\&\s-1RRD\s0 file.
.PP
The number of image files that are created depends on the retention period
of the \s-1RRD\s0 file. Hourly, 6 hourly, 12 hourly, daily, weekly, monthly, annual
and 3year graphs will be created if there is enough data in the \s-1RRD\s0 file to
accommodate them.
.PP
The image filenames will start with either the basename of the \s-1RRD\s0
file, or whatever is specified by the \f(CW\*(C`basename\*(C'\fR parameter. The second part
of the filename will be \*(L"\-hourly\*(R", \*(L"\-6hourly\*(R", \*(L"\-12hourly\*(R", \*(L"\-daily\*(R",
\&\*(L"\-weekly\*(R", \*(L"\-monthly\*(R", \*(L"\-annual\*(R" or \*(L"\-3year\*(R" depending on the period that
is being graphed.
.PP
\&\f(CW$rrdfile\fR is optional and will default to using the \s-1RRD\s0 filename specified
by the \f(CW\*(C`new\*(C'\fR constructor method, or \f(CW\*(C`$0.rrd\*(C'\fR. (Script basename with the file
extension of .rrd).
.PP
Graph options specific to RRD::Simple are:
.IP "destination" 4
.IX Item "destination"
The \f(CW\*(C`destination\*(C'\fR parameter is optional, and it will default to the same
path location as that of the \s-1RRD\s0 file specified by \f(CW$rrdfile\fR. 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).
.IP "basename" 4
.IX Item "basename"
The \f(CW\*(C`basename\*(C'\fR 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 \s-1RRD\s0 file. For example, if you specify a basename
name of \f(CW\*(C`mygraph\*(C'\fR, the following graph image files will be created in the
\&\f(CW\*(C`destination\*(C'\fR directory:
.Sp
.Vb 4
\& mygraph\-daily.png
\& mygraph\-weekly.png
\& mygraph\-monthly.png
\& mygraph\-annual.png
.Ve
.Sp
The default file format is \f(CW\*(C`png\*(C'\fR, but this can be explicitly specified using
the standard RRDs options. (See below).
.IP "timestamp" 4
.IX Item "timestamp"
.Vb 3
\& my %rtn = $rrd\->graph($rrdfile,
\& timestamp => "graph", # graph, rrd, both or none
\& );
.Ve
.Sp
The \f(CW\*(C`timestamp\*(C'\fR parameter is optional, but will default to \*(L"graph\*(R". This
parameter specifies which \*(L"last updated\*(R" timestamps should be added to the
bottom right hand corner of the graph.
.Sp
Valid values are: \*(L"graph\*(R" \- the timestamp of when the graph was last rendered
will be used, \*(L"rrd\*(R" \- the timestamp of when the \s-1RRD\s0 file was last updated will
be used, \*(L"both\*(R" \- both the timestamps of when the graph and \s-1RRD\s0 file were last
updated will be used, \*(L"none\*(R" \- no timestamp will be used.
.IP "periods" 4
.IX Item "periods"
The \f(CW\*(C`periods\*(C'\fR 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.
.IP "sources" 4
.IX Item "sources"
The \f(CW\*(C`sources\*(C'\fR 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.
.IP "source_colors" 4
.IX Item "source_colors"
.Vb 3
\& 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", },
\& );
.Ve
.Sp
The \f(CW\*(C`source_colors\*(C'\fR 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.
.IP "source_labels" 4
.IX Item "source_labels"
.Vb 4
\& 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", },
\& );
.Ve
.Sp
The \f(CW\*(C`source_labels\*(C'\fR 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 \f(CW\*(C`sources\*(C'\fR parameter is also
specified, since the label index position in the array will directly
relate to the data source index position in the \f(CW\*(C`sources\*(C'\fR array.
.Sp
The data source names will be used in the legend/key by default if no
\&\f(CW\*(C`source_labels\*(C'\fR parameter is specified.
.IP "source_drawtypes" 4
.IX Item "source_drawtypes"
.Vb 3
\& 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) ],
\& );
.Ve
.Sp
The \f(CW\*(C`source_drawtypes\*(C'\fR 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 (\s-1LINE\s0), but data sources
may also be drawn as filled areas (\s-1AREA\s0). Valid values are, \s-1LINE, LINE\s0\fIn\fR
(where \fIn\fR represents the thickness of the line in pixels), \s-1AREA\s0 or \s-1STACK.\s0
.IP "line_thickness" 4
.IX Item "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 \f(CW\*(C`source_drawtypes\*(C'\fR option.
Valid values are 1, 2 and 3 (pixels).
.IP "extended_legend" 4
.IX Item "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.
.PP
Common \s-1RRD\s0 graph options are:
.IP "title" 4
.IX Item "title"
A horizontal string at the top of the graph.
.IP "vertical_label" 4
.IX Item "vertical_label"
A vertically placed string at the left hand side of the graph.
.IP "width" 4
.IX Item "width"
The width of the canvas (the part of the graph with the actual data
and such). This defaults to 400 pixels.
.IP "height" 4
.IX Item "height"
The height of the canvas (the part of the graph with the actual data
and such). This defaults to 100 pixels.
.PP
For examples on how to best use the \f(CW\*(C`graph\*(C'\fR 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
.
.SS "retention_period"
.IX Subsection "retention_period"
.Vb 1
\& my $seconds = $rrd\->retention_period($rrdfile);
.Ve
.PP
This method will return the maximum period of time (in seconds) that the \s-1RRD\s0
file will store data for.
.PP
\&\f(CW$rrdfile\fR is optional and will default to using the \s-1RRD\s0 filename specified
by the \f(CW\*(C`new\*(C'\fR constructor method, or \f(CW\*(C`$0.rrd\*(C'\fR. (Script basename with the file
extension of .rrd).
.SS "info"
.IX Subsection "info"
.Vb 1
\& my $info = $rrd\->info($rrdfile);
.Ve
.PP
This method will return a complex data structure containing details about
the \s-1RRD\s0 file, including \s-1RRA\s0 and data source information.
.PP
\&\f(CW$rrdfile\fR is optional and will default to using the \s-1RRD\s0 filename specified
by the \f(CW\*(C`new\*(C'\fR constructor method, or \f(CW\*(C`$0.rrd\*(C'\fR. (Script basename with the file
extension of .rrd).
.SS "heartbeat"
.IX Subsection "heartbeat"
.Vb 2
\& my $heartbeat = $rrd\->heartbeat($rrdfile, "dsname");
\& my @rtn = $rrd\->heartbeat($rrdfile, "dsname", 600);
.Ve
.PP
This method will return the current heartbeat of a data source, or set a
new heartbeat of a data source.
.PP
\&\f(CW$rrdfile\fR is optional and will default to using the \s-1RRD\s0 filename specified
by the \f(CW\*(C`new\*(C'\fR constructor method, or \f(CW\*(C`$0.rrd\*(C'\fR. (Script basename with the file
extension of .rrd).
.SH "VARIABLES"
.IX Header "VARIABLES"
.ie n .SS "$RRD::Simple::DEBUG"
.el .SS "\f(CW$RRD::Simple::DEBUG\fP"
.IX Subsection "$RRD::Simple::DEBUG"
Debug and trace information will be printed to \s-1STDERR\s0 if this variable
is set to 1 (boolean true).
.PP
This variable will take its value from \f(CW$ENV{DEBUG}\fR, 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.
.ie n .SS "$RRD::Simple::DEFAULT_DSTYPE"
.el .SS "\f(CW$RRD::Simple::DEFAULT_DSTYPE\fP"
.IX Subsection "$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.
.PP
This variable will take its value from \f(CW$ENV{DEFAULT_DSTYPE}\fR, if it
exists, otherwise it will default to \f(CW\*(C`GAUGE\*(C'\fR. This is a normal package
variable and may be safely modified at any time.
.SH "EXPORTS"
.IX Header "EXPORTS"
You can export the following functions if you do not wish to go through
the extra effort of using the \s-1OO\s0 interface:
.PP
.Vb 10
\& create
\& update
\& last_update (synonym for the last() method)
\& sources
\& add_source
\& rename_source
\& graph
\& retention_period
\& info
\& heartbeat
.Ve
.PP
The tag \f(CW\*(C`all\*(C'\fR is available to easily export everything:
.PP
.Vb 1
\& use RRD::Simple qw(:all);
.Ve
.PP
See the examples and unit tests in this distribution for more
details.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
RRD::Simple::Examples, RRDTool::OO, RRDs,
, examples/*.pl,
,
.SH "VERSION"
.IX Header "VERSION"
\&\f(CW$Id:\fR Simple.pm 1100 2008\-01\-24 17:39:35Z nicolaw $
.SH "AUTHOR"
.IX Header "AUTHOR"
Nicola Worthington
.PP
.PP
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 )
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2005,2006,2007,2008 Nicola Worthington.
.PP
This software is licensed under The Apache Software License, Version 2.0.
.PP