/ 
RRD-Fetch-0.0.1
/ RRD::Fetch

NAME

RRD::Fetch - Fetch information from a RRD file.

VERSION

Version 0.0.1

SYNOPSIS

use RRD::Fetch;

my $rrd_fetch=RRD::Fetch->new(rrd_file=>'foo.rrd');

SUBROUTINES/METHODS

new

Initiates the object.

The required args are as below.

- rrd_file :: The RRD file to operate on. It needs to exist at the time it is called.
    Default :: undef

The following are optional.

- CF :: The RRD CF type to use.
    Default :: AVERAGE
    Values :: AVERAGE, MIN, MAX, LAST

- resolution :: Interval you want the values to have. Note, this does not support the optional
        suffixes as of currently.
    Default :: undef
    Type :: int

- backoff :: How many seconds to wait for to try again if it has a non-zero exit.
    Default :: 1
    Type :: int

- retries :: Number of times to retry if there is a non-zero exit. Set to 0 to disable.
    Default :: 3
    Type :: int

- align :: Call with --align-start.
    Default :: 1
    Type :: bool

fetch_raw

Fetches the specified information.

The required args are as below. Be aware as of currently start/end are not validated.

- start :: Value for passing via the --start flag.
    Default :: undef

- end :: Value for passing via the --start flag.
    Default :: undef

Be aware exceeding the number of retries is not a fatal error. It will issue a warning.

my $results = $rrd_fetch->fetch_raw(start=>'20240503', end=>'start+1d');
if ($results->{success}) {
    print $results->{output};
} else {
    die("Number of retries exceeded... last output was...\n".$results->{output});
}

The returned data is hash ref.

- .output :: The results of the fetch command.

- .success :: 0/1 for if it succeded or not.

- .retries :: The number of retries. 0 if success on the first attempt.

fetch_joined

Fetches the specified information.

The required args are as below. Be aware as of currently start/end are not validated.

- start :: Value for passing via the --start flag.
    Default :: undef

- end :: Value for passing via the --start flag.
    Default :: undef

The optional args are as below.

- by :: What to join by.
        time - Join by the time value
        column - join by the column name

    Default :: column

Be aware exceeding the number of retries is not a fatal error. It will issue a warning.

my $results = $rrd_fetch->fetch_raw(start=>'20240503', end=>'start+1d');

The return is is a hash ref for column by is as below.

- .output :: The results of the fetch command.

- .success :: 0/1 for if it succeded or not.

- .retries :: The number of retries. 0 if success on the first attempt.

- .columns[] :: A array of the columns.

- .data :: A hash ref that holds the columns.

- .data.$column[] :: A array for a specific column that holds values at that time.
    The time can for a specific value can be looked up via checking it's array location
    in the array .rows[]. So lets say we a column named foo and we want the time for value
    3, $results->{data}{foo}[3], we would check .rows[3], $results->{rows}[3].

- .rows[] :: A array of time stamps.

The return is is a hash ref for column by is as below.

- .output :: The results of the fetch command.

- .success :: 0/1 for if it succeded or not.

- .retries :: The number of retries. 0 if success on the first attempt.

- .columns[] :: A array of the columns.

- .data :: A hash ref that holds the rows

- .data.$time :: A hash that holds a hash of the columns for that point in time.

- .data.$time.$column :: A value for a column at a specific point in time.

- .rows[] :: A array of time stamps.

daily_max

Gets daily max info.

Requires a start time and end time in

- start :: Start time in %Y%m%d
    Default :: undef

- for :: Number of days to get info on.
    Default :: 7

The return is is a hash ref for column by is as below.

- .columns[] :: A array of the columns.

- .dates[] :: A array of dates.

. .max.$date.$column :: The max info for a specific column on that date.

ERROR CODES/FLAGS

1/not_a_file

The specified file is not a file.

2/rrd_file_undef

The value given for rrd_file is undef.

3/fetch_retries_exceeded

rrdtool exited zero and number of retries has been exceeded.

4/wrong_ref_type

The specified variable is of the wrong ref type.

5/not_a_int

Value is not a int.

6/less_than_1

The number is less than1.

7/CF_bad

The value of CF is not set to one of the following.

AVERAGE
MIN
MAX
LAST

8/start_undef

start is undef.

9/end_undef

end is undef.

10/bad_by_opt

The value for $opts{by} is not recognized. See the docs for fetch_joined.

11/no_columns

Unable to retrieve any columns info. Parsing failed for some reason, likely due to bad data.

12/start_wrong_format

The value for start is not in the format %Y%m%d.

13/start_failed_parsing

The value passed for start could not be parsed via Time::Piece. Expected for mat is %Y%m%d.

14/fetching_a_day_failed

Failed to fetch information for a a day.

AUTHOR

Zane C. Bowers-Hadley, <vvelox at vvelox.net>

BUGS

Please report any bugs or feature requests to bug-rrd-fetch at rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=RRD-Fetch. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc RRD::Fetch

You can also look for information at:

LICENSE AND COPYRIGHT

This software is Copyright (c) 2025 by Zane C. Bowers-Hadley.

This is free software, licensed under:

The GNU General Public License, Version 2, June 1991