Signatur
Beschreibung
rrd_fetch() ist Teil der RRD-Erweiterung (Round-Robin-Database) für PHP und ermöglicht es, gespeicherte Messwerte aus einer .rrd-Datei abzufragen. Die Funktion entspricht dem CLI-Befehl rrdtool fetch und gibt Zeitreihendaten für einen definierten Zeitraum und eine Konsolidierungsfunktion zurück.
Die Rückgabe enthält Metadaten (Start-/Endzeit, Schrittgröße) sowie die eigentlichen Datenpunkte aller in der RRD-Datei gespeicherten Datenquellen (Data Sources). Damit lassen sich Messwerte für Weiterverarbeitungen, Exporte oder eigene Diagramme abrufen, ohne auf externe Diagramm-Generierung angewiesen zu sein.
Typische Anwendungsfälle sind Monitoring-Systeme (z. B. Netzwerküberwachung), Performance-Tracking oder das Exportieren historischer Messdaten. Die gewünschte Konsolidierungsfunktion (AVERAGE, MIN, MAX, LAST) sowie der Zeitraum werden über das $options-Array gesteuert.
- AVERAGE: Durchschnittswert über den Konsolidierungszeitraum
- MIN: Minimalwert im Zeitraum
- MAX: Maximalwert im Zeitraum
- LAST: Letzter gespeicherter Wert im Zeitraum
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $filename Pflicht | string | Pfad zur RRD-Datei (.rrd), aus der die Daten gelesen werden sollen. |
|
| $options Pflicht | array | Array mit Optionen für den Fetch-Befehl. Typischerweise enthält es die Konsolidierungsfunktion (AVERAGE, MIN, MAX, LAST) sowie optional Zeitbereichsangaben mit --start und --end (als Unix-Timestamp oder relative Angaben wie -1h). Beispiel: ['AVERAGE', '--start', '-1h', '--end', 'now']. |
Rückgabewert
start (Unix-Timestamp des ersten Datenpunkts), end (Unix-Timestamp des letzten Datenpunkts), step (Schrittweite in Sekunden) und data (assoziatives Array der Datenquellen mit ihren Messwerten als numerisch indizierte Arrays). Bei einem Fehler wird false zurückgegeben; die Fehlermeldung kann mit rrd_error() abgerufen werden.Beispiele
Durchschnittswerte der letzten Stunde aus einer RRD-Datei lesen
<?php
$file = '/var/lib/rrd/traffic.rrd';
$options = [
'AVERAGE',
'--start', '-1h',
'--end', 'now',
];
$result = rrd_fetch($file, $options);
if ($result === false) {
echo 'Fehler: ' . rrd_error();
} else {
echo 'Start: ' . date('Y-m-d H:i:s', $result['start']) . PHP_EOL;
echo 'Ende: ' . date('Y-m-d H:i:s', $result['end']) . PHP_EOL;
echo 'Schritte: ' . $result['step'] . ' Sekunden' . PHP_EOL;
foreach ($result['data'] as $dsName => $values) {
echo PHP_EOL . "Datenquelle: $dsName" . PHP_EOL;
foreach ($values as $timestamp => $value) {
$time = date('H:i:s', $result['start'] + $timestamp * $result['step']);
printf(" %s => %s\n", $time, is_nan((float)$value) ? 'N/A' : number_format((float)$value, 2));
}
}
}Maximalwerte eines bestimmten Zeitraums abfragen
<?php
$file = '/var/lib/rrd/cpu.rrd';
$start = strtotime('2024-05-01 00:00:00');
$end = strtotime('2024-05-01 23:59:59');
$options = [
'MAX',
'--start', (string)$start,
'--end', (string)$end,
];
$result = rrd_fetch($file, $options);
if ($result === false) {
echo 'Fehler beim Lesen der RRD-Datei: ' . rrd_error();
} else {
foreach ($result['data'] as $dsName => $values) {
$max = max(array_filter($values, fn($v) => !is_nan((float)$v)));
echo "Maximaler Wert für '$dsName': " . number_format($max, 4) . PHP_EOL;
}
}// Wichtig · Fallstricke
Voraussetzung: Die PHP-Erweiterung rrd muss installiert und aktiviert sein (pecl install rrd bzw. Paketmanager). Sie ist nicht Teil der Standard-PHP-Distribution.
NaN-Werte: RRD-Datenbanken können unbekannte Werte (unknown) enthalten, die in PHP als NAN (Not a Number) zurückgegeben werden. Vor arithmetischen Operationen sollte daher stets is_nan() geprüft werden.
Zeitzonenproblematik: RRD-Zeitstempel sind immer UTC-basiert. Bei der Ausgabe bzw. Weiterverarbeitung ist auf die korrekte Zeitzonen-Konvertierung zu achten.
Leistung: Bei sehr großen RRD-Dateien oder langen Zeiträumen mit kleiner Schrittgröße kann die zurückgegebene Datenmenge sehr groß werden. Ggf. den Zeitraum oder die Auflösung einschränken.