diff --git a/source/includes/monitoring-logging/logging.php b/source/includes/monitoring-logging/logging.php new file mode 100644 index 00000000..05c2355c --- /dev/null +++ b/source/includes/monitoring-logging/logging.php @@ -0,0 +1,38 @@ +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 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..cec90f79 --- /dev/null +++ b/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 +`__, 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 `__. +- 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 +`__ 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 +`__ 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