MongoDB\Driver\Monitoring\addSubscriber — Funktion · PHP-Referenz

Signatur

MongoDB\Driver\Monitoring\addSubscriber(MongoDB\Driver\Monitoring\Subscriber $subscriber): void

Beschreibung

MongoDB\Driver\Monitoring\addSubscriber() registriert ein Subscriber-Objekt global im MongoDB-PHP-Treiber. Nach der Registrierung empfängt der Abonnent alle entsprechenden Monitoring-Ereignisse – beispielsweise Command-, SDAM- (Server Discovery and Monitoring) oder Log-Ereignisse – für alle Manager-Instanzen innerhalb der Anwendung.

Typische Einsatzgebiete sind Performance-Monitoring (z. B. Messung der Ausführungszeiten von Abfragen), Debugging (Protokollierung aller ausgeführten MongoDB-Befehle) sowie Application-Performance-Monitoring (APM). Ein Abonnent muss mindestens eines der Interfaces CommandSubscriber, SDAMSubscriber oder LogSubscriber implementieren.

Im Unterschied zur Methode MongoDB\Driver\Manager::addSubscriber(), die nur Ereignisse eines bestimmten Manager-Objekts liefert, gilt ein über addSubscriber() registrierter Abonnent global für alle Manager-Instanzen der Anwendung. Dies ist besonders in Frameworks oder Middleware sinnvoll, wo mehrere Manager-Instanzen existieren können.

Ein Abonnent kann mit MongoDB\Driver\Monitoring\removeSubscriber() wieder abgemeldet werden. Das mehrfache Registrieren desselben Objekts führt dazu, dass Ereignisse mehrfach ausgeliefert werden.

Parameter

Name	Typ	Default	Beschreibung
$subscriber Pflicht	MongoDB\Driver\Monitoring\Subscriber		Ein Objekt, das das `MongoDB\Driver\Monitoring\Subscriber`-Interface implementiert. Konkret muss es mindestens eines der Sub-Interfaces (`CommandSubscriber`, `SDAMSubscriber` oder `LogSubscriber`) implementieren, damit es sinnvolle Ereignisse empfängt.

Rückgabewert

Typ

void

Beschreibung

Die Funktion gibt keinen Wert zurück.

Beispiele

Einfacher Command-Logger mit globalem Abonnenten

<?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
    {
        echo sprintf(
            "[START] Befehl '%s' auf DB '%s' (requestId: %d)\n",
            $event->getCommandName(),
            $event->getDatabaseName(),
            $event->getRequestId()
        );
    }

    public function commandSucceeded(CommandSucceededEvent $event): void
    {
        echo sprintf(
            "[OK]    Befehl '%s' abgeschlossen in %.2f ms\n",
            $event->getCommandName(),
            $event->getDurationMicros() / 1000
        );
    }

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

// Globalen Abonnenten registrieren
$logger = new CommandLogger();
MongoDB\Driver\Monitoring\addSubscriber($logger);

// Ab hier werden alle MongoDB-Befehle protokolliert
$manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
$query = new MongoDB\Driver\Query(['status' => 'active']);
$cursor = $manager->executeQuery('mydb.users', $query);

[START] Befehl 'find' auf DB 'mydb' (requestId: 1) [OK] Befehl 'find' abgeschlossen in 1.23 ms

Abonnent nach der Verwendung wieder abmelden

<?php
use MongoDB\Driver\Monitoring\CommandSubscriber;
use MongoDB\Driver\Monitoring\CommandStartedEvent;
use MongoDB\Driver\Monitoring\CommandSucceededEvent;
use MongoDB\Driver\Monitoring\CommandFailedEvent;

class MinimalLogger implements CommandSubscriber
{
    private array $log = [];

    public function commandStarted(CommandStartedEvent $event): void
    {
        $this->log[] = $event->getCommandName();
    }

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

    public function getLog(): array
    {
        return $this->log;
    }
}

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

$manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
$bulk = new MongoDB\Driver\BulkWrite();
$bulk->insert(['name' => 'Test']);
$manager->executeBulkWrite('mydb.test', $bulk);

// Abonnenten wieder abmelden – keine weiteren Ereignisse
MongoDB\Driver\Monitoring\removeSubscriber($logger);

print_r($logger->getLog());

Array ( [0] => insert )

// Wichtig · Fallstricke

Mehrfache Registrierung: Wird dasselbe Objekt mehrfach mit addSubscriber() registriert, erhält es Ereignisse entsprechend oft. Dies kann zu doppelten Logeinträgen oder verfälschten Metriken führen. Es empfiehlt sich, die Registrierung nur einmal – z. B. beim Bootstrap der Anwendung – durchzuführen.

Performance: Jeder registrierte Abonnent wird bei jedem Monitoring-Ereignis aufgerufen. In produktiven Umgebungen mit hohem Query-Aufkommen kann eine aufwändige Verarbeitung in der Callback-Methode zu Latenzen führen. Asynchrone Verarbeitung oder gepuffertes Logging sind hier empfehlenswert.

Globale vs. Manager-spezifische Abonnenten: Für Manager-spezifisches Monitoring sollte stattdessen MongoDB\Driver\Manager::addSubscriber() verwendet werden, um ungewollte Querverbindungen zwischen verschiedenen Datenbankverbindungen zu vermeiden.

Siehe auch

MongoDB\Driver\Monitoring\removeSubscriber MongoDB\Driver\Manager::addSubscriber MongoDB\Driver\Monitoring\CommandSubscriber MongoDB\Driver\Monitoring\SDAMSubscriber MongoDB\Driver\Monitoring\Subscriber