Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
RRD::Simple(3)	      User Contributed Perl Documentation	RRD::Simple(3)

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 arbitary 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 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 "-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://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>

perl v5.24.1			  2017-07-08			RRD::Simple(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | VARIABLES | EXPORTS | SEE ALSO | VERSION | AUTHOR | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=RRD::Simple&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help