RRD::Simple(3pm)

1RRD::Simple(3)        User Contributed Perl Documentation       RRD::Simple(3)
2
3
4

NAME

6       RRD::Simple - Simple interface to create and store data in RRD files
7

SYNOPSIS

9        use strict;
10        use RRD::Simple ();
11
12        # Create an interface object
13        my $rrd = RRD::Simple->new( file => "myfile.rrd" );
14
15        # Create a new RRD file with 3 data sources called
16        # bytesIn, bytesOut and faultsPerSec.
17        $rrd->create(
18                    bytesIn => "GAUGE",
19                    bytesOut => "GAUGE",
20                    faultsPerSec => "COUNTER"
21                );
22
23        # Put some arbitary data values in the RRD file for same
24        # 3 data sources called bytesIn, bytesOut and faultsPerSec.
25        $rrd->update(
26                    bytesIn => 10039,
27                    bytesOut => 389,
28                    faultsPerSec => 0.4
29                );
30
31        # Generate graphs:
32        # /var/tmp/myfile-daily.png, /var/tmp/myfile-weekly.png
33        # /var/tmp/myfile-monthly.png, /var/tmp/myfile-annual.png
34        my %rtn = $rrd->graph(
35                    destination => "/var/tmp",
36                    title => "Network Interface eth0",
37                    vertical_label => "Bytes/Faults",
38                    interlaced => ""
39                );
40        printf("Created %s\n",join(", ",map { $rtn{$_}->[0] } keys %rtn));
41
42        # Return information about an RRD file
43        my $info = $rrd->info;
44        require Data::Dumper;
45        print Data::Dumper::Dumper($info);
46
47        # Get unixtime of when RRD file was last updated
48        my $lastUpdated = $rrd->last;
49        print "myfile.rrd was last updated at " .
50              scalar(localtime($lastUpdated)) . "\n";
51
52        # Get list of data source names from an RRD file
53        my @dsnames = $rrd->sources;
54        print "Available data sources: " . join(", ", @dsnames) . "\n";
55
56        # And for the ultimately lazy, you could create and update
57        # an RRD in one go using a one-liner like this:
58        perl -MRRD::Simple=:all -e"update(@ARGV)" myfile.rrd bytesIn 99999
59

DESCRIPTION

61       RRD::Simple provides a simple interface to RRDTool's RRDs module.  This
62       module does not currently offer a "fetch" method that is available in
63       the RRDs module.
64
65       It does however create RRD files with a sensible set of default RRA
66       (Round Robin Archive) definitions, and can dynamically add new data
67       source names to an existing RRD file.
68
69       This module is ideal for quick and simple storage of data within an RRD
70       file if you do not need to, nor want to, bother defining custom RRA
71       definitions.
72

METHODS

74       new
75
76        my $rrd = RRD::Simple->new(
77                file => "myfile.rrd",
78                rrdtool => "/usr/local/rrdtool-1.2.11/bin/rrdtool",
79                cf => [ qw(AVERAGE MAX) ],
80                default_dstype => "GAUGE",
81            );
82
83       The "file" parameter is currently optional but will become mandatory in
84       future releases, replacing the optional $rrdfile parameters on subse‐
85       quent methods. This parameter specifies the RRD filename to be used.
86
87       The "rrdtool" parameter is optional. It specifically defines where the
88       "rrdtool" binary can be found. If not specified, the module will search
89       for the "rrdtool" binary in your path, an additional location relative
90       to where the "RRDs" module was loaded from, and in /usr/local/rrdtool*.
91
92       The "rrdtool" binary is only used by the "add_source" method, and only
93       under certain circumstances. The "add_source" method may also be called
94       automatically by the "update" method, if data point values for a previ‐
95       ously undefined data source are provided for insertion.
96
97       The "cf" parameter is optional, but when specified expects an array
98       reference. The "cf" parameter defines which consolidation functions are
99       used in round robin archives (RRAs) when creating new RRD files. Valid
100       values are AVERAGE, MIN, MAX and LAST. The default value is AVERAGE and
101       MAX.
102
103       The "default_dstype" parameter is optional. Specifying the default data
104       source type (DST) through the new() method allows the DST to be
105       localised to the $rrd object instance rather than be global to the
106       RRD::Simple package.  See $RRD::Simple::DEFAULT_DSTYPE.
107
108       create
109
110        $rrd->create($rrdfile, $period,
111                source_name => "TYPE",
112                source_name => "TYPE",
113                source_name => "TYPE"
114            );
115
116       This method will create a new RRD file on disk.
117
118       $rrdfile is optional and will default to using the RRD filename speci‐
119       fied by the "new" constructor method, or "$0.rrd". (Script basename
120       with the file extension of .rrd).
121
122       $period is optional and will default to "year". Valid options are
123       "day", "week", "month", "year", "3years" and "mrtg". Specifying a data
124       retention period value will change how long data will be retained for
125       within the RRD file. The "mrtg" scheme will try and mimic the data
126       retention period used by MRTG v2.13.2 (<http://peo‐
127       ple.ee.ethz.ch/~oetiker/webtools/mrtg/>.
128
129       The "mrtg" data retention period uses a data stepping resolution of 300
130       seconds (5 minutes) and heartbeat of 600 seconds (10 minutes), whereas
131       all the other data retention periods use a data stepping resolution of
132       60 seconds (1 minute) and heartbeat of 120 seconds (2 minutes).
133
134       Each data source name should specify the data source type. Valid data
135       source types (DSTs) are GAUGE, COUNTER, DERIVE and ABSOLUTE. See the
136       section regrading DSTs at <http://oss.oetiker.ch/rrdtool/doc/rrdcre‐
137       ate.en.html> for further information.
138
139       RRD::Simple will croak and die if you try to create an RRD file that
140       already exists.
141
142       update
143
144        $rrd->update($rrdfile, $unixtime,
145                source_name => "VALUE",
146                source_name => "VALUE",
147                source_name => "VALUE"
148            );
149
150       This method will update an RRD file by inserting new data point values
151       in to the RRD file.
152
153       $rrdfile is optional and will default to using the RRD filename speci‐
154       fied by the "new" constructor method, or "$0.rrd". (Script basename
155       with the file extension of .rrd).
156
157       $unixtime is optional and will default to "time()" (the current unix‐
158       time).  Specifying this value will determine the date and time that
159       your data point values will be stored against in the RRD file.
160
161       If you try to update a value for a data source that does not exist, it
162       will automatically be added for you. The data source type will be set
163       to whatever is contained in the $RRD::Simple::DEFAULT_DSTYPE variable.
164       (See the VARIABLES section below).
165
166       If you explicitly do not want this to happen, then you should check
167       that you are only updating pre-existing data source names using the
168       "sources" method.  You can manually add new data sources to an RRD file
169       by using the "add_source" method, which requires you to explicitly set
170       the data source type.
171
172       If you try to update an RRD file that does not exist, it will attept to
173       create the RRD file for you using the same behaviour as described
174       above. A warning message will be displayed indicating that the RRD file
175       is being created for you if have perl warnings turned on.
176
177       last
178
179        my $unixtime = $rrd->last($rrdfile);
180
181       This method returns the last (most recent) data point entry time in the
182       RRD file in UNIX time (seconds since the epoch; Jan 1st 1970). This
183       value should not be confused with the last modified time of the RRD
184       file.
185
186       $rrdfile is optional and will default to using the RRD filename speci‐
187       fied by the "new" constructor method, or "$0.rrd". (Script basename
188       with the file extension of .rrd).
189
190       sources
191
192        my @sources = $rrd->sources($rrdfile);
193
194       This method returns a list of all of the data source names contained
195       within the RRD file.
196
197       $rrdfile is optional and will default to using the RRD filename speci‐
198       fied by the "new" constructor method, or "$0.rrd". (Script basename
199       with the file extension of .rrd).
200
201       add_source
202
203        $rrd->add_source($rrdfile,
204                source_name => "TYPE"
205            );
206
207       You may add a new data source to an existing RRD file using this
208       method. Only one data source name can be added at a time. You must also
209       specify the data source type.
210
211       $rrdfile is optional and will default to using the RRD filename speci‐
212       fied by the "new" constructor method, or "$0.rrd". (Script basename
213       with the file extension of .rrd).
214
215       This method can be called internally by the "update" method to automat‐
216       ically add missing data sources.
217
218       rename_source
219
220        $rrd->rename_source($rrdfile, "old_datasource", "new_datasource");
221
222       You may rename a data source in an existing RRD file using this method.
223
224       $rrdfile is optional and will default to using the RRD filename speci‐
225       fied by the "new" constructor method, or "$0.rrd". (Script basename
226       with the file extension of .rrd).
227
228       graph
229
230        my %rtn = $rrd->graph($rrdfile,
231                destination => "/path/to/write/graph/images",
232                basename => "graph_basename",
233                timestamp => "both", # graph, rrd, both or none
234                sources => [ qw(source_name1 source_name2 source_name3) ],
235                source_colors => [ qw(ff0000 aa3333 000000) ],
236                source_labels => [ ("My Source 1","My Source Two","Source 3") ],
237                source_drawtypes => [ qw(LINE1 AREA LINE) ],
238                line_thickness => 2,
239                extended_legend => 1,
240                rrd_graph_option => "value",
241                rrd_graph_option => "value",
242                rrd_graph_option => "value"
243            );
244
245       This method will render one or more graph images that show the data in
246       the RRD file.
247
248       The number of image files that are created depends on the retention
249       period of the RRD file. Daily, weekly, monthly, annual and 3year graphs
250       will be created if there is enough data in the RRD file to accomodate
251       them.
252
253       The image filenames will start with either the basename of the RRD
254       file, or whatever is specified by the "basename" parameter. The second
255       part of the filename will be "-daily", "-weekly", "-monthly", "-annual"
256       or "-3year" depending on the period that is being graphed.
257
258       $rrdfile is optional and will default to using the RRD filename speci‐
259       fied by the "new" constructor method, or "$0.rrd". (Script basename
260       with the file extension of .rrd).
261
262       Graph options specific to RRD::Simple are:
263
264       destination
265           The "destination" parameter is optional, and it will default to the
266           same path location as that of the RRD file specified by $rrdfile.
267           Specifying this value will force the resulting graph images to be
268           written to this path location. (The specified path must be a valid
269           directory with the sufficient permissions to write the graph
270           images).
271
272       basename
273           The "basename" parameter is optional. This parameter specifies the
274           basename of the graph image files that will be created. If not
275           specified, it will default to the name of the RRD file. For
276           exmaple, if you specify a basename name of "mygraph", the following
277           graph image files will be created in the "destination" directory:
278
279            mygraph-daily.png
280            mygraph-weekly.png
281            mygraph-monthly.png
282            mygraph-annual.png
283
284           The default file format is "png", but this can be explicitly speci‐
285           fied using the standard RRDs options. (See below).
286
287       timestamp
288            my %rtn = $rrd->graph($rrdfile,
289                    timestamp => "graph", # graph, rrd, both or none
290                );
291
292           The "timestamp" parameter is optional, but will default to "graph".
293           This parameter specifies which "last updated" timestamps should be
294           added to the bottom right hand corner of the graph.
295
296           Valid values are: "graph" - the timestamp of when the graph was
297           last rendered will be used, "rrd" - the timestamp of when the RRD
298           file was last updated will be used, "both" - both the timestamps of
299           when the graph and RRD file were last updated will be used, "none"
300           - no timestamp will be used.
301
302       sources
303           The "sources" parameter is optional. This parameter should be an
304           array of data source names that you want to be plotted. All data
305           sources will be plotted by default.
306
307       source_colors
308            my %rtn = $rrd->graph($rrdfile,
309                    source_colors => [ qw(ff3333 ff00ff ffcc99) ],
310                );
311
312            %rtn = $rrd->graph($rrdfile,
313                    source_colors => { source_name1 => "ff3333",
314                                       source_name2 => "ff00ff",
315                                       source_name3 => "ffcc99", },
316                );
317
318           The "source_colors" parameter is optional. This parameter should be
319           an array or hash of hex triplet colors to be used for the plotted
320           data source lines. A selection of vivid primary colors will be set
321           by default.
322
323       source_labels
324            my %rtn = $rrd->graph($rrdfile,
325                    sources => [ qw(source_name1 source_name2 source_name3) ],
326                    source_labels => [ ("My Source 1","My Source Two","Source 3") ],
327                );
328
329            %rtn = $rrd->graph($rrdfile,
330                    source_labels => { source_name1 => "My Source 1",
331                                       source_name2 => "My Source Two",
332                                       source_name3 => "Source 3", },
333                );
334
335           The "source_labels" parameter is optional. The parameter should be
336           an array or hash of labels to be placed in the legend/key under‐
337           neath the graph. An array can only be used if the "sources" parame‐
338           ter is also specified, since the label index position in the array
339           will directly relate to the data source index position in the
340           "sources" array.
341
342           The data source names will be used in the legend/key by default if
343           no "source_labels" parameter is specified.
344
345       source_drawtypes
346            my %rtn = $rrd->graph($rrdfile,
347                    source_drawtypes => [ qw(LINE1 AREA LINE) ],
348                );
349
350            %rtn = $rrd->graph($rrdfile,
351                    source_colors => { source_name1 => "LINE1",
352                                       source_name2 => "AREA",
353                                       source_name3 => "LINE", },
354                );
355
356            %rtn = $rrd->graph($rrdfile,
357                    sources => [ qw(system user iowait idle) ]
358                    source_colors => [ qw(AREA STACK STACK STACK) ],
359                );
360
361           The "source_drawtypes" parameter is optional. This parameter should
362           be an array or hash of drawing/plotting types to be used for the
363           plotted data source lines. By default all data sources are drawn as
364           lines (LINE), but data sources may also be drawn as filled areas
365           (AREA). Valid values are, LINE, LINEn (where n represents the
366           thickness of the line in pixels), AREA or STACK.
367
368       line_thickness
369           Specifies the thickness of the data lines drawn on the graphs for
370           any data sources that have not had a specific line thinkness
371           already specified using the "source_drawtypes" option.  Valid val‐
372           ues are 1, 2 and 3 (pixels).
373
374       extended_legend
375           If set to boolean true, prints more detailed information in the
376           graph legend by adding the minimum, maximum and last values
377           recorded on the graph for each data source.
378
379       Common RRD graph options are:
380
381       title
382           A horizontal string at the top of the graph.
383
384       vertical_label
385           A vertically placed string at the left hand side of the graph.
386
387       width
388           The width of the canvas (the part of the graph with the actual data
389           and such). This defaults to 400 pixels.
390
391       height
392           The height of the canvas (the part of the graph with the actual
393           data and such). This defaults to 100 pixels.
394
395       For examples on how to best use the "graph" method, refer to the exam‐
396       ple scripts that are bundled with this module in the examples/ direc‐
397       tory. A complete list of parameters can be found at <http://peo‐
398       ple.ee.ethz.ch/~oetiker/webtools/rrdtool/doc/index.en.html>.
399
400       retention_period
401
402        my $seconds = $rrd->retention_period($rrdfile);
403
404       This method will return the maximum period of time (in seconds) that
405       the RRD file will store data for.
406
407       $rrdfile is optional and will default to using the RRD filename speci‐
408       fied by the "new" constructor method, or "$0.rrd". (Script basename
409       with the file extension of .rrd).
410
411       info
412
413        my $info = $rrd->info($rrdfile);
414
415       This method will return a complex data structure containing details
416       about the RRD file, including RRA and data source information.
417
418       $rrdfile is optional and will default to using the RRD filename speci‐
419       fied by the "new" constructor method, or "$0.rrd". (Script basename
420       with the file extension of .rrd).
421
422       heartbeat
423
424        my $heartbeat = $rrd->heartbeat($rrdfile, "dsname");
425        my @rtn = $rrd->heartbeat($rrdfile, "dsname", 600);
426
427       This method will return the current heartbeat of a data source, or set
428       a new heartbeat of a data source.
429
430       $rrdfile is optional and will default to using the RRD filename speci‐
431       fied by the "new" constructor method, or "$0.rrd". (Script basename
432       with the file extension of .rrd).
433

VARIABLES

435       $RRD::Simple::DEBUG
436
437       Debug and trace information will be printed to STDERR if this variable
438       is set to 1 (boolean true).
439
440       This variable will take its value from $ENV{DEBUG}, if it exists, oth‐
441       erwise it will default to 0 (boolean false). This is a normal package
442       variable and may be safely modified at any time.
443
444       $RRD::Simple::DEFAULT_DSTYPE
445
446       This variable is used as the default data source type when creating or
447       adding new data sources, when no other data source type is explicitly
448       specified.
449
450       This variable will take its value from $ENV{DEFAULT_DSTYPE}, if it
451       exists, otherwise it will default to "GAUGE". This is a normal package
452       variable and may be safely modified at any time.
453

EXPORTS

455       You can export the following functions if you do not wish to go through
456       the extra effort of using the OO interface:
457
458        create
459        update
460        last_update (synonym for the last() method)
461        sources
462        add_source
463        rename_source
464        graph
465        retention_period
466        info
467        heartbeat
468
469       The tag "all" is available to easily export everything:
470
471        use RRD::Simple qw(:all);
472
473       See the examples and unit tests in this distribution for more details.
474

VERSION

481       $Id: Simple.pm 988 2007-03-04 23:51:22Z nicolaw $
482

AUTHOR

484       Nicola Worthington <nicolaw@cpan.org>
485
486       <http://perlgirl.org.uk>
487
488       If you like this software, why not show your appreciation by sending
489       the author something nice from her Amazon wishlist?  ( http://www.ama‐
490       zon.co.uk/gp/registry/1VZXC59ESWYK0?sort=priority )
491

COPYRIGHT

493       Copyright 2005,2006,2007 Nicola Worthington.
494
495       This software is licensed under The Apache Software License, Version
496       2.0.
497
498       <http://www.apache.org/licenses/LICENSE-2.0>
499
500
501
502perl v5.8.8                       2007-03-22                    RRD::Simple(3)