From f37d0fe9a30decd2113fa76f55ac9fc8da50db31 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 10 Jun 2025 11:03:23 -0400 Subject: [PATCH 1/6] 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 2/6] 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 3/6] 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 4/6] 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 5/6] 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 6/6] 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.