Signatur
Beschreibung
rrd_graph() ist Teil der PECL-Erweiterung rrd und dient dazu, aus Round-Robin-Datenbanken (RRD) aussagekräftige Zeitreihen-Grafiken zu erstellen. Die Funktion ist das PHP-Pendant zum Kommandozeilen-Tool rrdtool graph.
Der erste Parameter gibt den Pfad zur Ausgabedatei an (z. B. eine PNG-Datei). Das $options-Array enthält alle Steuerparameter, die auch auf der Kommandozeile übergeben werden würden – darunter Zeitbereich (--start, --end), Grafikgröße, Titel, Datendefinitionen (DEF:), Berechnungen (CDEF:) und Zeichenanweisungen (LINE, AREA, GPRINT usw.).
Die Funktion eignet sich besonders für Monitoring- und Statistikwendungen, bei denen Messdaten (CPU-Auslastung, Netzwerktraffic, Temperatur etc.) über Zeit gesammelt und visualisiert werden sollen. Der Rückgabewert enthält Metadaten über die erzeugte Grafik, wie Breite, Höhe und die Anzahl der gezeichneten Werte.
Voraussetzung ist, dass die rrdtool-Bibliothek und die PECL-Erweiterung rrd auf dem System installiert sind.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $filename Pflicht | string | Pfad zur Ausgabedatei, in die die fertige Grafik geschrieben wird (z. B. /var/www/html/graphs/cpu.png). Als Sonderfall kann - übergeben werden, um die Grafik in den Ausgabepuffer zu schreiben. |
|
| $options Pflicht | array | Assoziatives oder numerisch indiziertes Array mit rrdtool-Optionen als Strings. Jede Option entspricht einem Argument des rrdtool graph-Befehls, z. B. '--start=-1d', 'DEF:ds0=data.rrd:traffic:AVERAGE', 'LINE1:ds0#FF0000:Traffic'. |
Rückgabewert
xsize (Breite in Pixeln), ysize (Höhe in Pixeln) und calcpr (Array mit berechneten Druckzeilen aus PRINT/GPRINT-Anweisungen). Im Fehlerfall wird false zurückgegeben; die Fehlermeldung lässt sich mit rrd_error() abrufen.Beispiele
Einfache CPU-Auslastungs-Grafik erzeugen
<?php
// RRD-Grafik für die letzten 24 Stunden erstellen
$result = rrd_graph('/var/www/html/graphs/cpu.png', [
'--title=CPU-Auslastung',
'--start=-86400', // letzte 24 Stunden
'--end=now',
'--width=600',
'--height=200',
'--vertical-label=Prozent',
'DEF:cpu=/var/lib/rrd/cpu.rrd:usage:AVERAGE',
'LINE2:cpu#00AA00:CPU-Auslastung',
'GPRINT:cpu:AVERAGE:Durchschnitt\: %6.2lf %%',
]);
if ($result === false) {
echo 'Fehler: ' . rrd_error();
} else {
echo 'Grafik erzeugt: ' . $result['xsize'] . 'x' . $result['ysize'] . ' Pixel';
}Grafik direkt im Browser ausgeben (Ausgabepuffer)
<?php
// Grafik nicht in Datei, sondern direkt ausgeben
$result = rrd_graph('-', [
'--title=Netzwerktraffic',
'--start=-3600', // letzte Stunde
'--end=now',
'--width=400',
'--height=150',
'--imgformat=PNG',
'DEF:in=/var/lib/rrd/net.rrd:incoming:AVERAGE',
'DEF:out=/var/lib/rrd/net.rrd:outgoing:AVERAGE',
'AREA:in#0000FF:Eingehend',
'LINE1:out#FF0000:Ausgehend',
]);
if ($result === false) {
http_response_code(500);
die('Fehler: ' . rrd_error());
}
header('Content-Type: image/png');
echo $result['image']; // Bilddaten aus dem Puffer// Wichtig · Fallstricke
Sicherheitshinweis: Werden Optionen oder Pfade aus Benutzereingaben zusammengesetzt, müssen diese sorgfältig validiert und bereinigt werden, um Path-Traversal-Angriffe oder das Einschleusen von RRDtool-Direktiven zu verhindern. Niemals ungeprüfte Benutzerdaten direkt in das $options-Array übernehmen.
Abhängigkeit: Die Funktion steht nur zur Verfügung, wenn die PECL-Erweiterung rrd installiert ist (pecl install rrd) und die zugrunde liegende librrd auf dem System vorhanden ist. Ohne diese Voraussetzungen führt der Aufruf zu einem fatalen Fehler.
Ausgabepuffer (- als Dateiname): Bei Verwendung von '-' als Dateiname enthält das Ergebnis-Array zusätzlich den Schlüssel image mit den rohen Bilddaten. Diese Variante bietet sich an, wenn die Grafik dynamisch per HTTP ausgeliefert werden soll, ohne eine temporäre Datei anlegen zu müssen.
Im Fehlerfall gibt rrd_error() eine aussagekräftige Fehlermeldung zurück, die beim Debugging hilfreich ist.