Log Driver Events

Overview

In this guide, you can learn how to use the PHP library to set up and configure logging. Logging allows you to receive information about database operations, server connections, errors, and other events that occur while your application runs.

The PHP library supports Psr\Log\LoggerInterface, a PSR-3 logger interface that configures your application to receive log messages. You can register one or more Psr\Log\LoggerInterface objects to send messages to the logger. The PHP library is built on top of the MongoDB C driver and the PHP extension, so the logger receives event notifications from both components.

Configure Logging

To configure your application to receive messages about driver events, create a logger class that implements the Psr\Log\LoggerInterface interface. Then, use the MongoDB\add_logger() function to register your logger.

After registering a logger, the PHP library generates log messages as array values that resemble the following sample message:

[0] => Array
    (
       [0] => debug
       [1] => Created client with hash: ...
       [2] => PHONGO
    )

The sample log message includes the following information:

Log level: Indicates the severity of the message. The debug level corresponds to standard driver activities. To view a list of possible levels, see PSR\Log\LogLevel.
Message: Describes the logged event, which signals the creation of a new client.
Domain string: Specifies the driver component that emitted the log message. The PHONGO domain indicates that the PHP extension generated the event.

Example

To implement Psr\Log\LoggerInterface, you can create a class that extends the Psr\Log\AbstractLogger class. AbstractLogger implements LoggerInterface and a generic log() method, which receives log messages at each severity level.

This example performs the following actions:

Creates a logger called MyLogger that extends the AbstractLogger class and records the log level, description, and domain of each event
Registers the logger
Prints each log message

class MyLogger extends AbstractLogger
{
    public array $logs = [];
    public function log($level, $message, array $context = []): void
    {
        $this->logs[] = [$level, $message, $context['domain']];
    }
}
$logger = new MyLogger();
add_logger($logger);
print_r($logger->logs);

Write Custom Log Messages

You can generate custom log messages by using the PsrLogAdapter::writeLog() function. This function allows you to write directly to the logger and can help with application monitoring and debugging. Pass the severity level, domain, and description as parameters to writeLog().

The following example writes log messages that have warning and critical severity levels to the logger:

PsrLogAdapter::writeLog(PsrLogAdapter::WARN, 'domain1', 'This is a warning message');
PsrLogAdapter::writeLog(PsrLogAdapter::CRITICAL, 'domain2', 'This is a critical message');
print_r($logger->logs);

Array
(
    [0] => Array
        (
            [0] => warning
            [1] => This is a warning message
            [2] => domain1
        )
    [1] => Array
        (
            [0] => critical
            [1] => This is a critical message
            [2] => domain2
        )
)

Remove a Logger

To unregister a logger, pass your logger object as a parameter to the MongoDB\remove_logger() function. After calling this function, your logger no longer receives log messages about your application.

The following example unregisters a logger:

remove_logger($logger);

Additional Information

To learn more about the PSR-3 logger, see PSR-3: Logger Interface in the PHP-FIG documentation.

API Documentation

To learn more about the PHP library methods discussed in this guide, see the following API documentation:

To learn more about how the underlying C driver generates log messages, see Logging in the libmongoc API documentation.

Back

Change Streams

Security