DOCSP-47063: Logging

source/includes/monitoring-logging/logging.php

@@ -0,0 +1,38 @@
+<?php
+
+require 'vendor/autoload.php';
+
+use Psr\Log\AbstractLogger;
+use Psr\Log\LoggerInterface;
+use Psr\Log\LogLevel;
+use MongoDB\PsrLogAdapter;
+
+use function MongoDB\add_logger;
+use function MongoDB\remove_logger;
+
+// start-register-logger
+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);
+// end-register-logger
+
+// start-write-messages
+PsrLogAdapter::writeLog(PsrLogAdapter::WARN, 'domain1', 'This is a warning message');
+PsrLogAdapter::writeLog(PsrLogAdapter::CRITICAL, 'domain2', 'This is a critical message');
+
+print_r($logger->logs);
+// end-write-messages
+
+// start-remove-logger
+remove_logger($logger);
+// end-remove-logger

source/monitoring-logging.txt

@@ -10,9 +10,14 @@ Monitoring and Logging
 
    Monitoring </monitoring-logging/monitoring>
    Change Streams </monitoring-logging/change-streams>
+   Logging </monitoring-logging/logging>
 
 .. /monitoring/command-monitoring
 .. /monitoring/connection-monitoring
 
 - :ref:`Monitor Application Events <php-monitoring>`: Monitor changes
-  in your application
+  in your application
+- :ref:`Logging <php-logging>`: Configure logging to receive messages
+  about {+library-short+} events
+- :ref:`Change Streams <php-change-streams>`: Monitor data changes in 
+  your application

source/monitoring-logging/logging.txt

@@ -0,0 +1,157 @@
+.. _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
+<https://www.php-fig.org/psr/psr-3>`__, 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 {+library-short+} is built on top of
+the MongoDB C driver and the {+extension-short+}, 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 {+library-short+} generates log messages
+as array values that resemble the following sample message:
+
+.. code-block:: php
+   :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 <https://www.php-fig.org/psr/psr-3/#5-psrlogloglevel>`__.
+- 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.
+
+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
+
+.. literalinclude:: /includes/monitoring-logging/logging.php
+   :language: php
+   :start-after: start-register-logger
+   :end-before: end-register-logger
+   :dedent:
+
+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:
+
+.. io-code-block::
+   :copyable:
+
+   .. input:: /includes/monitoring-logging/logging.php
+      :start-after: start-write-messages
+      :end-before: end-write-messages
+      :language: php
+      :dedent:
+
+   .. output::
+      :visible: false
+
+      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:
+
+.. 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 the PSR-3 logger, see `PSR-3: Logger Interface
+<https://www.php-fig.org/psr/psr-3/>`__ in the PHP-FIG documentation.
+
+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
+<https://mongoc.org/libmongoc/current/logging.html>`__ in the ``libmongoc``
+API documentation.

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