PHP - RRD rrd_create() Function

---

---

The PHP RRD rrd_create() function is used to create a new RRD file. This function is part of the RRDtool, which records and displays time-series data.

Syntax

Below is the syntax of the PHP RRD rrd_create() function −

bool rrd_create(string $filename, array $options)

Parameters

Below are the parameters of the rrd_create() function −

• $filename − It is the name of the RRD file to be created.

• $options − It is an array of options which define the structure of the RRD file. It basically includes start time, step interval, and the data sources with its configurations.

Return Value

The rrd_create() function returns TRUE on success and FALSE on failure.

PHP Version

The rrd_create() function is available from version 0.9.0 of the PECL rrd extension.

Example 1

First we will show you the basic example of the PHP RRD rrd_create() function to create an RRD file with minimal options.

<?php
   $filename = "example.rrd";
   $options = [
       "--start", "now-1h",       // Start time 
       "--step", "300",           
       "DS:temp:GAUGE:600:-273:5000", // Data Source
       "RRA:AVERAGE:0.5:1:120"    
   ];
   
   if (rrd_create($filename, $options)) {
       echo "RRD file created successfully.";
   } else {
       echo "Failed to create RRD file.";
   }
?>

Output

The above code will result something like this if RRD is successfully created −

RRD file created successfully.

If there is an error, it will show:

Failed to create RRD file.

Example 2

In the below PHP code we will try to use the rrd_create() function and create an RRD with multiple data sources.

<?php
   $filename = "example.rrd";
   $options = [
       "--start", "now-1h",
       "--step", "300",
       "DS:temp:GAUGE:600:-273:5000",    // Temperature data source
       "DS:humidity:GAUGE:600:0:100",   
       "RRA:AVERAGE:0.5:1:120",
       "RRA:AVERAGE:0.5:12:24"          
   ];
   
   if (rrd_create($filename, $options)) {
       echo "RRD file with multiple data sources created successfully.";
   } else {
       echo "Failed to create RRD file.";
   }
?> 

Output

After running the above program, it generates the following output −

RRD file with multiple data sources created successfully.

If there is an error occur, it will the message below:

Failed to create RRD file.

Example 3

In this example, an RRD file that tracks system load is created using three different aggregation techniques: average, maximum, and minimum.

<?php
   $filename = "example.rrd";
   $options = [
       "--start", "now-1d",
       "--step", "300",
       "DS:load:GAUGE:600:0:U",    // System load data source
       "RRA:AVERAGE:0.5:1:288",    // Average aggregation
       "RRA:MAX:0.5:1:288",        // Maximum value aggregation
       "RRA:MIN:0.5:1:288"         // Minimum value aggregation
   ];
   
   if (rrd_create($filename, $options)) {
       echo "RRD file created successfully with different aggregation methods.";
   } else {
       echo "Failed to create RRD file.";
   }
   
?> 

Output

This will create the below output −

RRD file created successfully with different aggregation methods.

If an error occur, it will show the message below:

Failed to create RRD file.

Important Note

The RRD rrd_create() function is very useful for applications that need to track and evaluate a range of statistics over time, like network capacity, environmental data, and system performance.