1NAME
2 RRD::Simple - Simple interface to create and store data in RRD files
3
4SYNOPSIS
5 use strict;
6 use RRD::Simple ();
7
8 # Create an interface object
9 my $rrd = RRD::Simple->new( file => "myfile.rrd" );
10
11 # Create a new RRD file with 3 data sources called
12 # bytesIn, bytesOut and faultsPerSec.
13 $rrd->create(
14 bytesIn => "GAUGE",
15 bytesOut => "GAUGE",
16 faultsPerSec => "COUNTER"
17 );
18
19 # Put some arbitary data values in the RRD file for the same
20 # 3 data sources called bytesIn, bytesOut and faultsPerSec.
21 $rrd->update(
22 bytesIn => 10039,
23 bytesOut => 389,
24 faultsPerSec => 0.4
25 );
26
27 # Generate graphs:
28 # /var/tmp/myfile-daily.png, /var/tmp/myfile-weekly.png
29 # /var/tmp/myfile-monthly.png, /var/tmp/myfile-annual.png
30 my %rtn = $rrd->graph(
31 destination => "/var/tmp",
32 title => "Network Interface eth0",
33 vertical_label => "Bytes/Faults",
34 interlaced => ""
35 );
36 printf("Created %s\n",join(", ",map { $rtn{$_}->[0] } keys %rtn));
37
38 # Return information about an RRD file
39 my $info = $rrd->info;
40 require Data::Dumper;
41 print Data::Dumper::Dumper($info);
42
43 # Get unixtime of when RRD file was last updated
44 my $lastUpdated = $rrd->last;
45 print "myfile.rrd was last updated at " .
46 scalar(localtime($lastUpdated)) . "\n";
47
48 # Get list of data source names from an RRD file
49 my @dsnames = $rrd->sources;
50 print "Available data sources: " . join(", ", @dsnames) . "\n";
51
52 # And for the ultimately lazy, you could create and update
53 # an RRD in one go using a one-liner like this:
54 perl -MRRD::Simple=:all -e"update(@ARGV)" myfile.rrd bytesIn 99999
55
56DESCRIPTION
57 RRD::Simple provides a simple interface to RRDTool's RRDs module. This
58 module does not currently offer a "fetch" method that is available in
59 the RRDs module.
60
61 It does however create RRD files with a sensible set of default RRA
62 (Round Robin Archive) definitions, and can dynamically add new data
63 source names to an existing RRD file.
64
65 This module is ideal for quick and simple storage of data within an RRD
66 file if you do not need to, nor want to, bother defining custom RRA
67 definitions.
68
69METHODS
70 new
71 my $rrd = RRD::Simple->new(
72 file => "myfile.rrd",
73 rrdtool => "/usr/local/rrdtool-1.2.11/bin/rrdtool",
74 tmpdir => "/var/tmp",
75 cf => [ qw(AVERAGE MAX) ],
76 default_dstype => "GAUGE",
77 on_missing_ds => "add",
78 );
79
80 The "file" parameter is currently optional but will become mandatory in
81 future releases, replacing the optional $rrdfile parameters on
82 subsequent methods. This parameter specifies the RRD filename to be
83 used.
84
85 The "rrdtool" parameter is optional. It specifically defines where the
86 "rrdtool" binary can be found. If not specified, the module will search
87 for the "rrdtool" binary in your path, an additional location relative
88 to where the "RRDs" module was loaded from, and in /usr/local/rrdtool*.
89
90 The "tmpdir" parameter is option and is only used what automatically
91 adding a new data source to an existing RRD file. By default any
92 temporary files will be placed in your default system temp directory
93 (typically /tmp on Linux, or whatever your TMPDIR environment variable
94 is set to). This parameter can be used for force any temporary files to
95 be created in a specific directory.
96
97 The "rrdtool" binary is only used by the "add_source" method, and only
98 under certain circumstances. The "add_source" method may also be called
99 automatically by the "update" method, if data point values for a
100 previously undefined data source are provided for insertion.
101
102 The "cf" parameter is optional, but when specified expects an array
103 reference. The "cf" parameter defines which consolidation functions are
104 used in round robin archives (RRAs) when creating new RRD files. Valid
105 values are AVERAGE, MIN, MAX and LAST. The default value is AVERAGE and
106 MAX.
107
108 The "default_dstype" parameter is optional. Specifying the default data
109 source type (DST) through the new() method allows the DST to be
110 localised to the $rrd object instance rather than be global to the
111 RRD::Simple package. See $RRD::Simple::DEFAULT_DSTYPE.
112
113 The "on_missing_ds" parameter is optional and will default to "add" when
114 not defined. This parameter will determine what will happen if you try
115 to insert or update data for a data source name that does not exist in
116 the RRD file. Valid values are "add", "ignore" and "die".
117
118 create
119 $rrd->create($rrdfile, $period,
120 source_name => "TYPE",
121 source_name => "TYPE",
122 source_name => "TYPE"
123 );
124
125 This method will create a new RRD file on disk.
126
127 $rrdfile is optional and will default to using the RRD filename
128 specified by the "new" constructor method, or "$0.rrd". (Script basename
129 with the file extension of .rrd).
130
131 $period is optional and will default to "year". Valid options are
132 "hour", "6hour"/"quarterday", "12hour"/"halfday", "day", "week",
133 "month", "year", "3years" and "mrtg". Specifying a data retention period
134 value will change how long data will be retained for within the RRD
135 file. The "mrtg" scheme will try and mimic the data retention period
136 used by MRTG v2.13.2
137 (<http://people.ee.ethz.ch/~oetiker/webtools/mrtg/>.
138
139 The "mrtg" data retention period uses a data stepping resolution of 300
140 seconds (5 minutes) and heartbeat of 600 seconds (10 minutes), whereas
141 all the other data retention periods use a data stepping resolution of
142 60 seconds (1 minute) and heartbeat of 120 seconds (2 minutes).
143
144 Each data source name should specify the data source type. Valid data
145 source types (DSTs) are GAUGE, COUNTER, DERIVE and ABSOLUTE. See the
146 section regrading DSTs at
147 <http://oss.oetiker.ch/rrdtool/doc/rrdcreate.en.html> for further
148 information.
149
150 RRD::Simple will croak and die if you try to create an RRD file that
151 already exists.
152
153 update
154 $rrd->update($rrdfile, $unixtime,
155 source_name => "VALUE",
156 source_name => "VALUE",
157 source_name => "VALUE"
158 );
159
160 This method will update an RRD file by inserting new data point values
161 in to the RRD file.
162
163 $rrdfile is optional and will default to using the RRD filename
164 specified by the "new" constructor method, or "$0.rrd". (Script basename
165 with the file extension of .rrd).
166
167 $unixtime is optional and will default to "time()" (the current
168 unixtime). Specifying this value will determine the date and time that
169 your data point values will be stored against in the RRD file.
170
171 If you try to update a value for a data source that does not exist, it
172 will automatically be added for you. The data source type will be set to
173 whatever is contained in the $RRD::Simple::DEFAULT_DSTYPE variable. (See
174 the VARIABLES section below).
175
176 If you explicitly do not want this to happen, then you should check that
177 you are only updating pre-existing data source names using the "sources"
178 method. You can manually add new data sources to an RRD file by using
179 the "add_source" method, which requires you to explicitly set the data
180 source type.
181
182 If you try to update an RRD file that does not exist, it will attept to
183 create the RRD file for you using the same behaviour as described above.
184 A warning message will be displayed indicating that the RRD file is
185 being created for you if have perl warnings turned on.
186
187 last
188 my $unixtime = $rrd->last($rrdfile);
189
190 This method returns the last (most recent) data point entry time in the
191 RRD file in UNIX time (seconds since the epoch; Jan 1st 1970). This
192 value should not be confused with the last modified time of the RRD
193 file.
194
195 $rrdfile is optional and will default to using the RRD filename
196 specified by the "new" constructor method, or "$0.rrd". (Script basename
197 with the file extension of .rrd).
198
199 sources
200 my @sources = $rrd->sources($rrdfile);
201
202 This method returns a list of all of the data source names contained
203 within the RRD file.
204
205 $rrdfile is optional and will default to using the RRD filename
206 specified by the "new" constructor method, or "$0.rrd". (Script basename
207 with the file extension of .rrd).
208
209 add_source
210 $rrd->add_source($rrdfile,
211 source_name => "TYPE"
212 );
213
214 You may add a new data source to an existing RRD file using this method.
215 Only one data source name can be added at a time. You must also specify
216 the data source type.
217
218 $rrdfile is optional and will default to using the RRD filename
219 specified by the "new" constructor method, or "$0.rrd". (Script basename
220 with the file extension of .rrd).
221
222 This method can be called internally by the "update" method to
223 automatically add missing data sources.
224
225 rename_source
226 $rrd->rename_source($rrdfile, "old_datasource", "new_datasource");
227
228 You may rename a data source in an existing RRD file using this method.
229
230 $rrdfile is optional and will default to using the RRD filename
231 specified by the "new" constructor method, or "$0.rrd". (Script basename
232 with the file extension of .rrd).
233
234 graph
235 my %rtn = $rrd->graph($rrdfile,
236 destination => "/path/to/write/graph/images",
237 basename => "graph_basename",
238 timestamp => "both", # graph, rrd, both or none
239 periods => [ qw(week month) ], # omit to generate all graphs
240 sources => [ qw(source_name1 source_name2 source_name3) ],
241 source_colors => [ qw(ff0000 aa3333 000000) ],
242 source_labels => [ ("My Source 1", "My Source Two", "Source 3") ],
243 source_drawtypes => [ qw(LINE1 AREA LINE) ],
244 line_thickness => 2,
245 extended_legend => 1,
246 rrd_graph_option => "value",
247 rrd_graph_option => "value",
248 rrd_graph_option => "value"
249 );
250
251 This method will render one or more graph images that show the data in
252 the RRD file.
253
254 The number of image files that are created depends on the retention
255 period of the RRD file. Hourly, 6 hourly, 12 hourly, daily, weekly,
256 monthly, annual and 3year graphs will be created if there is enough data
257 in the RRD file to accomodate them.
258
259 The image filenames will start with either the basename of the RRD file,
260 or whatever is specified by the "basename" parameter. The second part of
261 the filename will be "-hourly", "-6hourly", "-12hourly", "-daily",
262 "-weekly", "-monthly", "-annual" or "-3year" depending on the period
263 that is being graphed.
264
265 $rrdfile is optional and will default to using the RRD filename
266 specified by the "new" constructor method, or "$0.rrd". (Script basename
267 with the file extension of .rrd).
268
269 Graph options specific to RRD::Simple are:
270
271 destination
272 The "destination" parameter is optional, and it will default to the
273 same path location as that of the RRD file specified by $rrdfile.
274 Specifying this value will force the resulting graph images to be
275 written to this path location. (The specified path must be a valid
276 directory with the sufficient permissions to write the graph
277 images).
278
279 basename
280 The "basename" parameter is optional. This parameter specifies the
281 basename of the graph image files that will be created. If not
282 specified, it will default to the name of the RRD file. For example,
283 if you specify a basename name of "mygraph", the following graph
284 image files will be created in the "destination" directory:
285
286 mygraph-daily.png
287 mygraph-weekly.png
288 mygraph-monthly.png
289 mygraph-annual.png
290
291 The default file format is "png", but this can be explicitly
292 specified using the standard RRDs options. (See below).
293
294 timestamp
295 my %rtn = $rrd->graph($rrdfile,
296 timestamp => "graph", # graph, rrd, both or none
297 );
298
299 The "timestamp" parameter is optional, but will default to "graph".
300 This parameter specifies which "last updated" timestamps should be
301 added to the bottom right hand corner of the graph.
302
303 Valid values are: "graph" - the timestamp of when the graph was last
304 rendered will be used, "rrd" - the timestamp of when the RRD file
305 was last updated will be used, "both" - both the timestamps of when
306 the graph and RRD file were last updated will be used, "none" - no
307 timestamp will be used.
308
309 periods
310 The "periods" parameter is an optional list of periods that graphs
311 should be generated for. If omitted, all possible graphs will be
312 generated and not restricted to any specific subset. See the create
313 method for a list of valid time periods.
314
315 sources
316 The "sources" parameter is optional. This parameter should be an
317 array of data source names that you want to be plotted. All data
318 sources will be plotted by default.
319
320 source_colors
321 my %rtn = $rrd->graph($rrdfile,
322 source_colors => [ qw(ff3333 ff00ff ffcc99) ],
323 );
324
325 %rtn = $rrd->graph($rrdfile,
326 source_colors => { source_name1 => "ff3333",
327 source_name2 => "ff00ff",
328 source_name3 => "ffcc99", },
329 );
330
331 The "source_colors" parameter is optional. This parameter should be
332 an array or hash of hex triplet colors to be used for the plotted
333 data source lines. A selection of vivid primary colors will be set
334 by default.
335
336 source_labels
337 my %rtn = $rrd->graph($rrdfile,
338 sources => [ qw(source_name1 source_name2 source_name3) ],
339 source_labels => [ ("My Source 1","My Source Two","Source 3") ],
340 );
341
342 %rtn = $rrd->graph($rrdfile,
343 source_labels => { source_name1 => "My Source 1",
344 source_name2 => "My Source Two",
345 source_name3 => "Source 3", },
346 );
347
348 The "source_labels" parameter is optional. The parameter should be
349 an array or hash of labels to be placed in the legend/key underneath
350 the graph. An array can only be used if the "sources" parameter is
351 also specified, since the label index position in the array will
352 directly relate to the data source index position in the "sources"
353 array.
354
355 The data source names will be used in the legend/key by default if
356 no "source_labels" parameter is specified.
357
358 source_drawtypes
359 my %rtn = $rrd->graph($rrdfile,
360 source_drawtypes => [ qw(LINE1 AREA LINE) ],
361 );
362
363 %rtn = $rrd->graph($rrdfile,
364 source_colors => { source_name1 => "LINE1",
365 source_name2 => "AREA",
366 source_name3 => "LINE", },
367 );
368
369 %rtn = $rrd->graph($rrdfile,
370 sources => [ qw(system user iowait idle) ]
371 source_colors => [ qw(AREA STACK STACK STACK) ],
372 );
373
374 The "source_drawtypes" parameter is optional. This parameter should
375 be an array or hash of drawing/plotting types to be used for the
376 plotted data source lines. By default all data sources are drawn as
377 lines (LINE), but data sources may also be drawn as filled areas
378 (AREA). Valid values are, LINE, LINE*n* (where *n* represents the
379 thickness of the line in pixels), AREA or STACK.
380
381 line_thickness
382 Specifies the thickness of the data lines drawn on the graphs for
383 any data sources that have not had a specific line thickness already
384 specified using the "source_drawtypes" option. Valid values are 1, 2
385 and 3 (pixels).
386
387 extended_legend
388 If set to boolean true, prints more detailed information in the
389 graph legend by adding the minimum, maximum and last values recorded
390 on the graph for each data source.
391
392 Common RRD graph options are:
393
394 title
395 A horizontal string at the top of the graph.
396
397 vertical_label
398 A vertically placed string at the left hand side of the graph.
399
400 width
401 The width of the canvas (the part of the graph with the actual data
402 and such). This defaults to 400 pixels.
403
404 height
405 The height of the canvas (the part of the graph with the actual data
406 and such). This defaults to 100 pixels.
407
408 For examples on how to best use the "graph" method, refer to the example
409 scripts that are bundled with this module in the examples/ directory. A
410 complete list of parameters can be found at
411 <http://people.ee.ethz.ch/~oetiker/webtools/rrdtool/doc/index.en.html>.
412
413 retention_period
414 my $seconds = $rrd->retention_period($rrdfile);
415
416 This method will return the maximum period of time (in seconds) that the
417 RRD file will store data for.
418
419 $rrdfile is optional and will default to using the RRD filename
420 specified by the "new" constructor method, or "$0.rrd". (Script basename
421 with the file extension of .rrd).
422
423 info
424 my $info = $rrd->info($rrdfile);
425
426 This method will return a complex data structure containing details
427 about the RRD file, including RRA and data source information.
428
429 $rrdfile is optional and will default to using the RRD filename
430 specified by the "new" constructor method, or "$0.rrd". (Script basename
431 with the file extension of .rrd).
432
433 heartbeat
434 my $heartbeat = $rrd->heartbeat($rrdfile, "dsname");
435 my @rtn = $rrd->heartbeat($rrdfile, "dsname", 600);
436
437 This method will return the current heartbeat of a data source, or set a
438 new heartbeat of a data source.
439
440 $rrdfile is optional and will default to using the RRD filename
441 specified by the "new" constructor method, or "$0.rrd". (Script basename
442 with the file extension of .rrd).
443
444VARIABLES
445 $RRD::Simple::DEBUG
446 Debug and trace information will be printed to STDERR if this variable
447 is set to 1 (boolean true).
448
449 This variable will take its value from $ENV{DEBUG}, if it exists,
450 otherwise it will default to 0 (boolean false). This is a normal package
451 variable and may be safely modified at any time.
452
453 $RRD::Simple::DEFAULT_DSTYPE
454 This variable is used as the default data source type when creating or
455 adding new data sources, when no other data source type is explicitly
456 specified.
457
458 This variable will take its value from $ENV{DEFAULT_DSTYPE}, if it
459 exists, otherwise it will default to "GAUGE". This is a normal package
460 variable and may be safely modified at any time.
461
462EXPORTS
463 You can export the following functions if you do not wish to go through
464 the extra effort of using the OO interface:
465
466 create
467 update
468 last_update (synonym for the last() method)
469 sources
470 add_source
471 rename_source
472 graph
473 retention_period
474 info
475 heartbeat
476
477 The tag "all" is available to easily export everything:
478
479 use RRD::Simple qw(:all);
480
481 See the examples and unit tests in this distribution for more details.
482
483SEE ALSO
484 RRD::Simple::Examples, RRDTool::OO, RRDs, <http://www.rrdtool.org>,
485 examples/*.pl,
486 <http://search.cpan.org/src/NICOLAW/RRD-Simple-1.44/examples/>,
487 <http://rrd.me.uk>
488
489VERSION
490 $Id: Simple.pm 1100 2008-01-24 17:39:35Z nicolaw $
491
492AUTHOR
493 Nicola Worthington <nicolaw@cpan.org>
494
495 <http://perlgirl.org.uk>
496
497 If you like this software, why not show your appreciation by sending the
498 author something nice from her Amazon wishlist? (
499 http://www.amazon.co.uk/gp/registry/1VZXC59ESWYK0?sort=priority )
500
501COPYRIGHT
502 Copyright 2005,2006,2007,2008 Nicola Worthington.
503
504 This software is licensed under The Apache Software License, Version
505 2.0.
506
507 <http://www.apache.org/licenses/LICENSE-2.0>
508
509