Signatur
Beschreibung
rrd_update schreibt neue Datenpunkte in eine bestehende RRD-Datei (Round Robin Database). RRD ist ein System zur Speicherung und Visualisierung von Zeitreihendaten, wie sie z. B. bei Netzwerk-Monitoring, Server-Metriken oder Sensordaten anfallen. Die Funktion ist das PHP-Äquivalent zum Kommandozeilenbefehl rrdtool update.
Der Parameter $options enthält ein Array von Optionsstrings, die dem RRD-Tool übergeben werden. Typischerweise enthält dieses Array den Zeitstempel und die dazugehörigen Datenwerte im Format timestamp:wert1:wert2:.... Der Zeitstempel kann ein Unix-Timestamp sein oder das Sonderzeichen N für den aktuellen Zeitpunkt.
Die Funktion setzt die PHP-Erweiterung rrd (PECL) voraus, die auf dem System installiert und aktiviert sein muss. Sie ist besonders nützlich in Monitoring-Skripten, Cron-Jobs oder Datenerfassungs-Daemons, die regelmäßig Messwerte in RRD-Datenbanken persistieren müssen.
Im Fehlerfall gibt die Funktion false zurück; mit rrd_error() kann die genaue Fehlermeldung abgerufen werden. Es ist daher empfehlenswert, den Rückgabewert stets zu prüfen und bei Fehler die Fehlermeldung zu protokollieren.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $filename Pflicht | string | Pfad zur RRD-Datei, die aktualisiert werden soll. Die Datei muss zuvor mit rrd_create angelegt worden sein. |
|
| $options Pflicht | array | Array von Optionsstrings für den Update-Befehl. Typischer Eintrag ist ein String der Form 'timestamp:wert1:wert2', wobei N als Timestamp den aktuellen Unix-Zeitstempel bedeutet. Mehrere Zeitpunkte können als mehrere Array-Einträge übergeben werden. |
Rückgabewert
true bei Erfolg zurück, oder false im Fehlerfall. Mit rrd_error() kann nach einem Fehler die genaue Fehlermeldung abgerufen werden.Beispiele
Einfachen Datenpunkt in eine RRD-Datei schreiben
<?php
// RRD-Datei mit einem Data Source 'temperature' aktualisieren
$rrdFile = '/var/rrd/temperature.rrd';
// Aktuellen Zeitstempel + Messwert übergeben
// Format: 'timestamp:wert' — N steht für "jetzt"
$options = ['N:23.5'];
$result = rrd_update($rrdFile, $options);
if ($result === false) {
$error = rrd_error();
error_log('rrd_update fehlgeschlagen: ' . $error);
} else {
echo 'RRD-Datei erfolgreich aktualisiert.';
}Mehrere Datenpunkte mit explizitem Zeitstempel einfügen
<?php
// Mehrere historische Messwerte in eine RRD-Datei schreiben
// RRD-Datei hat zwei Data Sources: 'in' und 'out' (z. B. Netzwerktraffic)
$rrdFile = '/var/rrd/network.rrd';
$baseTime = time() - 300; // Beginne 5 Minuten in der Vergangenheit
$options = [
($baseTime + 0) . ':1024:512',
($baseTime + 60) . ':2048:1024',
($baseTime + 120) . ':1536:768',
($baseTime + 180) . ':3072:1500',
($baseTime + 240) . ':2560:1280',
];
$result = rrd_update($rrdFile, $options);
if ($result === false) {
echo 'Fehler: ' . rrd_error();
} else {
echo 'Alle ' . count($options) . ' Datenpunkte erfolgreich geschrieben.';
}// Wichtig · Fallstricke
Zeitstempel-Reihenfolge: RRD verlangt, dass Datenpunkte in aufsteigender Zeitreihenfolge eingefügt werden. Wird ein Zeitstempel übergeben, der älter als der zuletzt gespeicherte ist, schlägt der Update fehl (illegal attempt to update using time ... when last update time is ...).
PECL-Erweiterung: rrd_update gehört zur PECL-Erweiterung rrd und ist nicht im PHP-Standard-Kern enthalten. Installation über pecl install rrd und Aktivierung in der php.ini erforderlich.
Unbekannte Werte: Wenn ein Messwert für einen Zeitpunkt nicht verfügbar ist, kann statt eines numerischen Werts U (Unknown) übergeben werden, z. B. 'N:U:512'.
Fehlerbehandlung: Der Rückgabewert sollte stets geprüft werden. Im Fehlerfall liefert rrd_error() eine beschreibende Meldung, die für Logging und Debugging hilfreich ist.