diff --git a/source/includes/monitoring-logging/logging.php b/source/includes/monitoring-logging/logging.php new file mode 100644 index 00000000..8a97b794 --- /dev/null +++ b/source/includes/monitoring-logging/logging.php @@ -0,0 +1,38 @@ +pushHandler(new StreamHandler(__DIR__ . '/mongodb.log', Logger::DEBUG)); + +MongoDB\add_logger($logger); +// end-monolog-logger + +// start-custom-logger +use Psr\Log\AbstractLogger; +use Psr\Log\LoggerInterface; +use Psr\Log\LogLevel; +use MongoDB\PsrLogAdapter; + +class MyLogger extends AbstractLogger +{ + public array $logs = []; + + public function log($level, $message, array $context = []): void + { + $this->logs[] = [$level, $message, $context['domain']]; + } +} + +$customLogger = new MyLogger(); +MongoDB\add_logger($customLogger); +print_r($customLogger->logs); +// end-custom-logger + +// start-remove-logger +MongoDB\remove_logger($logger); +// end-remove-logger diff --git a/source/includes/monitoring/monitor.php b/source/includes/monitoring-logging/monitor.php similarity index 100% rename from source/includes/monitoring/monitor.php rename to source/includes/monitoring-logging/monitor.php diff --git a/source/monitoring-logging.txt b/source/monitoring-logging.txt index ff902d8a..f18906d8 100644 --- a/source/monitoring-logging.txt +++ b/source/monitoring-logging.txt @@ -10,9 +10,14 @@ Monitoring and Logging Monitoring Change Streams + Logging .. /monitoring/command-monitoring .. /monitoring/connection-monitoring - :ref:`Monitor Application Events `: Monitor changes - in your application \ No newline at end of file + in your application +- :ref:`Logging `: Configure logging to receive messages + about {+library-short+} events +- :ref:`Change Streams `: Monitor data changes in + your application diff --git a/source/monitoring-logging/logging.txt b/source/monitoring-logging/logging.txt new file mode 100644 index 00000000..7eecd8a9 --- /dev/null +++ b/source/monitoring-logging/logging.txt @@ -0,0 +1,160 @@ +.. _php-logging: + +================= +Log Driver Events +================= + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: debugging, printing + +Overview +-------- + +In this guide, you can learn how to use the {+library-short+} 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 {+library-short+} supports `Psr\\Log\\LoggerInterface +`__, a PSR-3 +logger interface that configures your application to receive log messages. +You can register one or more instances of a class that implements +``Psr\Log\LoggerInterface`` to receive log messages. The {+library-short+} is built on top of +the MongoDB C driver and the {+extension-short+}, so the logger receives event notifications +from each component. + +Configure Logging +----------------- + +To configure your application to receive messages about driver events, +create an instance of 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 {+library-short+} generates log messages +that resemble the following sample message: + +.. code-block:: none + :copyable: false + + [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 {+extension-short+} generated the event. + +.. note:: Log Message Format + + The preceding example shows a log message stored in an array. However, + the format of your log messages might differ depending on your logging + implementation. + +Create a Monolog Logger +~~~~~~~~~~~~~~~~~~~~~~~ + +You can use `Monolog `__, a +PHP logging library, to configure logging in your application. Monolog simplifies +logging configuration by providing a ``Monolog\Logger`` class. This class implements +the ``Psr\Log\LoggerInterface`` interface and provides handlers that direct logs to +specified locations. + +To use Monolog, install the ``monolog/monolog`` package by running +the following command: + +.. code-block:: shell + + composer require monolog/monolog + +Then, you can create a logger by defining a ``Monolog\Logger`` object +and registering it with the {+library-short+}. + +This example performs the following actions: + +- Creates a Monolog logger called ``mongodb-logger`` +- Uses a handler to write all logs with a severity of ``debug`` or higher + to a file called ``mongodb.log`` in your project directory +- Registers the logger + +.. literalinclude:: /includes/monitoring-logging/logging.php + :language: php + :start-after: start-monolog-logger + :end-before: end-monolog-logger + :dedent: + +Create a Custom Logger +~~~~~~~~~~~~~~~~~~~~~~ + +To create a custom PSR-3 logger, create a class that implements the +``Psr\Log\LoggerInterface`` interface. You can implement ``Psr\Log\LoggerInterface`` +by defining 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 class named ``MyLogger`` that extends the ``AbstractLogger`` class + and records the log level, description, and domain of each event +- Creates a ``MyLogger`` object and registers the logger +- Prints each log message + +.. literalinclude:: /includes/monitoring-logging/logging.php + :language: php + :start-after: start-custom-logger + :end-before: end-custom-logger + :dedent: + +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: + +.. literalinclude:: /includes/monitoring-logging/logging.php + :language: php + :start-after: start-remove-logger + :end-before: end-remove-logger + :dedent: + +Additional Information +---------------------- + +To learn more about PSR-3 loggers, see `PSR-3: Logger Interface +`__ in the PHP-FIG documentation. + +To learn more about Monolog, see the :github:`monolog ` +GitHub repository. + +API Documentation +~~~~~~~~~~~~~~~~~ + +To learn more about the {+library-short+} methods discussed in this guide, see the +following API documentation: + +- :phpmethod:`MongoDB\add_logger()` +- :phpmethod:`MongoDB\remove_logger()` + +To learn more about how the underlying C driver generates log messages, see `Logging +`__ in the ``libmongoc`` +API documentation. diff --git a/source/monitoring-logging/monitoring.txt b/source/monitoring-logging/monitoring.txt index 3a3ade51..0a6af969 100644 --- a/source/monitoring-logging/monitoring.txt +++ b/source/monitoring-logging/monitoring.txt @@ -124,7 +124,7 @@ the ``CommandSubscriber`` interface. The class defines each ``CommandSubscriber` and includes custom logic for the ``commandStarted()`` method, which prints details about each new command that the server receives: -.. literalinclude:: /includes/monitoring/monitor.php +.. literalinclude:: /includes/monitoring-logging/monitor.php :start-after: start-command-subscriber :end-before: end-command-subscriber :language: php @@ -191,7 +191,7 @@ the ``SDAMSubscriber`` interface. The class defines each ``SDAMSubscriber`` meth and includes custom logic for the ``serverOpening()`` method, which prints details about servers added to the topology: -.. literalinclude:: /includes/monitoring/monitor.php +.. literalinclude:: /includes/monitoring-logging/monitor.php :start-after: start-sdam-subscriber :end-before: end-sdam-subscriber :language: php @@ -216,7 +216,7 @@ The following code registers the command and SDAM event subscribers created in the :ref:`php-subscribe` section of this page with a ``MongoDB\Client``: -.. literalinclude:: /includes/monitoring/monitor.php +.. literalinclude:: /includes/monitoring-logging/monitor.php :start-after: start-add-subs :end-before: end-add-subs :language: php @@ -243,7 +243,7 @@ To unregister a subscriber from your client, use the The following code shows how to remove the subscriber created in the :ref:`php-subscribe-command` section of this page: -.. literalinclude:: /includes/monitoring/monitor.php +.. literalinclude:: /includes/monitoring-logging/monitor.php :start-after: start-remove-sub :end-before: end-remove-sub :language: php