Signatur
Beschreibung
Die Klasse MongoDB\Driver\Monitoring\CommandFailedEvent kapselt alle Informationen zu einem fehlgeschlagenen MongoDB-Befehl und wird im Rahmen des Command Monitoring an registrierte Subscriber übergeben. Implementierungen von MongoDB\Driver\Monitoring\CommandSubscriber erhalten eine Instanz dieser Klasse in ihrer Methode commandFailed().
Ein CommandFailedEvent entsteht immer dann, wenn der MongoDB-Treiber eine Fehlerantwort vom Server erhält oder ein Netzwerkfehler auftritt, nachdem ein Befehl gesendet wurde. Es enthält unter anderem den Befehlsnamen, die Dauer der Ausführung, das Fehler-Objekt sowie Korrelations-IDs, um das Ereignis mit dem ursprünglichen CommandStartedEvent zu verknüpfen.
Diese Klasse ist besonders nützlich für Logging, Tracing und Performance-Monitoring von Datenbankoperationen in produktiven Anwendungen. Da die Klasse als final deklariert ist, kann sie nicht erweitert werden; Instanzen werden ausschließlich vom Treiber intern erzeugt.
- Befehlsname und Server-Informationen für Logging nutzbar
- Fehlerobjekt für detaillierte Fehleranalyse verfügbar
- Ausführungsdauer für Performance-Auswertungen messbar
Beispiele
CommandFailedEvent in einem CommandSubscriber loggen
<?php
use MongoDB\Driver\Monitoring\CommandSubscriber;
use MongoDB\Driver\Monitoring\CommandStartedEvent;
use MongoDB\Driver\Monitoring\CommandSucceededEvent;
use MongoDB\Driver\Monitoring\CommandFailedEvent;
class CommandLogger implements CommandSubscriber
{
public function commandStarted(CommandStartedEvent $event): void
{
// Wird beim Start eines Befehls aufgerufen
}
public function commandSucceeded(CommandSucceededEvent $event): void
{
// Wird bei Erfolg aufgerufen
}
public function commandFailed(CommandFailedEvent $event): void
{
printf(
"[FEHLER] Befehl '%s' auf Server '%s' fehlgeschlagen nach %.4f Sekunden.\n",
$event->getCommandName(),
$event->getHost() . ':' . $event->getPort(),
$event->getDurationMicros() / 1_000_000
);
printf("Fehlerklasse: %s\n", get_class($event->getError()));
printf("Fehlermeldung: %s\n", $event->getError()->getMessage());
printf("Operation-ID: %d, Request-ID: %d\n",
$event->getOperationId(),
$event->getRequestId()
);
}
}
$manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
MongoDB\Driver\Monitoring\addSubscriber(new CommandLogger());
try {
// Absichtlich ungültige Query erzeugen
$command = new MongoDB\Driver\Command(['invalidCommand' => 1]);
$manager->executeCommand('test', $command);
} catch (MongoDB\Driver\Exception\Exception $e) {
// Fehler wurde bereits im Subscriber geloggt
}Fehlerereignisse in einer Datenbank-Tracing-Klasse sammeln
<?php
use MongoDB\Driver\Monitoring\CommandSubscriber;
use MongoDB\Driver\Monitoring\CommandStartedEvent;
use MongoDB\Driver\Monitoring\CommandSucceededEvent;
use MongoDB\Driver\Monitoring\CommandFailedEvent;
class CommandTracer implements CommandSubscriber
{
private array $failedCommands = [];
public function commandStarted(CommandStartedEvent $event): void {}
public function commandSucceeded(CommandSucceededEvent $event): void {}
public function commandFailed(CommandFailedEvent $event): void
{
$this->failedCommands[] = [
'command' => $event->getCommandName(),
'durationMs' => $event->getDurationMicros() / 1000,
'error' => $event->getError()->getMessage(),
'requestId' => $event->getRequestId(),
'operationId' => $event->getOperationId(),
'server' => $event->getHost() . ':' . $event->getPort(),
'serviceId' => $event->getServiceId(),
];
}
public function getFailedCommands(): array
{
return $this->failedCommands;
}
}
$tracer = new CommandTracer();
MongoDB\Driver\Monitoring\addSubscriber($tracer);
// ... Datenbankoperationen durchführen ...
$failures = $tracer->getFailedCommands();
foreach ($failures as $failure) {
echo sprintf(
"Befehl: %s | Dauer: %.2f ms | Fehler: %s\n",
$failure['command'],
$failure['durationMs'],
$failure['error']
);
}// Wichtig · Fallstricke
Wichtig: Instanzen von CommandFailedEvent können nicht manuell erzeugt werden – sie werden ausschließlich intern vom PHP-MongoDB-Treiber erstellt und an CommandSubscriber::commandFailed() übergeben.
Da die Klasse final ist, ist eine Vererbung nicht möglich. Das Command Monitoring kann die Anwendungsperformance leicht beeinflussen; in Produktionsumgebungen sollte der Subscriber so schlank wie möglich gehalten werden, um den Overhead zu minimieren.
getServiceId() gibt null zurück, wenn das verbundene Deployment keine Load Balancer einsetzt. Die Methode steht erst ab Treiber-Version 1.11.0 zur Verfügung.