MongoDB\Driver\Monitoring\CommandStartedEvent — Klasse · PHP-Referenz

Signatur

class MongoDB\Driver\Monitoring\CommandStartedEvent

Beschreibung

MongoDB\Driver\Monitoring\CommandStartedEvent ist eine Klasse im MongoDB PHP-Treiber, die als Teil des Command-Monitorings verwendet wird. Sie wird instanziiert, wenn ein MongoDB-Befehl ausgeführt wird, und enthält Metainformationen über den gestarteten Befehl – z. B. den Befehlsnamen, die Zieldatenbank, den Hostnamen des Servers und eine eindeutige Anfrage-ID.

Um auf diese Ereignisse zu reagieren, muss ein Objekt implementiert werden, das das Interface MongoDB\Driver\Monitoring\CommandSubscriber implementiert und mit MongoDB\Driver\Monitoring\addSubscriber() registriert wird. Sobald ein Befehl gestartet wird, ruft der Treiber die Methode commandStarted() des Subscribers auf und übergibt ihr eine Instanz dieser Klasse.

Das Command-Monitoring ist besonders nützlich für Debugging, Logging, Performance-Messung und Tracing von Datenbankoperationen. Durch das Verknüpfen von CommandStartedEvent, CommandSucceededEvent und CommandFailedEvent über die getRequestId()-Methode lässt sich der vollständige Lebenszyklus eines Befehls nachverfolgen.

Beachte, dass diese Klasse keine öffentliche Konstruktormethode besitzt – Instanzen werden ausschließlich intern durch den MongoDB-Treiber erzeugt und an Subscriber-Methoden übergeben.

Beispiele

Command-Subscriber implementieren und Befehle 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
    {
        printf(
            "[START] Befehl '%s' auf Datenbank '%s' (RequestId: %s)\n",
            $event->getCommandName(),
            $event->getDatabaseName(),
            $event->getRequestId()
        );
        echo "Befehlsdetails: ";
        var_dump($event->getCommand());
    }

    public function commandSucceeded(CommandSucceededEvent $event): void
    {
        printf(
            "[SUCCESS] Befehl '%s' abgeschlossen in %d Mikrosekunden\n",
            $event->getCommandName(),
            $event->getDurationMicros()
        );
    }

    public function commandFailed(CommandFailedEvent $event): void
    {
        printf(
            "[FAILED] Befehl '%s' fehlgeschlagen: %s\n",
            $event->getCommandName(),
            $event->getError()->getMessage()
        );
    }
}

$logger = new CommandLogger();
MongoDB\Driver\Monitoring\addSubscriber($logger);

$manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
$query = new MongoDB\Driver\Query(['status' => 'aktiv']);
$cursor = $manager->executeQuery('testdb.benutzer', $query);

[START] Befehl 'find' auf Datenbank 'testdb' (RequestId: 1) Befehlsdetails: object(stdClass)#... ...

Befehlsdetails und Serverinformationen auslesen

<?php

use MongoDB\Driver\Monitoring\CommandSubscriber;
use MongoDB\Driver\Monitoring\CommandStartedEvent;
use MongoDB\Driver\Monitoring\CommandSucceededEvent;
use MongoDB\Driver\Monitoring\CommandFailedEvent;

class DetailedCommandMonitor implements CommandSubscriber
{
    public function commandStarted(CommandStartedEvent $event): void
    {
        $server = $event->getServer();
        echo "=== Befehl gestartet ===" . PHP_EOL;
        echo "Name:       " . $event->getCommandName() . PHP_EOL;
        echo "Datenbank:  " . $event->getDatabaseName() . PHP_EOL;
        echo "Server:     " . $server->getHost() . ':' . $server->getPort() . PHP_EOL;
        echo "Request-ID: " . $event->getRequestId() . PHP_EOL;
        echo "Opr.-ID:    " . $event->getOperationId() . PHP_EOL;
        echo "Service-ID: " . ($event->getServiceId() ?? 'N/A') . PHP_EOL;
    }

    public function commandSucceeded(CommandSucceededEvent $event): void {}
    public function commandFailed(CommandFailedEvent $event): void {}
}

$monitor = new DetailedCommandMonitor();
MongoDB\Driver\Monitoring\addSubscriber($monitor);

$manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
$bulk = new MongoDB\Driver\BulkWrite();
$bulk->insert(['name' => 'Testdokument', 'wert' => 42]);
$manager->executeBulkWrite('testdb.sammlung', $bulk);

=== Befehl gestartet === Name: insert Datenbank: testdb Server: localhost:27017 Request-ID: 1 Opr.-ID: 1 Service-ID: N/A

// Wichtig · Fallstricke

Kein öffentlicher Konstruktor: Instanzen von CommandStartedEvent werden ausschließlich intern durch den MongoDB-Treiber erstellt. Es ist nicht möglich, diese Klasse manuell zu instanziieren.

Sicherheit: Das Command-Monitoring kann sensible Daten aus MongoDB-Befehlen offenlegen (z. B. Abfrageparameter, Authentifizierungsdaten). Stelle sicher, dass Logs entsprechend gesichert sind und nicht öffentlich zugänglich werden.

Performance: Das Aktivieren von Monitoring-Subscribern hat Auswirkungen auf die Laufzeit. Für Produktionsumgebungen sollte das Monitoring nur gezielt und nicht pauschal für alle Befehle aktiviert werden.

Methoden der Klasse: getCommand(), getCommandName(), getDatabaseName(), getOperationId(), getRequestId(), getServer(), getServiceId().

Siehe auch

MongoDB\Driver\Monitoring\CommandSubscriber MongoDB\Driver\Monitoring\CommandSucceededEvent MongoDB\Driver\Monitoring\CommandFailedEvent MongoDB\Driver\Monitoring\addSubscriber MongoDB\Driver\Monitoring\removeSubscriber