Signatur
Beschreibung
rrd_xport() liest Zeitreihendaten aus RRD-Datenbanken (Round Robin Database) und exportiert sie als strukturiertes PHP-Array. Die Funktion entspricht dem Kommandozeilenwerkzeug rrdtool xport und eignet sich besonders dazu, Daten aus mehreren RRD-Quellen zu kombinieren, zeitlich zu interpolieren und für externe Systeme (z. B. XML-Export, JavaScript-Graphen) aufzubereiten.
Die Optionen werden als indiziertes Array von Strings übergeben, wobei jeder Eintrag einem Parameter entspricht, den man auch an rrdtool xport auf der Kommandozeile übergeben würde. Typische Parameter sind --start, --end, --step, DEF:-Definitionen zur Anbindung von RRD-Dateien sowie XPORT:-Anweisungen, die festlegen, welche berechneten Werte exportiert werden sollen.
Das zurückgegebene Array enthält Metadaten (wie Start- und Endzeit, Schrittweite, Spaltenüberschriften) sowie die eigentlichen Datenpunkte. Es ist besonders nützlich, wenn aggregierte Werte aus mehreren RRD-Dateien in einer einzigen Abfrage zusammengeführt werden sollen, ohne eine SVG/PNG-Grafik rendern zu müssen.
Die Funktion gehört zur PECL-Erweiterung rrd und steht nur zur Verfügung, wenn diese installiert und aktiviert ist. RRD-Datenbanken werden typischerweise für Monitoring-Systeme (z. B. Cacti, Nagios) eingesetzt.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $options Pflicht | array | Indiziertes Array von Zeichenketten, das die Export-Optionen enthält. Jeder Eintrag entspricht einem Parameter des rrdtool xport-Kommandos, z. B. '--start', '--end', 'DEF:ds0=datei.rrd:AVERAGE' oder 'XPORT:ds0:Bezeichnung'. |
Rückgabewert
start (Unix-Timestamp), end (Unix-Timestamp), step (Schrittweite in Sekunden), legend (Array der Spaltenbezeichnungen) und data (zweidimensionales Array der exportierten Datenpunkte). Bei einem Fehler wird false zurückgegeben; mit rrd_error() lässt sich die Fehlermeldung abfragen.Beispiele
Einfacher Export von Netzwerk-Traffic aus einer RRD-Datei
<?php
// RRD-Datei mit Netzwerk-Traffi-Daten exportieren
$options = [
'--start', '-1h',
'--end', 'now',
'--step', '300',
'DEF:inBytes=network.rrd:ifInOctets:AVERAGE',
'DEF:outBytes=network.rrd:ifOutOctets:AVERAGE',
'XPORT:inBytes:Eingehend',
'XPORT:outBytes:Ausgehend',
];
$result = rrd_xport($options);
if ($result === false) {
echo 'Fehler: ' . rrd_error();
} else {
echo 'Start: ' . date('H:i:s', $result['start']) . PHP_EOL;
echo 'Ende: ' . date('H:i:s', $result['end']) . PHP_EOL;
echo 'Schritt: ' . $result['step'] . ' Sekunden' . PHP_EOL;
echo 'Spalten: ' . implode(', ', $result['legend']) . PHP_EOL;
foreach ($result['data'] as $timestamp => $values) {
printf(
"%s IN: %.2f Bytes/s OUT: %.2f Bytes/s\n",
date('H:i:s', $timestamp),
$values[0] ?? 0,
$values[1] ?? 0
);
}
}Aggregierter Export aus mehreren RRD-Dateien (CDEF)
<?php
// Zwei Server-Last-Werte addieren und als Gesamtwert exportieren
$options = [
'--start', strval(strtotime('-24 hours')),
'--end', strval(time()),
'--step', '3600',
'DEF:load1=server1.rrd:load:AVERAGE',
'DEF:load2=server2.rrd:load:AVERAGE',
'CDEF:totalLoad=load1,load2,+',
'XPORT:load1:Server1-Load',
'XPORT:load2:Server2-Load',
'XPORT:totalLoad:Gesamt-Load',
];
$result = rrd_xport($options);
if ($result === false) {
die('Export fehlgeschlagen: ' . rrd_error());
}
// Daten als JSON für ein Frontend-Chart aufbereiten
$chartData = [];
foreach ($result['data'] as $ts => $row) {
$chartData[] = [
'time' => $ts,
'load1' => $row[0],
'load2' => $row[1],
'total' => $row[2],
];
}
header('Content-Type: application/json');
echo json_encode(['legend' => $result['legend'], 'rows' => $chartData]);// Wichtig · Fallstricke
PECL-Erweiterung erforderlich: rrd_xport() ist Teil der PECL-Erweiterung rrd und steht nicht in der PHP-Standardinstallation zur Verfügung. Die Erweiterung muss separat installiert werden (pecl install rrd).
Fehlerbehandlung: Bei ungültigen Optionen oder nicht vorhandenen RRD-Dateien gibt die Funktion false zurück. Eine ausführlichere Fehlermeldung lässt sich immer mit rrd_error() abrufen.
Zeitstempel: Die Schlüssel des data-Arrays sind Unix-Timestamps. Achte darauf, dass --start und --end als Unix-Timestamps oder relative Angaben (z. B. '-1h', 'now') übergeben werden – Formate, die rrdtool direkt versteht.
NaN-Werte: Fehlende oder ungültige Messpunkte in der RRD-Datenbank werden als PHP-NAN (Not a Number) im data-Array geliefert. Vor arithmetischen Operationen sollte daher is_nan() geprüft werden.