RRD-Simple-1.44/ 0000777 0000764 0000764 00000000000 10746154056 013216 5 ustar nicolaw nicolaw RRD-Simple-1.44/LICENSE 0000444 0000764 0000764 00000026136 10746154056 014225 0 ustar nicolaw nicolaw
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright [yyyy] [name of copyright owner]
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
RRD-Simple-1.44/README 0000444 0000764 0000764 00000047723 10746154056 014105 0 ustar nicolaw nicolaw 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
(.
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
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, LINE*n* (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
.
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, ,
examples/*.pl,
,
VERSION
$Id: Simple.pm 1100 2008-01-24 17:39:35Z nicolaw $
AUTHOR
Nicola Worthington
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
Copyright 2005,2006,2007,2008 Nicola Worthington.
This software is licensed under The Apache Software License, Version
2.0.
RRD-Simple-1.44/Changes 0000444 0000764 0000764 00000043472 10746154056 014515 0 ustar nicolaw nicolaw Version 1.44 - 24th Janurary 2008
+ Fixed some small typos in the POD.
+ Added "on_missing_ds" parameter to the new()
constructor method to detemine what action should
be taken when the user tries to update or insert
new data point values in an RRD for a data source
name that does not exist.
+ Added "tmpdir" parameter to the new() constructor
method to force any temporary files to be created
in the specified directory. This is only used in
the add_source() / _modify_source code.
+ Added a number of additional TRACE() statements
in the code to aid debugging with the DEBUG=1
environment variable.
+ Changed graph() so that there is no longer an
AVERAGE VDEF vname generated for each data source
by default. See the updated example on drawing
average lines in RRD::Simple::Examples.
+ Changed graph() method to allow undef or ''
(empty) values to be passed in for the sources
parameter. This is useful if you do not want to
draw and data source values directly on the graph
but instead only want to plot CDEF values. As a
result and requirement of this change, the DEF
statements for each and every data source in the
RRD file are always defined early on in the
commands passed on to RRDs.pm.
+ Added a new example to RRD::Simple::Examples
to show how to generate predictive graphs to
provide basic capacity planning. See
examples/mem_usage-monthly.png for the example
output.
+ Added a new "periods" parameter to the graph()
method to restrict which graphs will be
generated. For example, "weekly, month" could
be specified to only generate those two graphs.
This is useful if you want to use the SHIFT
command to produce a capacity planning graph
based on the last 6 months projecting in to the
next 6 months in an annual graphing period.
+ Updated version of rrd.me.uk in the examples
sub-directory of this distribution, inside the
"rrd-server" directory.
Version 1.43 - 5th March 2007
+ Changed Build.PL to be more paranoid defaulting
to no while using $build->y_n to work around
potential removal of expected method functionality.
+ Added complain.txt.
+ Added instructions for installing rrdtool and RRDs
under Debian/Ubuntu, RHEL and Fedora Core to the
INSTALL file.
+ Various fixes and improvements to the POD.
+ Added another example to RRD::Simple::Examples.
+ Fixed typos in existing examples 1 to 5 in
RRD::Simple::Examples.
Version 1.42 - 27th February 2007
+ Increased the spacing on the graph between the
timestamps in the bottom right hand corner and
the legend if the "extended-legend" parameter is
NOT specified.
+ Added the "file" parameter to the new() constructor
method to specify the RRD filename to be used for
by the resulting RRD::Simple object. Eventually
this will replace the (now optional) ability to
pass the RRD filename as the first parameter to
subsequent object methods.
+ Changed the POD to reflect the above changes
to the new() constructor method regarding passing
of the RRD filename at object creation time.
+ Added new unit text for the above changes
to the new() constructor method.
+ Corrected minimum RRD::Simple version for
rrd-server.pl as documented in README.
+ Updated the main POD to include data resolution
information for each of the 6 different data
retention period schemes.
+ Changed to an inside out object. Use the DEBUG
environment variable to debug.
+ Updated and renamed RRD::Simple::Examples from
a .pm file to a .pod file since it contains no
actual code (only documentation).
Version 1.41 - 11th February 2007
+ Added RRD::Simple::Examples POD.
+ Added new requirement of POSIX to Build.PL.
+ Added new timestamp parameter to the graph()
method.
+ Added heartbeat() method and POD and unit
test for it.
+ Documented some parameters to the new()
constructor method that were previously
undocumented.
+ Updated version of examples/data_gathering/*
scripts, as currently used on http://rrd.me.uk
Version 1.40 - 24th August 2006
+ Some small changes to POD.
+ Updated version of examples/data_gathering/*
scripts, as currently used on http://rrd.me.uk
+ Changed RRDs::error calls to RRDs::error().
+ Changed debug warn() calls to carp().
+ Explicitly import fewer symbols from other
modules.
+ Added rename_source() method and associated
POD and unit test.
+ Changed the graph() method to recognise use
of command (GPRINT,PRINT,COMMENT,VRULE,.. etc)
over options and flags, so that they will be
added to the graph definition after the
data sources have been defined.
+ Added new unit tests for new functionality.
t/35average_hrule.t tests and demonstrates
how the changes to the graph() method can be
used.
+ Fixed a bug where an uninitialised variable
could cause unexpected behaviour if you tried
to add a new data source using add_source()
method. This only manifested itself with an
versions of RRDs earlier than 1.2013, and
where the rrdtool binary is not installed or
the path to the rrdtool binary is unknown.
Version 1.39 - 26th June 2006
+ Changed the return value from the graph()
method to be a hash instead of an array, so
that the data inside can be easily identified
as being generated by a specific graph (daily,
weekly, monthly, annual or 3year).
+ Added the min, max and last values plotted in
each graph, and the filename of the image file
written to disk to the graph() method return
value.
+ Added some more checks in unit tests t/23graph.t
and t/21synopsis.t to account for the changed
to the graph() method return value.
+ Updated POD to reflect change in the return
value from the graph() method.
+ Fixed an uninitialised value warning that
occured if the graph() method was passed too
few items in the 'sources' paramater compared
to the number of items passed in the
'source_drawtypes' or 'source_labels'
paramaters.
+ Added client/server server monitoring scripts
in examples/data_gathering.
+ Updated POD for update() method to make it
clearer that updating an RRD file that does not
exist will result it one being automatically
created for you using default values.
Version 1.38 - 15th June 2006
+ Fixed a major bug introduced in v1.37 where
add_source() method appends new data sources
instead of prepends. This would have swapped
historical RRA data with different data source
names if a new source was added during use
of version 1.37.
+ Added examples/loadavg.pl
+ Modified examples/meminfo.pl to create
swap-*.png graphs if /proc/meminfo is
available.
Version 1.37 - 15th June 2006
+ Changed the add_source() method so that new
data sources will be appended to the existing
data sources, instead of prepended as was done
before. This is useful if you are updating
your RRD file directly with RRDs.pm and are
assuming the order of the data source names
in the RRD file.
+ Added ability to use the STACK draw type in
the graph() method. See examples/vmstat.pl and
examples/vmstat-cpu-daily.png an example of
how to use it and what the results can look
like.
+ Added a couple more tests to t/26add_source.t
+ $RRD::Simple::DEFAULT_DSTYPE and
$RRD::Simple::DEBUG will now no longer be
reset/overwritten when loading RRD::Simple,
if the values were already defined. The
existing documented logic will still work
as expected, assuming you do not explicitly
set the variable before loading RRD::Simple.
This behaviour is intented to reduce confusion.
+ Added examples/processes.pl
Version 1.36 - 13th June 2006
+ Changed unit tests to skip tests if they find
that RRDs is not actually installed. RRDs is
clearly marked as a prerequisite for RRD::Simple
to work. The module should not even build if
RRDs is not installed. Submitting failed CPAN
tester reports because you failed to install
the prerequisite modules is stupid.
+ Added some brief instructions to INSTALL for
installing RRDtool and RRDs.
+ Added a README in the examples directory to
help briefly describe what each script does.
+ Changed the following three modules used in
unit tests to be reccomended instead of required
for building, since the unit tests will quite
happily skip if they are not installed:
'Test::Pod' => 1.20,
'Test::Pod::Coverage' => 1.06,
'Test::Deep' => 0.093,
+ Build.PL now makes an extra special point of
warning about missing RRDs.pm, stating where a
copy of RRDtool can be downloaded from, and
that more details can be found in INSTALL.
+ Corrected a typo in examples/vmstat.pl in the
command line for vmstat.
Version 1.35 - 10th June 2006
+ Added some more example images and scripts in
the examples/ directory, and finished off
examples/iostat.pl and examples/df.pl.
+ Added the "extended_legend" option to the graph()
method, to include recent values to be printed
next to the labels.
+ Changed the order of the default set of colours
used to draw data sources in the graph() method,
and altered the second and third shade cycles to
make the colours slights more easily
distingustable from one another.
Version 1.34 - 1st June 2006
+ Fixed a small gotcha whereby _ and - characters
were not allowed in the "basename" paramater
passed to the graph() method.
+ Fixed a typo in the code setting $VERSION.
Version 1.33 - 1st May 2006
+ Changed the default scheme from being 'year' to
'mrtg' instead.
+ Added the "source_drawtypes" option to the graph
method, so that AREA as well as LINE types can
be plotted.
+ Renamed the t/*.t unit test files and did a little
bit of refactoring of them. It's planned to
improve upon them in the future.
Version 1.32 - 8th February 2006
+ No longer set alt-autoscale and alt-y-grid to
on by default when creating graphs.
+ Changed the graph() method to default the end
time for the graph to the last time the RRD
was updated, instead of the current time.
+ Changed the default RRAs that are created in
RRD files to be only AVERAGE and MAX. This is to
reduce the file size and update times. To create
RRD files with MIN and LAST CFs you can still use
the "cf" parameter in the new() constructor method.
+ Changed the retention schemes to be more uniform
and added an "mrtg" scheme that mimics the MRTG
retention priod.
+ Updated unit tests to cope with code changes.
Version 1.31 - 19th January 2006
+ Fixed POD unit tests to run the right tests
+ Added more unit tests.
+ Added retention_period() to exports and documented
in the POD
+ Bug fix whereby the add_source() wasn't finding
the best heartbeat (it was returning a source
name in some internal code instead of the correct
integer value).
+ Added functionality for the graph() method to check
what RRA CFs are available before blindly graphing
the AVERAGE CF type. It will select best of the CFs
available, in order of preference, AVERAGE, MAX,
MIN, LAST.
+ Added (undocumented) "cf" parameter inside the
new() constructor method to specify which CFs to use
when creating RRAs in a new RRD file. This may be
documented later if it's considered useful, and if
the parameter name is correct (ie, shouldn't be
named something else), or implemented in another way.
+ Fixed a bug which (until this release) would not
and should not have been noticed since it only
effected the passing of default values to the
RRD::Simple $self object when used with indirect
method calls requiring the new "cf" paramater.
Version 1.30 - 15th January 2006
+ Removed notice about add_source() not working with
latest versions of RRD from the POD.
+ Added Test::Pod and Test::Pod::Coverage unit tests
+ The graph() method now allows arrays to be passed
as key value options, thus allowing many --colour
values to be set
+ Added the "source_colors" parameter to the graph()
method to specify the plotted data source line colours
+ Added the "source_labels" parameter to the graph()
method to specify data source labels in the legend/key
+ Changed the add_source() method to try and use
the RRDs module for all the needed rrdtool
functionality, instead of having to spawn an external
copy of the rrdtool binary. A patch submitted to
Tobi on 2006/01/08 which should be available in the
1.2.13 release of rrdtool will allow RRDs::dump to
dump to a filename instead of STDOUT, this removing
the need for RRD::Simple to use the rrdtool binary
at all.
+ Tweaked POD a little
+ Fixed some typos in the code where "3year" and "3years"
were being mixed up. They have all been changed to be
"3years" now, as per the POD.
+ Added the retention_period() method to return (in
seconds) how long the RRD will store data for.
+ The graph() method will now only generate graphs which
the RRD file has enough data for. (ie, a 1 week long
RRD file will not try and generate a 3 year graph etc)
+ Fixed a bug whereby the create() method and the graph()
method were both getting the same values back from the
_seconds_in() function, which should not be the case.
This was resulting in blocky graphs because there was
not enough margin between RRA boundies to ensure that
each graph was getting the highest resolution data that
you would expect. Also, _seconds_in() was returning
slightly too high values, which indirectly caused the
X asis labels to overlap eachother in some instances.
Version 1.29 - 6th January 2006
+ Improved makefile version extraction.
+ Changed license to Apache 2.0
http://www.apache.org/licenses/LICENSE-2.0
+ Changed escaping on date in graph() to only happen
with RRDs version 1.2 or greater (escaping should not
be used with version 1.0)
+ Changed how the last values are pulled from the RRA
in the last_values() method so it's more reliable
now.
+ Fixed add_source() to work with rrdtool 1.2x and RRD
version 0003 files.
+ Added /usr/local/rrdtool*/bin/ to the search path
when looking for the rrdtool binary.
+ Tweaked Makefile.PL
Version 1.25 - 28th December 2005
+ Added Changes file.
+ Changed cluck warnings to only be output when perl
warnings are enabled ($^W is set true).
+ t/04lazy_create_by_update.t
t/07correct_spelling.t
-- Disabled warnings being output for some unit tests
so as not to alarm people. (The warnings are
intentional when $^W is true, so it is deliberately
set to false for those tests).
+ Modified Makefile.PL to send anonymous information to
http://perlgirl.org.uk/lib/usage.cgi if the user
agrees. This is so I can track which of my modules
are most heavily used and on what platforms, so I can
concentrate on maintaning the most popular ones in
my limited spare time.
Version 1.24 - 26th December 2005
+ Added explicit specification of a data retention
period (internally to RRD::Simple called a scheme).
+ Added checking of RRD file versions before
attempting to add a new data source to an existing
RRD file. add_source() can only be used on RRD
version 001 files at the moment (rrdtool version
1.0.x). Unit tests have been updated to take this
in to account and skip if necessary.
+ Tidied and improved some of the error messages that
are returned if the addition of a new data source
to an existing RRD file fails.
+ Fixed escaping of the time date stamp that is added
to the graphs so that it is compatible with rrdtool
version 1.2.x.
+ Altered parsing of arguments to the graph() method
so that _ characters are converted to - characters
before passing to the RRDs module. This negated the
need to quote a number or arguments that are passed
in to the graph() method.
+ Added some more comments in the code.
+ Added some more POD.
Version 1.21 - 14th December 2005
+ Added examples/ApacheAccessLogActivity.pl
-- Example script to import apache access log
files in to a simple RRD file for graphing
+ Fixed a bug in the update() method to allow explicit
specification of data insertion time. Previously if no
RRD file was specified, the explicitly specified
insertion time would have incorrectly been used as the
RRD filename.
+ Added an experimental last_values() method to return
the last values stored in the LAST CF RRA. This is not
currently documented because it does not function as
you would logically expect.
+ Added t/09last_value.t
-- This test is essentially skipped because the output
is not as you might expect. It will be enabled once
the last_values() method is working better.
+ Added the 'basename' argument to the graph() method.
+ Added the 'sources' argument to the graph() method.
+ Fixed a few minor typos in warning messages.
+ Added more POD.
+ Improved unit tests.
RRD-Simple-1.44/TODO 0000444 0000764 0000764 00000000072 10746154056 013677 0 ustar nicolaw nicolaw + Add a delete_source() method.
+ Add a fetch() method.
RRD-Simple-1.44/examples/ 0000777 0000764 0000764 00000000000 10746154056 015034 5 ustar nicolaw nicolaw RRD-Simple-1.44/examples/mem_usage-monthly.png 0000444 0000764 0000764 00000053554 10746154056 021202 0 ustar nicolaw nicolaw PNG
IHDR Dr ItEXtSoftware RRDtool, Tobias Oetiker , http://tobi.oetiker.ch\a IDATx} Tű}_}Eq 5[B\1A4Ĩq7K!H
J\pD 彼տ=LO߳L͝uէܬYH沁zrii__jjjj *_BW
duҢ6&&8!g}}66u6666Ф6 ޤzvՃPPPȾ
(+\m@m@m@m c6+=\9T)g:IӲ?>>RPa r}W#'Z
⑆rjjjNO?4-Y^~ȱZA\A<0FFS]m4}t-ϙ3'rVW4FdG6mm[guhV\.YwD[:^E\zno=,WRZ#|ji??S,sym
57
M|tIyYj~:pkYKFѴWFO~9=Okwti|NvmDsM6+n[#*]. mT]־ d\շo_K,=zr zUo>]{ή_*>}~_zrovݻ7͛Gzr:fbI4m93
f_=馛~gtil@k6
jӖ.]ZO~Bx`9dۥP/\
s<]wmVg---=1(6]w|>_^uWp
},_'o{ۗ_Km|kyc뎺P>ɾgAkAiџnl3X\o'҈#C
ď9:蠃?{Ygeu_um9^h{M'|2O^{Eg}vY>+#3'4ĕo}cجq;M}qǴxb;2dH.Ok?aZKÎfpy4:-ZD}TlUɓ{V\^Y+2bqo8! =3fXOW\k՚VJ+Dwuղ_UW]T|i|$^xZqysz6}\O\i+~oLpa^ [6u_n|ⲅB'i)/fLXG}45f+ $Ö$v壮AeXO\]2<(19K\k@~7KK7
mt~h346M.qk~D0../^7=~>WF?ݏ3m\:cU+ɾ,Opﺓ8Ώn^
Rģ n5J1YM4ı6:O\THM0n7GϜ9ӂ9+>0
ti2.+&\-³U.AX!
?|8:7*MkTqK}k=7._?t˺8o1Ώs:Bv9OA++¨O;ꨣhС84{lk68&c#-i~UF^Oxc3=#R㬟a\Q~Z#_.?zIzoF;
ƍ8P6;, '`s8?.}Z7OV| F]5X/0 ~C۫W/l]ڸkl9rzGx}햋)VX?|ާNj'Xƣ l?#GRn,9m?s}+