Signatur
Beschreibung
Die Klasse MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent ist Teil des Server-Discovery-and-Monitoring-Systems (SDAM) des MongoDB PHP-Treibers. Sie wird erzeugt, wenn ein periodischer Heartbeat-Aufruf an einen MongoDB-Server fehlschlägt – etwa weil der Server nicht erreichbar ist oder eine Verbindung unterbrochen wurde.
Instanzen dieser Klasse werden ausschließlich vom Treiber selbst erstellt und an registrierte MongoDB\Driver\Monitoring\SDAMSubscriber-Implementierungen übergeben, konkret an die Methode serverHeartbeatFailed(). Entwickler können diese Klasse nicht manuell instanziieren.
Mithilfe dieses Ereignisses lassen sich Verbindungsprobleme zu MongoDB-Servern protokollieren, Monitoring-Systeme benachrichtigen oder automatische Fehlerbehandlungen implementieren. Das Ereignis enthält Informationen über den betroffenen Server, die Fehlerursache sowie die Dauer des fehlgeschlagenen Heartbeats.
Typische Einsatzgebiete sind das Logging von Infrastrukturproblemen, das Auslösen von Alarmen in Überwachungssystemen oder das Erfassen von Metriken über die Verfügbarkeit von Datenbankservern in produktiven Umgebungen.
Beispiele
Fehlgeschlagene Heartbeats mit einem SDAM-Subscriber protokollieren
<?php
use MongoDB\Driver\Monitoring\SDAMSubscriber;
use MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent;
use MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent;
use MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent;
use MongoDB\Driver\Monitoring\ServerClosedEvent;
use MongoDB\Driver\Monitoring\ServerOpeningEvent;
use MongoDB\Driver\Monitoring\ServerChangedEvent;
use MongoDB\Driver\Monitoring\TopologyClosedEvent;
use MongoDB\Driver\Monitoring\TopologyOpeningEvent;
use MongoDB\Driver\Monitoring\TopologyChangedEvent;
class HeartbeatLogger implements SDAMSubscriber
{
public function serverHeartbeatFailed(ServerHeartbeatFailedEvent $event): void
{
$host = $event->getHost();
$port = $event->getPort();
$durationMs = $event->getDurationMicros() / 1000;
$error = $event->getError();
error_log(sprintf(
'[HEARTBEAT FAILED] Server %s:%d nach %.2f ms — Fehler: %s',
$host,
$port,
$durationMs,
$error->getMessage()
));
}
public function serverHeartbeatStarted(ServerHeartbeatStartedEvent $event): void {}
public function serverHeartbeatSucceeded(ServerHeartbeatSucceededEvent $event): void {}
public function serverClosed(ServerClosedEvent $event): void {}
public function serverOpening(ServerOpeningEvent $event): void {}
public function serverChanged(ServerChangedEvent $event): void {}
public function topologyClosed(TopologyClosedEvent $event): void {}
public function topologyOpening(TopologyOpeningEvent $event): void {}
public function topologyChanged(TopologyChangedEvent $event): void {}
}
$subscriber = new HeartbeatLogger();
MongoDB\Driver\Monitoring\addSubscriber($subscriber);
$manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
// Ab hier werden fehlgeschlagene Heartbeats automatisch protokolliert.Informationen aus einem ServerHeartbeatFailedEvent auslesen
<?php
use MongoDB\Driver\Monitoring\SDAMSubscriber;
use MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent;
use MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent;
use MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent;
use MongoDB\Driver\Monitoring\ServerClosedEvent;
use MongoDB\Driver\Monitoring\ServerOpeningEvent;
use MongoDB\Driver\Monitoring\ServerChangedEvent;
use MongoDB\Driver\Monitoring\TopologyClosedEvent;
use MongoDB\Driver\Monitoring\TopologyOpeningEvent;
use MongoDB\Driver\Monitoring\TopologyChangedEvent;
class DetailedHeartbeatSubscriber implements SDAMSubscriber
{
public function serverHeartbeatFailed(ServerHeartbeatFailedEvent $event): void
{
// Serveradresse
echo 'Host: ' . $event->getHost() . PHP_EOL;
echo 'Port: ' . $event->getPort() . PHP_EOL;
// Dauer des fehlgeschlagenen Heartbeats in Mikrosekunden
echo 'Dauer (µs): ' . $event->getDurationMicros() . PHP_EOL;
// Fehler-Objekt (\Exception)
$error = $event->getError();
echo 'Fehlerklasse: ' . get_class($error) . PHP_EOL;
echo 'Fehlermeldung: ' . $error->getMessage() . PHP_EOL;
// Ob der Heartbeat über eine neue ("awaited") Verbindung lief
echo 'Awaited: ' . ($event->isAwaited() ? 'ja' : 'nein') . PHP_EOL;
}
public function serverHeartbeatStarted(ServerHeartbeatStartedEvent $event): void {}
public function serverHeartbeatSucceeded(ServerHeartbeatSucceededEvent $event): void {}
public function serverClosed(ServerClosedEvent $event): void {}
public function serverOpening(ServerOpeningEvent $event): void {}
public function serverChanged(ServerChangedEvent $event): void {}
public function topologyClosed(TopologyClosedEvent $event): void {}
public function topologyOpening(TopologyOpeningEvent $event): void {}
public function topologyChanged(TopologyChangedEvent $event): void {}
}
MongoDB\Driver\Monitoring\addSubscriber(new DetailedHeartbeatSubscriber());
$manager = new MongoDB\Driver\Manager('mongodb://unreachable-host:27017');// Wichtig · Fallstricke
Nicht instanziierbar: ServerHeartbeatFailedEvent kann nicht per new erzeugt werden. Instanzen werden ausschließlich intern vom Treiber erstellt und den Subscriber-Methoden übergeben.
Awaited Heartbeats: Seit MongoDB-Serverversion 4.4 und Treiber-Version 1.9 unterstützt der Treiber sogenannte Awaited Hello-Antworten (Streaming Monitoring Protocol). Die Methode isAwaited() gibt an, ob der Heartbeat über diesen Mechanismus lief. Fehlgeschlagene Awaited-Heartbeats können häufiger auftreten und erfordern eine gesonderte Behandlung.
Performance: Subscriber-Callbacks werden synchron ausgeführt und können die Treiber-Performance beeinflussen. Aufwändige Operationen (z. B. Datenbankzugriffe) in Subscriber-Methoden sollten vermieden werden.