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