RRD::Simple(3pm)

📦

version 1.44 · 2 versions

1.44 · fedora 43 (latest)
1.44 · fedora 44

💖 RRD::Simple 💖

so like, welcome to the RRD::Simple(3pm) page bestie — officially filed under User Contributed Perl Documentation, and it's genuinely one of those modules that just gets you. it's a simple interface for creating and storing data in RRD files, and if you've ever stared at raw RRDTool docs and felt your soul leave your body, this is the glow-up you deserve. 🦋

✨ NAME ✨

RRD::Simple — a simple interface to create and store data in RRD files. no cap, that's the whole assignment. 💅

🌸 SYNOPSIS 🌸

okay so here's the vibe, in code:

use strict;
use RRD::Simple ();

# Create an interface object
my $rrd = RRD::Simple->new( file => "myfile.rrd" );

# Create a new RRD file with 3 data sources called
# bytesIn, bytesOut and faultsPerSec.
$rrd->create(
            bytesIn => "GAUGE",
            bytesOut => "GAUGE",
            faultsPerSec => "COUNTER"
        );

# Put some arbitary data values in the RRD file for the same
# 3 data sources called bytesIn, bytesOut and faultsPerSec.
$rrd->update(
            bytesIn => 10039,
            bytesOut => 389,
            faultsPerSec => 0.4
        );

# Generate graphs:
# /var/tmp/myfile-daily.png, /var/tmp/myfile-weekly.png
# /var/tmp/myfile-monthly.png, /var/tmp/myfile-annual.png
my %rtn = $rrd->graph(
            destination => "/var/tmp",
            title => "Network Interface eth0",
            vertical_label => "Bytes/Faults",
            interlaced => ""
        );
printf("Created %s\n",join(", ",map { $rtn{$_}->[0] } keys %rtn));

# Return information about an RRD file
my $info = $rrd->info;
require Data::Dumper;
print Data::Dumper::Dumper($info);

# Get unixtime of when RRD file was last updated
my $lastUpdated = $rrd->last;
print "myfile.rrd was last updated at " .
      scalar(localtime($lastUpdated)) . "\n";

# Get list of data source names from an RRD file
my @dsnames = $rrd->sources;
print "Available data sources: " . join(", ", @dsnames) . "\n";

# And for the ultimately lazy, you could create and update
# an RRD in one go using a one-liner like this:
perl -MRRD::Simple=:all -e"update(@ARGV)" myfile.rrd bytesIn 99999

literally that last one-liner is for when you simply cannot be bothered, and honestly? respect. 🫶

🦋 DESCRIPTION 🦋

okay so the tea: RRD::Simple gives you a simple interface to RRDTool's RRDs module. that's the whole point. 🎀

heads up though — this module does not currently offer a "fetch" method, even though that one is available in the RRDs module. so don't come looking for it here, it's not here bestie. 😭

what it does do is create RRD files with a sensible set of default RRA (Round Robin Archive) definitions, and it can dynamically add new data source names to an RRD file that already exists. iconic behaviour, honestly. ✨

so if you just want quick and simple storage of data inside an RRD file, and you do not need to — nor want to — bother defining custom RRA definitions? this module is your girl. 👑

👑 METHODS 👑

💜 new

my $rrd = RRD::Simple->new(
        file => "myfile.rrd",
        rrdtool => "/usr/local/rrdtool-1.2.11/bin/rrdtool",
        tmpdir => "/var/tmp",
        cf => [ qw(AVERAGE MAX) ],
        default_dstype => "GAUGE",
        on_missing_ds => "add",
    );

the file parameter is currently optional, but plot twist: it's going to become mandatory in future releases, replacing the optional $rrdfile parameters on the methods that come after. so like, get with the program now. this parameter says which RRD filename gets used. 📁

the rrdtool parameter is optional. it specifically defines where the rrdtool binary can be found. if you don't specify it, the module goes hunting for the rrdtool binary in your path, plus an additional location relative to where the RRDs module was loaded from, and in /usr/local/rrdtool*. it's giving detective energy. 🔍

the tmpdir parameter is optional (the original says "option", we all know what she meant 💀) and it's only used when automatically adding a new data source to an existing RRD file. by default, any temporary files get dropped into your default system temp directory — typically /tmp on Linux, or whatever your TMPDIR environment variable is set to. this parameter is for when you want to force temp files into a specific directory.

the rrdtool binary is only used by the add_source method, and only under certain circumstances. also, add_source might get called automatically by the update method — specifically if you hand over data point values for a data source that was previously undefined. sneaky but helpful. 🙈

the cf parameter is optional, but when you do specify it, it expects an array reference. cf defines which consolidation functions get used in round robin archives (RRAs) when creating new RRD files. valid values are AVERAGE, MIN, MAX and LAST. the default value is AVERAGE and MAX.

the default_dstype parameter is optional. specifying the default data source type (DST) through new() lets the DST be localised to the $rrd object instance instead of being global to the whole RRD::Simple package. see $RRD::Simple::DEFAULT_DSTYPE.

the on_missing_ds parameter is optional and defaults to "add" when it's not defined. this one decides what happens when you try to insert or update data for a data source name that does not exist in the RRD file. valid values are "add", "ignore" and "die". choose your fighter. ⚔️

🎀 create

$rrd->create($rrdfile, $period,
        source_name => "TYPE",
        source_name => "TYPE",
        source_name => "TYPE"
    );

this method creates a new RRD file on disk. periodt. 💾

$rrdfile is optional and will default to the RRD filename you specified in the new constructor method, or "$0.rrd" (that's the script basename with the file extension of .rrd).

$period is optional and defaults to "year". valid options are "hour", "6hour"/"quarterday", "12hour"/"halfday", "day", "week", "month", "year", "3years" and "mrtg". specifying a data retention period value changes how long data gets retained inside the RRD file. the "mrtg" scheme will try and mimic the data retention period used by MRTG v2.13.2 (http://people.ee.ethz.ch/~oetiker/webtools/mrtg/).

fun fact bestie: the "mrtg" data retention period uses a data stepping resolution of 300 seconds (5 minutes) and a heartbeat of 600 seconds (10 minutes). every other data retention period uses a data stepping resolution of 60 seconds (1 minute) and a heartbeat of 120 seconds (2 minutes). not me knowing that by heart. 💅

each data source name should specify the data source type. valid data source types (DSTs) are GAUGE, COUNTER, DERIVE and ABSOLUTE. for further info, go peek at the section regarding DSTs at http://oss.oetiker.ch/rrdtool/doc/rrdcreate.en.html.

🚨 warning: RRD::Simple will croak and die if you try to create an RRD file that already exists. it is not playing. 💀

🔥 update

$rrd->update($rrdfile, $unixtime,
        source_name => "VALUE",
        source_name => "VALUE",
        source_name => "VALUE"
    );

this method updates an RRD file by inserting new data point values into it. 🔥

$rrdfile is optional and defaults to the RRD filename from the new constructor method, or "$0.rrd" (script basename, file extension .rrd).

$unixtime is optional and defaults to time() — that's the current unixtime, babes. specifying this value determines the date and time that your data point values get stored against inside the RRD file. ⏰

if you try to update a value for a data source that does not exist, it will automatically be added for you. the data source type gets set to whatever is contained in the $RRD::Simple::DEFAULT_DSTYPE variable. (see the VARIABLES section below, it's coming.)

if you explicitly do not want that to happen, then you should check that you're only updating pre-existing data source names by using the sources method. you can manually add new data sources to an RRD file with the add_source method instead — that one requires you to explicitly set the data source type. you're the main character, you make the rules. 👑

if you try to update an RRD file that does not exist, it will attempt to create the RRD file for you using the same behaviour described above. a warning message will be displayed saying the RRD file is being created for you, but only if you have perl warnings turned on. consider yourself warned. 🙈

⭐ last

my $unixtime = $rrd->last($rrdfile);

this method returns the last (most recent) data point entry time in the RRD file, in UNIX time (seconds since the epoch; Jan 1st 1970). 🕰️

do not confuse this value with the last modified time of the RRD file. they are different things, bestie, do not mix them up, it's giving chaos. 😭

$rrdfile is optional and defaults to the RRD filename from the new constructor method, or "$0.rrd" (script basename, file extension .rrd).

🌈 sources

my @sources = $rrd->sources($rrdfile);

this method returns a list of all the data source names contained inside the RRD file. every single one. no gatekeeping. 🌈

$rrdfile is optional and defaults to the RRD filename from the new constructor method, or "$0.rrd" (script basename, file extension .rrd).

🧚 add_source

$rrd->add_source($rrdfile,
        source_name => "TYPE"
    );

you can add a new data source to an existing RRD file with this method. one (1) data source name at a time only, so don't get greedy. you must also specify the data source type. 🧚

$rrdfile is optional and defaults to the RRD filename from the new constructor method, or "$0.rrd" (script basename, file extension .rrd).

this method can be called internally by the update method, so that missing data sources get added automatically. teamwork makes the dream work. 🫶

🍓 rename_source

$rrd->rename_source($rrdfile, "old_datasource", "new_datasource");

you can rename a data source in an existing RRD file with this method. glow-up achieved. ✨

$rrdfile is optional and defaults to the RRD filename from the new constructor method, or "$0.rrd" (script basename, file extension .rrd).

🌸 graph

my %rtn = $rrd->graph($rrdfile,
        destination => "/path/to/write/graph/images",
        basename => "graph_basename",
        timestamp => "both", # graph, rrd, both or none
        periods => [ qw(week month) ], # omit to generate all graphs
        sources => [ qw(source_name1 source_name2 source_name3) ],
        source_colors => [ qw(ff0000 aa3333 000000) ],
        source_labels => [ ("My Source 1", "My Source Two", "Source 3") ],
        source_drawtypes => [ qw(LINE1 AREA LINE) ],
        line_thickness => 2,
        extended_legend => 1,
        rrd_graph_option => "value",
        rrd_graph_option => "value",
        rrd_graph_option => "value"
    );

this method renders one or more graph images that show the data in the RRD file. this is the moment, honestly. 🎨

the number of image files created depends on the retention period of the RRD file. hourly, 6 hourly, 12 hourly, daily, weekly, monthly, annual and 3year graphs will be created — but only if there's enough data in the RRD file to accommodate them. no data, no graph, that's the rule. 💀

the image filenames start with either the basename of the RRD file, or whatever you specify in the basename parameter. the second part of the filename will be "-hourly", "-6hourly", "-12hourly", "-daily", "-weekly", "-monthly", "-annual" or "-3year", depending on the period being graphed. cute, consistent, we love a naming convention. 💅

$rrdfile is optional and defaults to the RRD filename from the new constructor method, or "$0.rrd" (script basename, file extension .rrd).

graph options specific to RRD::Simple are: (hold that thought — there's a whole list and it's a lot, more on that in a sec 🎀)

destination — this one's optional, bestie. If you don't say anything, it defaults to the same path as the RRD file from $rrdfile. If you do set it, the graph images get forced into that path. Just make sure that path is a real directory and you've got permission to write the graph images there, or it's gonna be a whole thing 💀
basename — optional too. It's the basename for the graph image files. If you skip it, it just uses the name of the RRD file. So if you set basename to mygraph, these files show up in the destination directory:

mygraph-daily.png
mygraph-weekly.png
mygraph-monthly.png
mygraph-annual.png

The default file format is png, but you can say otherwise using the standard RRDs options (peep below).

timestamp — optional, defaults to graph. It decides which "last updated" timestamps get slapped on the bottom right corner of the graph. Example:

my %rtn = $rrd->graph($rrdfile,
        timestamp => "graph", # graph, rrd, both or none
    );

Valid values are:

"graph" — timestamp of when the graph was last rendered.
"rrd" — timestamp of when the RRD file was last updated.
"both" — both timestamps, because why not.
"none" — no timestamp, we're mysterious.

periods — optional list of periods to generate graphs for. If you omit it, all possible graphs get generated, no restrictions. Check the create method for valid time periods.
sources — optional. Should be an array of data source names you want plotted. By default, all data sources get plotted.
source_colors — optional. Array or hash of hex triplet colors for the plotted data source lines. A selection of vivid primary colors is set by default. Examples:

my %rtn = $rrd->graph($rrdfile,
        source_colors => [ qw(ff3333 ff00ff ffcc99) ],
    );

%rtn = $rrd->graph($rrdfile,
        source_colors => { source_name1 => "ff3333",
                           source_name2 => "ff00ff",
                           source_name3 => "ffcc99", },
    );

source_labels — optional. Array or hash of labels for the legend/key underneath the graph. An array only works if you also specify sources, because the label index position lines up directly with the data source index position in the sources array. If you don't specify source_labels, the data source names get used in the legend/key by default. Examples:

my %rtn = $rrd->graph($rrdfile,
        sources => [ qw(source_name1 source_name2 source_name3) ],
        source_labels => [ ("My Source 1","My Source Two","Source 3") ],
    );

%rtn = $rrd->graph($rrdfile,
        source_labels => { source_name1 => "My Source 1",
                           source_name2 => "My Source Two",
                           source_name3 => "Source 3", },
    );

source_drawtypes — optional. Array or hash of drawing/plotting types for the plotted data source lines. By default all data sources are drawn as lines (LINE), but they can also be filled areas (AREA). Valid values: LINE, LINEn (where n is line thickness in pixels), AREA, or STACK. Examples:

my %rtn = $rrd->graph($rrdfile,
        source_drawtypes => [ qw(LINE1 AREA LINE) ],
    );

%rtn = $rrd->graph($rrdfile,
        source_colors => { source_name1 => "LINE1",
                           source_name2 => "AREA",
                           source_name3 => "LINE", },
    );

%rtn = $rrd->graph($rrdfile,
        sources => [ qw(system user iowait idle) ]
        source_colors => [ qw(AREA STACK STACK STACK) ],
    );

line_thickness — sets the thickness of data lines for any data sources that didn't already get a specific line thickness via the source_drawtypes option. Valid values: 1, 2, and 3 (pixels).
extended_legend — if set to boolean true, prints more detailed info in the graph legend by adding the minimum, maximum, and last values recorded on the graph for each data source.

Common RRD graph options are:

title — a horizontal string at the top of the graph.
vertical_label — a vertically placed string on the left hand side of the graph.
width — the width of the canvas (the part with the actual data and such). Defaults to 400 pixels.
height — the height of the canvas (the part with the actual data and such). Defaults to 100 pixels.

For examples on how to best use the graph method, check the example scripts bundled with this module in the examples/ directory. A complete list of parameters lives at <http://people.ee.ethz.ch/~oetiker/webtools/rrdtool/doc/index.en.html>.

retention_period 💧

my $seconds = $rrd->retention_period($rrdfile);

Returns the maximum period of time (in seconds) that the RRD file will store data for. $rrdfile is optional and defaults to the RRD filename from the new constructor method, or $0.rrd (script basename with the file extension .rrd).

info 🕵️‍♀️

my $info = $rrd->info($rrdfile);

Returns a complex data structure with details about the RRD file, including RRA and data source information. $rrdfile is optional and defaults to the RRD filename from the new constructor method, or $0.rrd (script basename with the file extension .rrd).

heartbeat 💓

my $heartbeat = $rrd->heartbeat($rrdfile, "dsname");
my @rtn = $rrd->heartbeat($rrdfile, "dsname", 600);

Returns the current heartbeat of a data source, or sets a new heartbeat for a data source. $rrdfile is optional and defaults to the RRD filename from the new constructor method, or $0.rrd (script basename with the file extension .rrd).

✨ VARIABLES ✨

`$RRD::Simple::DEBUG`

Debug and trace info gets printed to STDERR if this variable is set to 1 (boolean true). It takes its value from $ENV{DEBUG} if that exists, otherwise it defaults to 0 (boolean false). This is a normal package variable and may be safely modified at any time.

`$RRD::Simple::DEFAULT_DSTYPE`

This variable is the default data source type when creating or adding new data sources, when no other data source type is explicitly specified. It takes its value from $ENV{DEFAULT_DSTYPE} if that exists, otherwise it defaults to "GAUGE". This is a normal package variable and may be safely modified at any time.

✨ EXPORTS ✨

You can export these functions if you don't wanna do the extra effort of the OO interface:

create
update
last_update (synonym for the last() method)
sources
add_source
rename_source
graph
retention_period
info
heartbeat

The tag "all" is available to easily export everything:

use RRD::Simple qw(:all);

See the examples and unit tests in this distribution for more details.

✨ SEE ALSO ✨

RRD::Simple::Examples, RRDTool::OO, RRDs, <http://www.rrdtool.org>, examples/*.pl, <http://search.cpan.org/src/NICOLAW/RRD-Simple-1.44/examples/>, <http://rrd.me.uk>

✨ VERSION ✨

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

✨ AUTHOR ✨

Nicola Worthington <nicolaw@cpan.org>

<http://perlgirl.org.uk>

If you like this software, why not show your appreciation by sending the author something nice from her Amazon wishlist <http://www.amazon.co.uk/gp/registry/1VZXC59ESWYK0?sort=priority>? ( http://www.amazon.co.uk/gp/registry/1VZXC59ESWYK0?sort=priority )

✨ COPYRIGHT ✨

This software is licensed under The Apache Software License, Version 2.0.

<http://www.apache.org/licenses/LICENSE-2.0>

This lil page was brought to you by RRD::Simple(3pm), perl v5.42.0, dated 2025-07-25. Stay hydrated and go plot something gorgeous, bestie 💖🦋

📦 where this page comes from

fedora 43: perl-RRD-Simple 1.44-52.fc43 · Apache-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms