Signatur
Beschreibung
Die Klasse MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent gehört zum SDAM-Monitoring (Server Discovery and Monitoring) des MongoDB PHP-Treibers. Sie wird an registrierte MongoDB\Driver\Monitoring\SDAMSubscriber-Implementierungen übergeben, wenn der Treiber einen neuen Heartbeat-Vorgang gegenüber einem MongoDB-Server initiiert.
Heartbeats sind periodische Prüfungen, die der Treiber durchführt, um den Zustand und die Topologie der verbundenen Server zu überwachen. Das ServerHeartbeatStartedEvent markiert dabei den Zeitpunkt, zu dem dieser Vorgang beginnt – noch bevor eine Antwort vom Server empfangen wurde. Zusammen mit ServerHeartbeatSucceededEvent und ServerHeartbeatFailedEvent lässt sich so die vollständige Dauer und das Ergebnis eines Heartbeat-Zyklus nachverfolgen.
Objekte dieser Klasse können nicht manuell instanziiert werden. Sie werden ausschließlich intern durch den Treiber erzeugt und an die entsprechenden Monitoring-Callbacks weitergereicht. Dies erlaubt es Entwicklern, Verbindungsüberwachung, Diagnosewerkzeuge oder benutzerdefiniertes Logging zu implementieren, ohne in die Treiberinterna eingreifen zu müssen.
- Verwende diese Klasse innerhalb einer
SDAMSubscriber-Implementierung, um Heartbeat-Ereignisse zu verarbeiten. - Kombiniere sie mit
ServerHeartbeatSucceededEventundServerHeartbeatFailedEvent, um vollständige Latenz-Metriken zu erfassen.
Beispiele
Heartbeat-Ereignisse mit einem SDAMSubscriber protokollieren
<?php
use MongoDB\Driver\Monitoring\SDAMSubscriber;
use MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent;
use MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent;
use MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent;
use MongoDB\Driver\Monitoring\ServerChangedEvent;
use MongoDB\Driver\Monitoring\ServerClosedEvent;
use MongoDB\Driver\Monitoring\ServerOpeningEvent;
use MongoDB\Driver\Monitoring\TopologyChangedEvent;
use MongoDB\Driver\Monitoring\TopologyClosedEvent;
use MongoDB\Driver\Monitoring\TopologyOpeningEvent;
class HeartbeatLogger implements SDAMSubscriber
{
public function serverHeartbeatStarted(ServerHeartbeatStartedEvent $event): void
{
printf(
"[%s] Heartbeat gestartet für Host: %s:%d (awaited: %s)\n",
date('H:i:s'),
$event->getHost(),
$event->getPort(),
$event->isAwaited() ? 'ja' : 'nein'
);
}
public function serverHeartbeatSucceeded(ServerHeartbeatSucceededEvent $event): void
{
printf("[%s] Heartbeat erfolgreich (%.2f ms)\n", date('H:i:s'), $event->getDurationMicros() / 1000);
}
public function serverHeartbeatFailed(ServerHeartbeatFailedEvent $event): void
{
printf("[%s] Heartbeat fehlgeschlagen: %s\n", date('H:i:s'), $event->getError()->getMessage());
}
public function serverChanged(ServerChangedEvent $event): void {}
public function serverClosed(ServerClosedEvent $event): void {}
public function serverOpening(ServerOpeningEvent $event): void {}
public function topologyChanged(TopologyChangedEvent $event): void {}
public function topologyClosed(TopologyClosedEvent $event): void {}
public function topologyOpening(TopologyOpeningEvent $event): void {}
}
$subscriber = new HeartbeatLogger();
MongoDB\Driver\Monitoring\addSubscriber($subscriber);
$manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
$query = new MongoDB\Driver\Query([]);
$cursor = $manager->executeQuery('test.collection', $query);
Host und Port eines gestarteten Heartbeats auslesen
<?php
use MongoDB\Driver\Monitoring\SDAMSubscriber;
use MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent;
class SimpleHeartbeatLogger implements SDAMSubscriber
{
private array $startedAt = [];
public function serverHeartbeatStarted(ServerHeartbeatStartedEvent $event): void
{
$key = $event->getHost() . ':' . $event->getPort();
$this->startedAt[$key] = microtime(true);
echo "Heartbeat gestartet für: {$key}" . PHP_EOL;
echo "Awaited (streaming): " . ($event->isAwaited() ? 'ja' : 'nein') . PHP_EOL;
}
// Weitere Interface-Methoden müssen ebenfalls implementiert werden (hier weggelassen)
public function serverHeartbeatSucceeded(\MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent $e): void {}
public function serverHeartbeatFailed(\MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent $e): void {}
public function serverChanged(\MongoDB\Driver\Monitoring\ServerChangedEvent $e): void {}
public function serverClosed(\MongoDB\Driver\Monitoring\ServerClosedEvent $e): void {}
public function serverOpening(\MongoDB\Driver\Monitoring\ServerOpeningEvent $e): void {}
public function topologyChanged(\MongoDB\Driver\Monitoring\TopologyChangedEvent $e): void {}
public function topologyClosed(\MongoDB\Driver\Monitoring\TopologyClosedEvent $e): void {}
public function topologyOpening(\MongoDB\Driver\Monitoring\TopologyOpeningEvent $e): void {}
}
// Wichtig · Fallstricke
Objekte vom Typ ServerHeartbeatStartedEvent können nicht manuell instanziiert werden – der Konstruktor ist nicht öffentlich zugänglich. Instanzen werden ausschließlich durch den MongoDB-Treiber erzeugt.
Die Methode isAwaited() gibt true zurück, wenn der Heartbeat im Rahmen des Streaming-Protokolls (MongoDB 4.4+) ausgeführt wird. Dies unterscheidet sich vom klassischen polling-basierten Heartbeat-Mechanismus und sollte bei der Interpretation der Latenzdaten berücksichtigt werden.
Subscriber müssen alle Methoden des SDAMSubscriber-Interface implementieren, auch wenn einzelne Ereignisse nicht benötigt werden – andernfalls führt dies zu einem Error zur Laufzeit.