From f37d0fe9a30decd2113fa76f55ac9fc8da50db31 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 10 Jun 2025 11:03:23 -0400 Subject: [PATCH 01/12] DOCSP-47063: Logging --- .../includes/monitoring-logging/logging.php | 41 ++++ .../sdam.php | 0 source/monitoring-logging.txt | 5 +- source/monitoring-logging/logging.txt | 191 ++++++++++++++++++ 4 files changed, 236 insertions(+), 1 deletion(-) create mode 100644 source/includes/monitoring-logging/logging.php rename source/includes/{monitoring => monitoring-logging}/sdam.php (100%) create mode 100644 source/monitoring-logging/logging.txt diff --git a/source/includes/monitoring-logging/logging.php b/source/includes/monitoring-logging/logging.php new file mode 100644 index 00000000..cf9025da --- /dev/null +++ b/source/includes/monitoring-logging/logging.php @@ -0,0 +1,41 @@ +logs[] = [$level, $message, $context['domain']]; + } +} + +$logger = new MyLogger(); +add_logger($logger); + +$uri = "mongodb://a.mongo.cosmos.azure.com:19555/"; +$client = new MongoDB\Client($uri); +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/sdam.php b/source/includes/monitoring-logging/sdam.php similarity index 100% rename from source/includes/monitoring/sdam.php rename to source/includes/monitoring-logging/sdam.php diff --git a/source/monitoring-logging.txt b/source/monitoring-logging.txt index 5f5fc7b2..b030e067 100644 --- a/source/monitoring-logging.txt +++ b/source/monitoring-logging.txt @@ -10,9 +10,12 @@ Monitoring and Logging Cluster Monitoring Change Streams + Logging .. /monitoring/command-monitoring .. /monitoring/connection-monitoring - :ref:`Cluster Monitoring `: Monitor changes - in your cluster configuration \ No newline at end of file + in your cluster configuration +- :ref:`Logging `: Configure logging to receive messages + about {+library-short+} events \ No newline at end of file diff --git a/source/monitoring-logging/logging.txt b/source/monitoring-logging/logging.txt new file mode 100644 index 00000000..06e304c7 --- /dev/null +++ b/source/monitoring-logging/logging.txt @@ -0,0 +1,191 @@ +.. _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**. + +The {+library-short+} supports `Psr\\Log\\LoggerInterface +`__, a PSR-3 +logger interface that allows your application to receive log messages. +You can register one or more ``Psr\Log\LoggerInterface`` objects to +send ``libmongoc`` and {+extension-short+} messages to the logger. + +Register a Logger +----------------- + +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. + +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 each type +of log message. + +Each message includes the following information: + +- Log level: Indicates the severity of the message. To view a list of + possible levels, see `PSR\\Log\\LogLevel `__. +- Message: Describes the logged event. +- Domain string: Specifies the driver component that emitted the log message. + +Example +~~~~~~~ + +This example performs the following actions: + +- Creates a logger called ``MyLogger`` that extends the ``AbstractLogger`` class + and prints the severity level, description, and domain of each event +- Registers the logger +- Creates a client that connects to a CosmosDB cluster +- Prints each log message + +.. io-code-block:: + :copyable: + + .. input:: /includes/monitoring-logging/logging.php + :start-after: start-register-logger + :end-before: end-register-logger + :language: php + :dedent: + + .. output:: + :visible: false + + Array + ( + [0] => Array + ( + [0] => debug + [1] => Connection string: 'mongodb://a.mongo.cosmos.azure.com:19555/' + [2] => PHONGO + ) + [1] => Array + ( + [0] => debug + [1] => Creating Manager, phongo-1.21.0[stable] - mongoc-1.30.1(bundled), libbson-1.30.1(bundled), php-8.4.4 + [2] => PHONGO + ) + [2] => Array + ( + [0] => debug + [1] => Setting driver handshake data: { name: 'ext-mongodb:PHP / PHPLIB ', version: '1.21.0 / 1.21.1 ', platform: 'PHP 8.4.4 ' } + [2] => PHONGO + ) + [3] => Array + ( + [0] => info + [1] => You appear to be connected to a CosmosDB cluster. For more information regarding feature compatibility and support please visit https://www.mongodb.com/supportability/cosmosdb + [2] => mongoc + ) + [4] => Array + ( + [0] => debug + [1] => Created client with hash: a:4:{s:3:"pid";i:61731;s:3:"uri";s:41:"mongodb://a.mongo.cosmos.azure.com:19555/";s:7:"options";a:0:{}s:13:"driverOptions";a:1:{s:6:"driver";a:2:{s:4:"name";s:6:"PHPLIB";s:7:"version";s:6:"1.21.1";}}} + [2] => PHONGO + ) + [5] => Array + ( + [0] => debug + [1] => Stored persistent client with hash: a:4:{s:3:"pid";i:61731;s:3:"uri";s:41:"mongodb://a.mongo.cosmos.azure.com:19555/";s:7:"options";a:0:{}s:13:"driverOptions";a:1:{s:6:"driver";a:2:{s:4:"name";s:6:"PHPLIB";s:7:"version";s:6:"1.21.1";}}} + [2] => PHONGO + ) + ) + +The preceding output includes log messages with a ``debug`` severity level, which +describe normal driver activities. It also includes a message about the CosmosDB +connection with an ``info`` severity level that describes a noteworthy but non-urgent +event. + +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 assist with application 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-register-logger + :end-before: end-register-logger + :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 C driver logging behavior, see `Logging +`__ in the ``libmongoc`` +API documentation. From 41aceb445f25354ee87ea544b1a8dc23a79f665b Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 10 Jun 2025 11:25:26 -0400 Subject: [PATCH 02/12] edits --- source/monitoring-logging/logging.txt | 32 +++++++++++++++------------ 1 file changed, 18 insertions(+), 14 deletions(-) diff --git a/source/monitoring-logging/logging.txt b/source/monitoring-logging/logging.txt index 06e304c7..30a8970c 100644 --- a/source/monitoring-logging/logging.txt +++ b/source/monitoring-logging/logging.txt @@ -21,13 +21,17 @@ Overview -------- In this guide, you can learn how to use the {+library-short+} to -set up and configure **logging**. +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 allows your application to receive log messages. +logger interface that configures your application to receive log messages. You can register one or more ``Psr\Log\LoggerInterface`` objects to -send ``libmongoc`` and {+extension-short+} messages to the logger. +send messages to the logger. The {+library-short+} is built on top of +``libmongoc`` and {+extension-short+}, so the logger receives event notifications +from both components. Register a Logger ----------------- @@ -37,25 +41,25 @@ create a logger class that implements the ``Psr\Log\LoggerInterface`` interface. Then, use the ``MongoDB\add_logger()`` function to register your logger. -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 each type -of log message. - -Each message includes the following information: +Each log message includes the following information: - Log level: Indicates the severity of the message. To view a list of possible levels, see `PSR\\Log\\LogLevel `__. - Message: Describes the logged event. - Domain string: Specifies the driver component that emitted the log message. +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. + Example ~~~~~~~ This example performs the following actions: - Creates a logger called ``MyLogger`` that extends the ``AbstractLogger`` class - and prints the severity level, description, and domain of each event + and records the log level, description, and domain of each event - Registers the logger - Creates a client that connects to a CosmosDB cluster - Prints each log message @@ -114,7 +118,7 @@ This example performs the following actions: The preceding output includes log messages with a ``debug`` severity level, which describe normal driver activities. It also includes a message about the CosmosDB -connection with an ``info`` severity level that describes a noteworthy but non-urgent +connection with an ``info`` level that describes a noteworthy but non-urgent event. Write Custom Log Messages @@ -122,7 +126,7 @@ 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 assist with application debugging. Pass the severity level, domain, 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 @@ -132,8 +136,8 @@ The following example writes log messages that have ``warning`` and :copyable: .. input:: /includes/monitoring-logging/logging.php - :start-after: start-register-logger - :end-before: end-register-logger + :start-after: start-write-messages + :end-before: end-write-messages :language: php :dedent: From 7decdd442bb4f509d669f3fc4b3fe2a61b61f409 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 10 Jun 2025 11:49:55 -0400 Subject: [PATCH 03/12] word --- source/monitoring-logging/logging.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/monitoring-logging/logging.txt b/source/monitoring-logging/logging.txt index 30a8970c..ad050afc 100644 --- a/source/monitoring-logging/logging.txt +++ b/source/monitoring-logging/logging.txt @@ -30,7 +30,7 @@ The {+library-short+} supports `Psr\\Log\\LoggerInterface 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 -``libmongoc`` and {+extension-short+}, so the logger receives event notifications +``libmongoc`` and the {+extension-short+}, so the logger receives event notifications from both components. Register a Logger From a5cdb3135616712cca66322c23a6da5063913158 Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 16 Jun 2025 15:24:58 -0400 Subject: [PATCH 04/12] feedback --- source/monitoring-logging.txt | 4 +- source/monitoring-logging/logging.txt | 101 ++++++++------------------ 2 files changed, 34 insertions(+), 71 deletions(-) diff --git a/source/monitoring-logging.txt b/source/monitoring-logging.txt index b030e067..7dcf5d93 100644 --- a/source/monitoring-logging.txt +++ b/source/monitoring-logging.txt @@ -18,4 +18,6 @@ Monitoring and Logging - :ref:`Cluster Monitoring `: Monitor changes in your cluster configuration - :ref:`Logging `: Configure logging to receive messages - about {+library-short+} events \ No newline at end of file + about {+library-short+} events +- :ref:`Change Streams `: Monitor data changes in + your application \ No newline at end of file diff --git a/source/monitoring-logging/logging.txt b/source/monitoring-logging/logging.txt index ad050afc..c08c029a 100644 --- a/source/monitoring-logging/logging.txt +++ b/source/monitoring-logging/logging.txt @@ -26,14 +26,14 @@ 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 +`__, 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 -``libmongoc`` and the {+extension-short+}, so the logger receives event notifications +the MongoDB C driver and the {+extension-short+}, so the logger receives event notifications from both components. -Register a Logger +Configure Logging ----------------- To configure your application to receive messages about driver events, @@ -41,85 +41,47 @@ create a logger class that implements the ``Psr\Log\LoggerInterface`` interface. Then, use the ``MongoDB\add_logger()`` function to register your logger. -Each log message includes the following information: +After registering a logger, the {+library-short+} generates log messages +as array values that resemble the following sample message: -- Log level: Indicates the severity of the message. To view a list of - possible levels, see `PSR\\Log\\LogLevel `__. -- Message: Describes the logged event. -- Domain string: Specifies the driver component that emitted the log 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. -Example -~~~~~~~ - 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 -- Creates a client that connects to a CosmosDB cluster - Prints each log message -.. io-code-block:: - :copyable: - - .. input:: /includes/monitoring-logging/logging.php - :start-after: start-register-logger - :end-before: end-register-logger - :language: php - :dedent: - - .. output:: - :visible: false - - Array - ( - [0] => Array - ( - [0] => debug - [1] => Connection string: 'mongodb://a.mongo.cosmos.azure.com:19555/' - [2] => PHONGO - ) - [1] => Array - ( - [0] => debug - [1] => Creating Manager, phongo-1.21.0[stable] - mongoc-1.30.1(bundled), libbson-1.30.1(bundled), php-8.4.4 - [2] => PHONGO - ) - [2] => Array - ( - [0] => debug - [1] => Setting driver handshake data: { name: 'ext-mongodb:PHP / PHPLIB ', version: '1.21.0 / 1.21.1 ', platform: 'PHP 8.4.4 ' } - [2] => PHONGO - ) - [3] => Array - ( - [0] => info - [1] => You appear to be connected to a CosmosDB cluster. For more information regarding feature compatibility and support please visit https://www.mongodb.com/supportability/cosmosdb - [2] => mongoc - ) - [4] => Array - ( - [0] => debug - [1] => Created client with hash: a:4:{s:3:"pid";i:61731;s:3:"uri";s:41:"mongodb://a.mongo.cosmos.azure.com:19555/";s:7:"options";a:0:{}s:13:"driverOptions";a:1:{s:6:"driver";a:2:{s:4:"name";s:6:"PHPLIB";s:7:"version";s:6:"1.21.1";}}} - [2] => PHONGO - ) - [5] => Array - ( - [0] => debug - [1] => Stored persistent client with hash: a:4:{s:3:"pid";i:61731;s:3:"uri";s:41:"mongodb://a.mongo.cosmos.azure.com:19555/";s:7:"options";a:0:{}s:13:"driverOptions";a:1:{s:6:"driver";a:2:{s:4:"name";s:6:"PHPLIB";s:7:"version";s:6:"1.21.1";}}} - [2] => PHONGO - ) - ) - -The preceding output includes log messages with a ``debug`` severity level, which -describe normal driver activities. It also includes a message about the CosmosDB -connection with an ``info`` level that describes a noteworthy but non-urgent -event. +.. literalinclude:: /includes/monitoring-logging/logging.php + :language: php + :start-after: start-register-logger + :end-before: end-register-logger + :dedent: Write Custom Log Messages ------------------------- @@ -189,7 +151,6 @@ following API documentation: - :phpmethod:`MongoDB\add_logger()` - :phpmethod:`MongoDB\remove_logger()` - -To learn more about C driver logging behavior, see `Logging +To learn more about how the underlying C driver generates log messages, see `Logging `__ in the ``libmongoc`` API documentation. From b895d72a991cd0a46d17a8a9914899024046a947 Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 16 Jun 2025 15:26:15 -0400 Subject: [PATCH 05/12] code edit --- source/includes/monitoring-logging/logging.php | 3 --- 1 file changed, 3 deletions(-) diff --git a/source/includes/monitoring-logging/logging.php b/source/includes/monitoring-logging/logging.php index cf9025da..05c2355c 100644 --- a/source/includes/monitoring-logging/logging.php +++ b/source/includes/monitoring-logging/logging.php @@ -23,9 +23,6 @@ public function log($level, $message, array $context = []): void $logger = new MyLogger(); add_logger($logger); - -$uri = "mongodb://a.mongo.cosmos.azure.com:19555/"; -$client = new MongoDB\Client($uri); print_r($logger->logs); // end-register-logger From ee302ce66b4f51278d6801d2235a33493906a236 Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 16 Jun 2025 15:28:23 -0400 Subject: [PATCH 06/12] fix --- source/monitoring-logging/logging.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/source/monitoring-logging/logging.txt b/source/monitoring-logging/logging.txt index c08c029a..cec90f79 100644 --- a/source/monitoring-logging/logging.txt +++ b/source/monitoring-logging/logging.txt @@ -151,6 +151,7 @@ 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. From 1f53a7e271ecca272a3aac1068d8f44e0284c774 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 18 Jun 2025 11:02:58 -0400 Subject: [PATCH 07/12] JT feedback --- .../includes/monitoring-logging/logging.php | 34 +++--- source/monitoring-logging/logging.txt | 101 +++++++++--------- 2 files changed, 67 insertions(+), 68 deletions(-) diff --git a/source/includes/monitoring-logging/logging.php b/source/includes/monitoring-logging/logging.php index 05c2355c..65f23d90 100644 --- a/source/includes/monitoring-logging/logging.php +++ b/source/includes/monitoring-logging/logging.php @@ -2,15 +2,22 @@ require 'vendor/autoload.php'; +// start-monolog-logger +use Monolog\Logger; +use Monolog\Handler\StreamHandler; + +$logger = new Logger('mongodb-logger'); +$logger->pushHandler(new StreamHandler(__DIR__ . '/library.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; -use function MongoDB\add_logger; -use function MongoDB\remove_logger; - -// start-register-logger class MyLogger extends AbstractLogger { public array $logs = []; @@ -21,18 +28,11 @@ public function log($level, $message, array $context = []): void } } -$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 +$customLogger = new MyLogger(); +MongoDB\add_logger($customLogger ); +print_r($customLogger ->logs); +// end-custom-logger // start-remove-logger -remove_logger($logger); -// end-remove-logger +MongoDB\remove_logger($logger); +// end-remove-logger \ No newline at end of file diff --git a/source/monitoring-logging/logging.txt b/source/monitoring-logging/logging.txt index cec90f79..a00c7478 100644 --- a/source/monitoring-logging/logging.txt +++ b/source/monitoring-logging/logging.txt @@ -37,12 +37,12 @@ Configure Logging ----------------- To configure your application to receive messages about driver events, -create a logger class that implements the ``Psr\Log\LoggerInterface`` +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 -as array values that resemble the following sample message: +that resemble the following sample message: .. code-block:: php :copyable: false @@ -62,65 +62,64 @@ The sample log message includes the following information: - Domain string: Specifies the driver component that emitted the log message. The ``PHONGO`` domain indicates that the {+extension-short+} generated the event. -Example -~~~~~~~ +.. note:: -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. + 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 provides +a ``Monolog\Logger`` logging class that implements the ``Psr\Log\LoggerInterface`` +interface. It also 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 logger called ``MyLogger`` that extends the ``AbstractLogger`` class - and records the log level, description, and domain of each event +- 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 ``library.log`` in your project directory - 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 + :start-after: start-monolog-logger + :end-before: end-monolog-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 - ) - ) +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 --------------- From b0e01f3338672eb56cd732e69f4875ce0fff3ef4 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 18 Jun 2025 11:07:46 -0400 Subject: [PATCH 08/12] edit --- source/monitoring-logging/logging.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/monitoring-logging/logging.txt b/source/monitoring-logging/logging.txt index a00c7478..f8133e96 100644 --- a/source/monitoring-logging/logging.txt +++ b/source/monitoring-logging/logging.txt @@ -28,8 +28,8 @@ 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 +You can register one or more instances of a class that implements +``Psr\Log\LoggerInterface`` 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. From b41980baaf9ecdf1dc7c88bc2543a37324ffd118 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 18 Jun 2025 11:09:24 -0400 Subject: [PATCH 09/12] spacing --- source/includes/monitoring-logging/logging.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/includes/monitoring-logging/logging.php b/source/includes/monitoring-logging/logging.php index 65f23d90..b876ca36 100644 --- a/source/includes/monitoring-logging/logging.php +++ b/source/includes/monitoring-logging/logging.php @@ -29,8 +29,8 @@ public function log($level, $message, array $context = []): void } $customLogger = new MyLogger(); -MongoDB\add_logger($customLogger ); -print_r($customLogger ->logs); +MongoDB\add_logger($customLogger); +print_r($customLogger->logs); // end-custom-logger // start-remove-logger From b069e90715b7708fdadcc5e19b0ad21bfb76a5ef Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 18 Jun 2025 11:11:21 -0400 Subject: [PATCH 10/12] gh link --- source/monitoring-logging/logging.txt | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/source/monitoring-logging/logging.txt b/source/monitoring-logging/logging.txt index f8133e96..4521a41a 100644 --- a/source/monitoring-logging/logging.txt +++ b/source/monitoring-logging/logging.txt @@ -139,9 +139,12 @@ The following example unregisters a logger: Additional Information ---------------------- -To learn more about the PSR-3 logger, see `PSR-3: Logger Interface +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 ~~~~~~~~~~~~~~~~~ From cf220867df3b4ed52a296030cb6bb732f46e2651 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 18 Jun 2025 11:29:01 -0400 Subject: [PATCH 11/12] JT feedback 2 --- source/includes/monitoring-logging/logging.php | 4 ++-- source/monitoring-logging/logging.txt | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/source/includes/monitoring-logging/logging.php b/source/includes/monitoring-logging/logging.php index b876ca36..8a97b794 100644 --- a/source/includes/monitoring-logging/logging.php +++ b/source/includes/monitoring-logging/logging.php @@ -7,7 +7,7 @@ use Monolog\Handler\StreamHandler; $logger = new Logger('mongodb-logger'); -$logger->pushHandler(new StreamHandler(__DIR__ . '/library.log', Logger::DEBUG)); +$logger->pushHandler(new StreamHandler(__DIR__ . '/mongodb.log', Logger::DEBUG)); MongoDB\add_logger($logger); // end-monolog-logger @@ -35,4 +35,4 @@ public function log($level, $message, array $context = []): void // start-remove-logger MongoDB\remove_logger($logger); -// end-remove-logger \ No newline at end of file +// end-remove-logger diff --git a/source/monitoring-logging/logging.txt b/source/monitoring-logging/logging.txt index 4521a41a..30c6243b 100644 --- a/source/monitoring-logging/logging.txt +++ b/source/monitoring-logging/logging.txt @@ -29,9 +29,9 @@ 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 send messages to the logger. The {+library-short+} is built on top of +``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 both components. +from each component. Configure Logging ----------------- @@ -90,7 +90,7 @@ 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 ``library.log`` in your project directory + to a file called ``mongodb.log`` in your project directory - Registers the logger .. literalinclude:: /includes/monitoring-logging/logging.php From 4c917c72dae6a42b8a17b08bea23c4599489401f Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 23 Jun 2025 16:30:57 -0400 Subject: [PATCH 12/12] RR feedback --- source/monitoring-logging/logging.txt | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/source/monitoring-logging/logging.txt b/source/monitoring-logging/logging.txt index 30c6243b..7eecd8a9 100644 --- a/source/monitoring-logging/logging.txt +++ b/source/monitoring-logging/logging.txt @@ -44,7 +44,7 @@ your logger. After registering a logger, the {+library-short+} generates log messages that resemble the following sample message: -.. code-block:: php +.. code-block:: none :copyable: false [0] => Array @@ -62,7 +62,7 @@ The sample log message includes the following information: - Domain string: Specifies the driver component that emitted the log message. The ``PHONGO`` domain indicates that the {+extension-short+} generated the event. -.. note:: +.. 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 @@ -72,9 +72,10 @@ Create a Monolog Logger ~~~~~~~~~~~~~~~~~~~~~~~ You can use `Monolog `__, a -PHP logging library, to configure logging in your application. Monolog provides -a ``Monolog\Logger`` logging class that implements the ``Psr\Log\LoggerInterface`` -interface. It also provides handlers that direct logs to specified locations. +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: