1RRD::Simple(3pm)      User Contributed Perl Documentation     RRD::Simple(3pm)
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 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
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        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
84       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
89       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
94       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
101       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
106       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
112       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
117       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
122   create
123        $rrd->create($rrdfile, $period,
124                source_name => "TYPE",
125                source_name => "TYPE",
126                source_name => "TYPE"
127            );
128
129       This method will create a new RRD file on disk.
130
131       $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
135       $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
143       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
148       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
154       RRD::Simple will croak and die if you try to create an RRD file that
155       already exists.
156
157   update
158        $rrd->update($rrdfile, $unixtime,
159                source_name => "VALUE",
160                source_name => "VALUE",
161                source_name => "VALUE"
162            );
163
164       This method will update an RRD file by inserting new data point values
165       in to the RRD file.
166
167       $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
171       $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
175       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
180       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
186       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
191   last
192        my $unixtime = $rrd->last($rrdfile);
193
194       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
199       $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
203   sources
204        my @sources = $rrd->sources($rrdfile);
205
206       This method returns a list of all of the data source names contained
207       within the RRD file.
208
209       $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
213   add_source
214        $rrd->add_source($rrdfile,
215                source_name => "TYPE"
216            );
217
218       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
222       $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
226       This method can be called internally by the "update" method to
227       automatically add missing data sources.
228
229   rename_source
230        $rrd->rename_source($rrdfile, "old_datasource", "new_datasource");
231
232       You may rename a data source in an existing RRD file using this method.
233
234       $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
238   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
255       This method will render one or more graph images that show the data in
256       the RRD file.
257
258       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
263       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
269       $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
273       Graph options specific to RRD::Simple are:
274
275       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
283       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
290            mygraph-daily.png
291            mygraph-weekly.png
292            mygraph-monthly.png
293            mygraph-annual.png
294
295           The default file format is "png", but this can be explicitly
296           specified using the standard RRDs options. (See below).
297
298       timestamp
299            my %rtn = $rrd->graph($rrdfile,
300                    timestamp => "graph", # graph, rrd, both or none
301                );
302
303           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
307           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
313       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
319       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
324       source_colors
325            my %rtn = $rrd->graph($rrdfile,
326                    source_colors => [ qw(ff3333 ff00ff ffcc99) ],
327                );
328
329            %rtn = $rrd->graph($rrdfile,
330                    source_colors => { source_name1 => "ff3333",
331                                       source_name2 => "ff00ff",
332                                       source_name3 => "ffcc99", },
333                );
334
335           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
340       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
346            %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
352           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
359           The data source names will be used in the legend/key by default if
360           no "source_labels" parameter is specified.
361
362       source_drawtypes
363            my %rtn = $rrd->graph($rrdfile,
364                    source_drawtypes => [ qw(LINE1 AREA LINE) ],
365                );
366
367            %rtn = $rrd->graph($rrdfile,
368                    source_colors => { source_name1 => "LINE1",
369                                       source_name2 => "AREA",
370                                       source_name3 => "LINE", },
371                );
372
373            %rtn = $rrd->graph($rrdfile,
374                    sources => [ qw(system user iowait idle) ]
375                    source_colors => [ qw(AREA STACK STACK STACK) ],
376                );
377
378           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
385       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
391       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
396       Common RRD graph options are:
397
398       title
399           A horizontal string at the top of the graph.
400
401       vertical_label
402           A vertically placed string at the left hand side of the graph.
403
404       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
408       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
412       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
417   retention_period
418        my $seconds = $rrd->retention_period($rrdfile);
419
420       This method will return the maximum period of time (in seconds) that
421       the RRD file will store data for.
422
423       $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
427   info
428        my $info = $rrd->info($rrdfile);
429
430       This method will return a complex data structure containing details
431       about the RRD file, including RRA and data source information.
432
433       $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
437   heartbeat
438        my $heartbeat = $rrd->heartbeat($rrdfile, "dsname");
439        my @rtn = $rrd->heartbeat($rrdfile, "dsname", 600);
440
441       This method will return the current heartbeat of a data source, or set
442       a new heartbeat of a data source.
443
444       $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

VARIABLES

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
453       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
457   $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
462       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

EXPORTS

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
470        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
481       The tag "all" is available to easily export everything:
482
483        use RRD::Simple qw(:all);
484
485       See the examples and unit tests in this distribution for more details.
486

SEE ALSO

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

VERSION

494       $Id: Simple.pm 1100 2008-01-24 17:39:35Z nicolaw $
495

AUTHOR

497       Nicola Worthington <nicolaw@cpan.org>
498
499       <http://perlgirl.org.uk>
500
501       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
509       This software is licensed under The Apache Software License, Version
510       2.0.
511
512       <http://www.apache.org/licenses/LICENSE-2.0>
513
514
515
516perl v5.38.0                      2023-07-21                  RRD::Simple(3pm)
Impressum