MongoDB\Driver\Monitoring\LogSubscriber — Interface · PHP-Referenz

Signatur

interface MongoDB\Driver\Monitoring\LogSubscriber

Beschreibung

Das Interface MongoDB\Driver\Monitoring\LogSubscriber gehört zum Monitoring-System des offiziellen MongoDB PHP-Treibers. Klassen, die dieses Interface implementieren, können beim Treiber registriert werden und erhalten daraufhin interne Logmeldungen, z. B. über Verbindungsaufbau, Servererkennung (SDAM), Authentifizierung oder Fehlerzustände.

Um einen LogSubscriber zu aktivieren, muss die implementierende Klasse zusätzlich über MongoDB\Driver\Monitoring\addSubscriber() registriert werden. Ab diesem Zeitpunkt ruft der Treiber bei jeder relevanten Logmeldung die Methode log() auf und übergibt Schweregrad, Domäne sowie die eigentliche Nachricht als String.

Das Interface eignet sich besonders für die Integration mit bestehenden Logging-Frameworks (z. B. Monolog oder PSR-3-kompatiblen Loggern), für das Debugging von Verbindungsproblemen im Produktionsbetrieb oder für das detaillierte Nachvollziehen des internen Treiberverhaltens ohne externen Profiler.

Der Schweregrad wird als ganzzahlige Konstante übergeben, die den in der Treiberdokumentation definierten Log-Level-Konstanten (MongoDB\Driver\Monitoring\LogSubscriber::LEVEL_*) entspricht und mit Standard-Log-Prioritäten wie RFC 5424 (Syslog) vergleichbar ist.

Beispiele

Einfacher LogSubscriber zum Protokollieren in eine Datei

<?php
use MongoDB\Driver\Monitoring\LogSubscriber;
use MongoDB\Driver\Monitoring;

class FileLogger implements LogSubscriber
{
    private $handle;

    public function __construct(string $path)
    {
        $this->handle = fopen($path, 'a');
    }

    public function log(int $level, string $domain, string $message): void
    {
        $levelName = match ($level) {
            LogSubscriber::LEVEL_ERROR   => 'ERROR',
            LogSubscriber::LEVEL_CRITICAL => 'CRITICAL',
            LogSubscriber::LEVEL_WARNING => 'WARNING',
            LogSubscriber::LEVEL_MESSAGE => 'MESSAGE',
            LogSubscriber::LEVEL_INFO    => 'INFO',
            LogSubscriber::LEVEL_DEBUG   => 'DEBUG',
            default                      => 'UNKNOWN',
        };

        $line = sprintf(
            "[%s] [%s] [%s] %s\n",
            date('Y-m-d H:i:s'),
            $levelName,
            $domain,
            $message
        );
        fwrite($this->handle, $line);
    }
}

$logger = new FileLogger('/var/log/mongodb_driver.log');
MongoDB\Driver\Monitoring\addSubscriber($logger);

// Ab jetzt werden alle Treiber-Logs in die Datei geschrieben
$manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
$query   = new MongoDB\Driver\Query([]);
$cursor  = $manager->executeQuery('testdb.collection', $query);

PSR-3-kompatibler LogSubscriber mit Monolog

<?php
use MongoDB\Driver\Monitoring\LogSubscriber;
use MongoDB\Driver\Monitoring;
use Monolog\Logger;
use Monolog\Handler\StreamHandler;

class MonologAdapter implements LogSubscriber
{
    private Logger $logger;

    // Mapping MongoDB-Level -> PSR-3/Monolog-Level
    private const LEVEL_MAP = [
        LogSubscriber::LEVEL_ERROR    => Logger::ERROR,
        LogSubscriber::LEVEL_CRITICAL => Logger::CRITICAL,
        LogSubscriber::LEVEL_WARNING  => Logger::WARNING,
        LogSubscriber::LEVEL_MESSAGE  => Logger::NOTICE,
        LogSubscriber::LEVEL_INFO     => Logger::INFO,
        LogSubscriber::LEVEL_DEBUG    => Logger::DEBUG,
    ];

    public function __construct(Logger $logger)
    {
        $this->logger = $logger;
    }

    public function log(int $level, string $domain, string $message): void
    {
        $monologLevel = self::LEVEL_MAP[$level] ?? Logger::DEBUG;
        $this->logger->log($monologLevel, $message, ['domain' => $domain]);
    }
}

$monolog  = new Logger('mongodb');
$monolog->pushHandler(new StreamHandler('php://stdout', Logger::DEBUG));

$adapter = new MonologAdapter($monolog);
MongoDB\Driver\Monitoring\addSubscriber($adapter);

$manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');

// Wichtig · Fallstricke

Log-Level-Konstanten: Das Interface definiert folgende Klassenkonstanten für den Schweregrad (absteigend von kritisch zu verbose): LEVEL_ERROR, LEVEL_CRITICAL, LEVEL_WARNING, LEVEL_MESSAGE, LEVEL_INFO, LEVEL_DEBUG. Es empfiehlt sich, in Produktionsumgebungen nur Meldungen ab LEVEL_WARNING aufwärts zu persistieren, da LEVEL_DEBUG sehr viele interne Informationen erzeugt und die Performance beeinflussen kann.

Abmelden nicht vergessen: Wird ein Subscriber nicht mehr benötigt, sollte er mit MongoDB\Driver\Monitoring\removeSubscriber() wieder abgemeldet werden, um Memory-Leaks oder unerwünschte Seiteneffekte in langlaufenden Prozessen zu vermeiden.

Thread-Sicherheit / async: In PHP ist dies in der Regel unproblematisch, jedoch sollte die log()-Implementierung keine aufwändigen oder blockierenden Operationen (z. B. synchrone HTTP-Requests) ausführen, da sie synchron im Treiber-Callback aufgerufen wird.

Siehe auch

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