RRDtool

Introduction
The PECL/rrd extension provides bindings to the RRDtool C library. RRDtool is the open source industry standard, high performance data logging and graphing system for time series data. The RRDtool homepage is http://www.mrtg.org/rrdtool/.

RRDtool

Installing/Configuring
Requirements
You need to install librrd first to be able to use PECL/rrd. Most common option is using of librrd-dev package from your favourite linux distro. PECL/rrd is tested with librrd 1.4.3, older or newer versions might or might not work for you. PECL/rrd installation is tested with PHP 5.3.2 or newer.

Warning Librrd and hence extension itself aren't mostly thread safe. There are many global and shared states in librrd. It can be dangerous use this extension in multi threaded environments like Apache2 mpm worker. If there are many parallel requests, one request can change some global librrd state of other runnig requests.

Installation
Information for installing this PECL extension may be found in the manual chapter titled Installation of PECL extensions. Additional information such as new releases, downloads, source files, maintainer information, and a CHANGELOG, can be located here: http://pecl.php.net/package/rrd.

Runtime Configuration
This extension has no configuration directives defined in php.ini.

Resource Types
This extension has no resource types defined.

RRDtool

Predefined Constants
This extension has no constants defined.

RRDtool

Examples
Procedural PECL/rrd example

Example #1 - Procedural usage of rrd

<?php $rrdFile = dirname(__FILE__) . "/speed.rrd"; //create rrd file rrd_create($rrdFile, array( "--start",920804400, "DS:speed:COUNTER:600:U:U", "RRA:AVERAGE:0.5:1:24", "RRA:AVERAGE:0.5:6:10" ) ); //update rrd file rrd_update($rrdFile, array( "920804700:12345", "920805000:12357" ) ); //graph output rrd_graph(dirname(__FILE__) . "/speed.png", array( "--start", "920804400", "--end", "920808000", "--vertical-label", "m/s", "DEF:myspeed=$rrdFile:speed:AVERAGE", "CDEF:realspeed=myspeed,1000,*", "LINE2:realspeed#FF0000" ) ); ?>

OOP PECL/rrd example

Example #1 - OO usage of rrd

<?php $rrdFile = dirname(__FILE__) . "/speed.rrd";

RRDtool

$outputPngFile = dirname(__FILE__) . "/speed.png"; $creator = new RRDCreator($rrdFile, "now -10d", 500); $creator->addDataSource("speed:COUNTER:600:U:U"); $creator->addArchive("AVERAGE:0.5:1:24"); $creator->addArchive("AVERAGE:0.5:6:10"); $creator->save(); $updater = new RRDUpdater($rrdFile); $updater->update(array("speed" => "12345"), "920804700"); $updater->update(array("speed" => "12357"), "920805000"); $graphObj = new RRDGraph($outputPngFile); $graphObj->setOptions( array( "--start" => "920804400", "--end" => 920808000, "--vertical-label" => "m/s", "DEF:myspeed=$rrdFile:speed:AVERAGE", "CDEF:realspeed=myspeed,1000,*", "LINE2:realspeed#FF0000" ) ); $graphObj->save(); ?>

RRDtool

RRD Functions

RRDtool

rrd_create
rrd_create -- Creates rrd database file

Description
bool rrd_create ( string $filename, array $options ) Creates the rdd database file.

Parameters
filename

Filename for newly created rrd file.

options

Options for rrd create - list of strings. See man page of rrd create for whole list of options.

Return Values
Returns TRUE on success or FALSE on failure.

RRDtool

rrd_error
rrd_error -- Gets latest error message.

Description
string rrd_error ( void ) Returns latest global rrd error message.

Parameters
This function has no parameters.

Return Values
Latest error message.

RRDtool

rrd_fetch
rrd_fetch -- Fetch the data for graph as array.

Description
array rrd_fetch ( string $filename, array $options ) Gets data for graph output from RRD database file as array. This function has same result as rrd_graph(), but fetched data are returned as array, no image file is created.

Parameters
filename

RRD database file name.

options

Array of options for resolution specification.

Return Values
Returns information about retrieved graph data.

RRDtool

10

rrd_first
rrd_first -- Gets the timestamp of the first sample from rrd file.

Description
int rrd_first ( string $file [, int $raaindex = 0 ] ) Returns the first data sample from the specified RRA of the RRD file.

Parameters
file

RRD database file name.

raaindex

The index number of the RRA that is to be examined. Default value is 0.

Return Values
Integer number of unix timestamp, FALSE if some error occurs.

RRDtool

11

rrd_graph
rrd_graph -- Creates image from a data.

Description
array rrd_graph ( string $filename, array $options ) Creates image for a particular data from RRD file.

Parameters
filename

RRD database file name.

options

Options for generating image. See man page of rrd graph for all possible options. All options (data definitions, variable defintions, etc.) are allowed.

Return Values
Array with information about generated image is returned, FALSE when error occurs.

RRDtool

12

rrd_info
rrd_info -- Gets information about rrd file

Description
array rrd_info ( string $filename ) Returns information about particular RRD database file.

Parameters
file

RRD database file name.

Return Values
Array with information about requsted RRD file, FALSE when error occurs.

RRDtool

13

rrd_last
rrd_last -- Gets unix timestamp of the last sample.

Description
int rrd_last ( string $filename ) Returns the UNIX timestamp of the most recent update of the RRD database.

Parameters
filename

RRD database file name.

Return Values
Integer as unix timestamp of the most recent data from the RRD database.

RRDtool

14

rrd_lastupdate
rrd_lastupdate -- Gets information about last updated data.

Description
array rrd_lastupdate ( string $filename ) Gets array of the UNIX timestamp and the values stored for each date in the most recent update of the RRD database file.

Parameters
file

RRD database file name.

Return Values
Array of information about last update, FALSE when error occurs.

RRDtool

15

rrd_restore
rrd_restore -- Restores the RRD file from XML dump.

Description
bool rrd_restore ( string $xml_file, string $rrd_file [, array $options ] ) Restores the RRD file from the XML dump.

Parameters
xml_file

XML filename with the dump of the original RRD database file.
rrd_file

Restored RRD database file name.

options

Array of options for restoring. See man page for rrd restore.

Return Values
Returns TRUE on success, FALSE otherwise.

RRDtool

16

rrd_tune
rrd_tune -- Tunes some RRD database file header options.

Description
bool rrd_tune ( string $filename, array $options ) Change some options in the RRD dabase header file. E.g. renames the source for the data etc.

Parameters
filename

RRD database file name.

options

Options with RRD database file properties which will be changed. See rrd tune man page for details.

Return Values
Returns TRUE on success, FALSE otherwise.

RRDtool

17

rrd_update
rrd_update -- Updates the RRD database.

Description
bool rrd_update ( string $filename, array $options ) Updates the RRD database file. The input data is time interpolated according to the properties of the RRD database file.

Parameters
filename

RRD database file name. This database will be updated.

options

Options for updating the RRD database. This is list of strings. See man page of rrd update for whole list of options.

Return Values
Returns TRUE on success, FALSE when error occurs.

RRDtool

18

rrd_version
rrd_version -- Gets information about underlying rrdtool library

Description
string rrd_version ( void ) Returns information about underlying rrdtool library.

Parameters
This function has no parameters.

Return Values
String with rrdtool version number e.g. "1.4.3".

RRDtool

19

rrd_xport
rrd_xport -- Exports the information about RRD database.

Description
array rrd_xport ( array $options ) Exports the information about RRD database file. This data can be converted to XML file via user space PHP script and then restored back as RRD database file.

Parameters
options

Array of options for the export, see rrd xport man page.

Return Values
Array with information about RRD database file, FALSE when error occurs.

RRDtool

20

The RRDCreator class

Introduction
Class for creation of RRD database file.

Class synopsis

RRDCreator

RRDCreator { /* Methods */ public void RRDCreator::addArchive ( string $description ) public void RRDCreator::addDataSource ( string $description ) public RRDCreator::__construct ( string $path [, string $startTime [, int $step = 0 ] ]) public bool RRDCreator::save ( void ) }

RRDtool

21

RRDCreator::addArchive
RRDCreator::addArchive -- Adds RRA - archive of data values for each data source.

Description
public void RRDCreator::addArchive ( string $description ) Adds RRA definition by description of archive. Archive consists of a number of data values or statistics for each of the defined data-sources (DS). Data sources are defined by method RRDCreator::addDataSource. You need call this method for each requested archive.

Parameters
description

Definition of archive - RRA. This has same format as RRA definition in rrd create command. See man page of rrd create for more details.

Return Values
No value is returned.

RRDtool

22

RRDCreator::addDataSource
RRDCreator::addDataSource -- Adds data source definition for RRD database.

Description
public void RRDCreator::addDataSource ( string $description ) RRD can accept input from several data sources (DS), e.g incomming and outgoing traffic. This method adds data source by description. You need call this method for each data source.

Parameters
description

Definition of data source - DS. This has same format as DS definition in rrd create command. See man page of rrd create for more details.

Return Values
No value is returned.

RRDtool

23

RRDCreator::__construct
RRDCreator::__construct -- Creates new RRDCreator instance

Description
public RRDCreator::__construct ( string $path [, string $startTime [, int $step = 0 ] ] ) Creates new RRDCreator instance.

Parameters
path

Path for newly created RRD database file.

startTime

Time for the first value in RRD database. Parameter supports all formats which are supported by rrd create call. int step Base interval in seconds with which data will be fed into the RRD database.

Return Values
No value is returned.

RRDtool

24

RRDCreator::save
RRDCreator::save -- Saves the RRD database to a file

Description
public bool RRDCreator::save ( void ) Saves the RRD database into file, which name is defined by RRDCreator::__construct.

Parameters
This function has no parameters.

Return Values
Returns TRUE on success or FALSE on failure.

RRDtool

25

The RRDGraph class

Introduction
Class for exporting data from RRD database to image file.

Class synopsis

RRDGraph

RRDGraph { /* Methods */ public RRDGraph::__construct ( string $path ) public array RRDGraph::save ( void ) public array RRDGraph::saveVerbose ( void ) public void RRDGraph::setOptions ( array $options ) }

RRDtool

26

RRDGraph::__construct
RRDGraph::__construct -- Creates new RRDGraph instance

Description
public RRDGraph::__construct ( string $path ) Creates new RRDGraph instance. This instance is responsible for rendering the result of RRD database query into image.

Parameters
path

Full path for the newly created image.

Return Values
No value is returned.

RRDtool

27

RRDGraph::save
RRDGraph::save -- Saves the result of query into image

Description
public array RRDGraph::save ( void ) Saves the result of RRD database query into image defined by RRDGraph::__construct.

Parameters
This function has no parameters.

Return Values
Array with information about generated image is returned, FALSE if error occurs.

RRDtool

28

RRDGraph::saveVerbose
RRDGraph::saveVerbose -- Saves the RRD database query into image and returns the verbose information about generated graph.

Description
public array RRDGraph::saveVerbose ( void ) Saves the RRD database query into image file defined by method RRDGraph::__construct and returns the verbose information about generated graph, if "-" is used as image filename, image data are also returned in result array.

Parameters
This function has no parameters.

Return Values
Array with detailed information about generated image is returned, optionally with image data, FALSE if error occurs.

RRDtool

29

RRDGraph::setOptions
RRDGraph::setOptions -- Sets the options for rrd graph export

Description
public void RRDGraph::setOptions ( array $options )

Parameters
options

List of options for the image generation from the RRD database file. It can be list of strings or list of strings with keys for better readability. Read the rrd graph man pages for list of available options.

Return Values
No value is returned.

Examples

Example #1 - RRDGraph::setOptions examples

<?php $graphObj->setOptions(array( "--start" => "920804400", "--end" => 920808000, "--vertical-label" => "m/s", "DEF:myspeed=$rrdFile:speed:AVERAGE", "CDEF:realspeed=myspeed,1000,*", "LINE2:realspeed#FF0000" )); ?>

RRDtool

30

The RRDUpdater class

Introduction
Class for updating RDD database file.

Class synopsis

RRDUpdater

RRDUpdater { /* Methods */ public RRDUpdater::__construct ( string $path ) public bool RRDUpdater::update ( array $values [, string $time = time() ] ) }

RRDtool

31

RRDUpdater::__construct
RRDUpdater::__construct -- Creates new RRDUpdater instance

Description
public RRDUpdater::__construct ( string $path ) Creates new RRDUpdater instance. This instance is responsible for updating the RRD database file.

Parameters
path

Filesystem path for RRD database file, which will be updated.

Return Values
No value is returned.

RRDtool

32

RRDUpdater::update
RRDUpdater::update -- Update the RRD database file

Description
public bool RRDUpdater::update ( array $values [, string $time = time() ] ) Updates the RRD file defined via RRDUpdater::__construct. The file is updated with a specific values.

Parameters
values

Data for update. Key is data source name.

time

Time value for updating the RRD with a particulat data. Default value is current time.

Return Values
Returns TRUE on success or FALSE on failure.

Errors/Exceptions
Throws a Exception on error.

Examples

Example #1 - RRDUpdater::update examples

<?php $updator = new RRDUpdater("speed.rrd"); //updates the data source "speed" with value "12411" //for time defined by timestamp "920807700" $updator->update(array("speed" => "12411"), "920807700"); ?>

RRDtool

33