RRD::Tweak - RRD file manipulation
use RRD::Tweak; my $rrd = RRD::Tweak->new(); $rrd->load_file($filename1); my $rrd_info = $rrd->info(); $rrd->del_ds(5); $rrd->add_ds({name => 'InErrors', type=> 'COUNTER', heartbeat => 755}); $rrd->modify_ds(2, {max => 1000}); $rrd->add_rra({cf => 'MAX', xff => 0.77, steps => 12, rows => 10000}) ; $rrd->modify_rra(6, {rows => 3000}); $rrd->save_file($filename2);
This is a module for manipulating the structure of RRDtool files. It can read a file, alter its DS and RRA structure, and save a new file. It also allows creating new empty RRD files in memory or on the disk.
The file read/write operations are implemented in native C. The module links with librrd, so the librrd library and its header files are required for building the RRD::Tweak module. The module is tested with RRDtool versions 1.3 and 1.4. As the RRD file format is architecture dependent, RRD::Tweak can only read files which are created by RRDtool in the same processor architecture.
my $rrd = RRD::Tweak->new();
Creates a new RRD::Tweak object
$status = $rrd->is_empty();
Returns true value if this RRD::Tweak object contains no data. The object can be empty due to new() or clean() objects.
$status = $rrd->validate();
Validates the contents of an RRD::Tweak object and returns false if the data is inconsistent. In case of failed validation, $rrd->errmsg() returns a human-readable explanation of the failure.
$msg = $rrd->errmsg();
Returns a text string explaining the details if $rrd->validate() failed.
$rrd->load_file($filename);
Reads the RRD file and stores its whole content in the RRD::Tweak object
$rrd->save_file($filename);
Creates a new RRD file from the contents of the RRD::Tweak object. If the file already exists, it's truncated and overwritten.
$rrd->clean();
The method empties the RRD::Tweak object to what it was right after new().
$rrd->create({step => 300, start => time(), ds => [{name => 'InOctets', type=> 'COUNTER', heartbeat => 600}, {name => 'OutOctets', type => 'COUNTER', heartbeat => 600}, {name => 'Load', type => 'GAUGE', heartbeat => 800, min => 0, max => 255}], rra => [{cf => 'AVERAGE', xff => 0.5, steps => 1, rows => 2016}, {cf => 'AVERAGE', xff => 0.25, steps => 12, rows => 768}, {cf => 'MAX', xff => 0.25, steps => 12, rows => 768}]});
The method initializes the RRD::Tweak object with new RRD data as specified by the arguments. The arguments are presented in a hash reference with the following keys and values: step, defining the minumum RRA resolution (default is 300 seconds); start in seconds from epoch (default is "time() - 10"); ds pointing to an array that defines the datasources; rra pointing to an array with RRA definitions.
step
start
ds
rra
start and lastupdate are synonyms.
lastupdate
Each datasource definition is a hash with the following arguments: name, type, heartbeat, min (default: "nan"), max (default: "nan"). The COMPUTE datasource type is currently not supported.
name
type
heartbeat
min
max
Each RRA definition is a hash with arguments: cf defines the consolidation function; steps defines how many minimal steps are aggregated by this RRA; rows defines the size of the RRA.
cf
steps
rows
For AVERAGE, MIN, MAX, and LAST consolidation functions, xff is required.
xff
The a subset of the following attributes is required for each RRA that is related to the Holt-Winters Forecasting: hw_alpha, hw_beta, dependent_rra_idx, dependent_rra_idx, seasonal_gamma, seasonal_smooth_idx, delta_pos, delta_neg, window_len, failure_threshold, dependent_rra_idx. Also smoothing_window is supported for RRD files of version 4.
hw_alpha
hw_beta
dependent_rra_idx
seasonal_gamma
seasonal_smooth_idx
delta_pos
delta_neg
window_len
failure_threshold
smoothing_window
See also rrdcreate manual page of RRDTool for more details.
$rrd->add_ds({name => 'InOctets', type=> 'COUNTER', heartbeat => 600});
The method takes a hash reference as an argument and extends the RRD::Tweak object by adding a new datasource. The new datasource is appended to the array of other datasources. The name should be unique, otherwise the method croaks. The hash keys and values are the same as the DS attributes in create() method.
add_ds() should only be called on an RRD::Tweak object with some data in it. The data can be initialized by create() or load_file().
$rrd->del_ds($ds_index);
The method removes a datasource from a given index. The indexing starts from 0.
$rrd->modify_ds($ds_index, {heartbeat => 700});
The method takes the DS index and a hash reference with DS parameters that need to be modified. All DS parameters described for the create() method are supported.
$rrd->add_rra({cf => 'AVERAGE', xff => 0.25, steps => 12, rows => 768});
The method takes a hash reference as an argument and extends the RRD::Tweak object by adding a new round-robin array. The new RRA is appended to the list of other RRA's. The hash keys and values are the same as the RRA attributes in create() method. If an RRA with the same cf and steps already exists in the RRD::Tweak object, the method croaks with an error.
add_rra() should only be called on an RRD::Tweak object with some data in it. The data can be initialized by create() or load_file().
$rrd->del_rra($rra_index);
The method removes a round-robin array from a given index. The indexing starts from 0.
$rrd->modify_rra($rra_index, {xff => 0.40});
The method takes the RRA index and a hash reference with RRA parameters that need to be modified. The following parameters are supported:
Modifying of XFF does not change any data in the array, and only affects future updates.
If the number of rows is increasing, the existing data stays intact, and the new data elements which fall into the extended time range are set to NaN.
If the number of rows is decreasing, the oldest data elements are discarded.
my $result = $rrd->info();
The method returns a hash reference with all available information as described for the create() method. It always returns a "lastupdate" value in the returned attributes.
my $hw_status = $rrd->has_hwpredict();
The method returns true if any of Holt-Winters RRA exist in the RRD file.
$rrd->ds_descr($ds_index);
The method returns the DS description string as described in rrdcreate manual page (e.g. "DS:InOctets:COUNTER:700:0:U").
$rrd->rra_descr($rra_index);
The method returns a string description of a round-robin array, as specified in rrdcreate manual page (e.g. "RRA:AVERAGE:0.25:12:365").
The returned string for Holt-Winters prediction RRA delivers only partial information.
Stanislav Sinyagin, <ssinyagin at k-open.com>
<ssinyagin at k-open.com>
This development has been sponsored by Nexellent AG and UPC Cablecom AG, Switzerland.
Copyright 2012 Stanislav Sinyagin.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; version 2 dated June, 1991 or at your option any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
A copy of the GNU General Public License is available in the source tree; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
To install RRD::Tweak, copy and paste the appropriate command in to your terminal.
cpanm
cpanm RRD::Tweak
CPAN shell
perl -MCPAN -e shell install RRD::Tweak
For more information on module installation, please visit the detailed CPAN module installation guide.