Signatur
Beschreibung
rrd_create() erzeugt eine neue RRD-Datei (Round Robin Database), die zur Speicherung von Zeitreihendaten wie Netzwerkverkehr, CPU-Auslastung oder Sensorwerten genutzt wird. RRD ist ein zyklisches Speicherformat, das ältere Daten automatisch durch Aggregationen ersetzt, sodass der Speicherbedarf konstant bleibt.
Der Parameter $options entspricht dabei den Befehlszeilenargumenten des rrdtool create-Kommandos: Er enthält Angaben zum Startzeit-Wert (--start), zum Messintervall (--step), zu Datenquellen (DS:...) sowie zu Round-Robin-Archiven (RRA:...), die die Konsolidierungsfunktion und Aufbewahrungsdauer definieren.
Typische Anwendungsfälle sind Monitoring-Systeme, Netzwerk-Management-Tools (z. B. MRTG-ähnliche Lösungen) oder jede Applikation, die zeitbasierte Metriken über lange Zeiträume effizient speichern und visualisieren muss. Die Funktion ist Bestandteil der PECL-Erweiterung rrd, die auf der rrdtool-Bibliothek aufbaut.
Vor dem Aufruf muss sichergestellt werden, dass die Zieldatei noch nicht existiert, da RRD bestehende Dateien nicht überschreibt. Das Verzeichnis, in dem die Datei erstellt werden soll, muss für den PHP-Prozess beschreibbar sein.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $filename Pflicht | string | Pfad zur zu erstellenden RRD-Datei (z. B. /var/rrd/traffic.rrd). Die Datei darf noch nicht existieren. |
|
| $options Pflicht | array | Array mit Optionen für rrdtool create. Mögliche Elemente sind z. B. '--start', '--step', 'DS:name:typ:heartbeat:min:max' und 'RRA:CF:xff:steps:rows'. Die Reihenfolge entspricht der CLI-Syntax von rrdtool. |
Rückgabewert
true zurück, wenn die RRD-Datei erfolgreich angelegt wurde. Im Fehlerfall wird false zurückgegeben; mit rrd_error() kann die Fehlermeldung abgerufen werden.Beispiele
Einfache RRD-Datei für Netzwerkverkehr erstellen
<?php
$filename = '/tmp/traffic.rrd';
$options = [
'--start', 'now-10s',
'--step', '300', // Messintervall: 300 Sekunden
'DS:in_octets:COUNTER:600:0:U', // Datenquelle: eingehende Bytes
'DS:out_octets:COUNTER:600:0:U', // Datenquelle: ausgehende Bytes
'RRA:AVERAGE:0.5:1:600', // 5-Minuten-Werte, 50 Stunden
'RRA:AVERAGE:0.5:6:700', // 30-Minuten-Werte, ~14 Tage
'RRA:MAX:0.5:6:700',
];
if (rrd_create($filename, $options)) {
echo 'RRD-Datei erfolgreich erstellt: ' . $filename . PHP_EOL;
} else {
echo 'Fehler: ' . rrd_error() . PHP_EOL;
}RRD-Datei für CPU-Auslastung mit mehreren Archiven
<?php
$filename = '/tmp/cpu_load.rrd';
// Sicherstellen, dass die Datei noch nicht existiert
if (file_exists($filename)) {
unlink($filename);
}
$options = [
'--start', strval(time() - 10),
'--step', '60', // 1-Minuten-Intervall
'DS:cpu:GAUGE:120:0:100', // CPU in Prozent (0–100)
'RRA:AVERAGE:0.5:1:1440', // 1-Minuten-Werte für 1 Tag
'RRA:AVERAGE:0.5:5:2016', // 5-Minuten-Werte für 1 Woche
'RRA:AVERAGE:0.5:60:720', // Stundenwerte für 30 Tage
'RRA:MAX:0.5:60:720', // Stunden-Maxima für 30 Tage
'RRA:MIN:0.5:60:720', // Stunden-Minima für 30 Tage
];
$result = rrd_create($filename, $options);
if ($result) {
echo 'CPU-RRD-Datei angelegt.' . PHP_EOL;
echo 'Dateigröße: ' . filesize($filename) . ' Bytes' . PHP_EOL;
} else {
echo 'Fehler beim Erstellen: ' . rrd_error() . PHP_EOL;
}// Wichtig · Fallstricke
PECL-Erweiterung: rrd_create() ist Teil der PECL-Erweiterung rrd und steht nicht standardmäßig in PHP zur Verfügung. Die Erweiterung muss separat installiert werden (pecl install rrd) und setzt die librrd-Entwicklungspakete voraus.
Dateiberechtigungen: Das Zielverzeichnis muss für den PHP-Prozess (z. B. www-data) schreibbar sein. Sensible RRD-Dateien sollten außerhalb des Web-Roots abgelegt werden, um direkten HTTP-Zugriff zu verhindern.
DS-Typen: Wichtig ist die korrekte Wahl des Datenquellen-Typs: COUNTER für monoton steigende Zähler (z. B. Bytes), GAUGE für direkte Messwerte (z. B. Temperatur), DERIVE für Ableitungen auch negativer Werte und ABSOLUTE für Zähler, die nach jedem Abruf zurückgesetzt werden.
Fehlerbehandlung: Im Fehlerfall gibt die Funktion false zurück. Die genaue Fehlermeldung ist über rrd_error() abrufbar. Häufige Fehlerquellen sind eine bereits existierende Datei, ungültige DS- oder RRA-Definitionen sowie fehlende Schreibrechte.