Skip to content

Commit 7f8c17b

Browse files
norareidynorareidy
authored
DOCSP-47063: Logging (#267)
* DOCSP-47063: Logging * edits * word * feedback * code edit * fix * JT feedback * edit * spacing * gh link * JT feedback 2 * RR feedback
1 parent 59aa88c commit 7f8c17b

File tree

5 files changed

+208
-5
lines changed

5 files changed

+208
-5
lines changed

‎source/includes/monitoring-logging/logging.php

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
<?php
2+
3+
require 'vendor/autoload.php';
4+
5+
// start-monolog-logger
6+
use Monolog\Logger;
7+
use Monolog\Handler\StreamHandler;
8+
9+
$logger = new Logger('mongodb-logger');
10+
$logger->pushHandler(new StreamHandler(__DIR__ . '/mongodb.log', Logger::DEBUG));
11+
12+
MongoDB\add_logger($logger);
13+
// end-monolog-logger
14+
15+
// start-custom-logger
16+
use Psr\Log\AbstractLogger;
17+
use Psr\Log\LoggerInterface;
18+
use Psr\Log\LogLevel;
19+
use MongoDB\PsrLogAdapter;
20+
21+
class MyLogger extends AbstractLogger
22+
{
23+
public array $logs = [];
24+
25+
public function log($level, $message, array $context = []): void
26+
{
27+
$this->logs[] = [$level, $message, $context['domain']];
28+
}
29+
}
30+
31+
$customLogger = new MyLogger();
32+
MongoDB\add_logger($customLogger);
33+
print_r($customLogger->logs);
34+
// end-custom-logger
35+
36+
// start-remove-logger
37+
MongoDB\remove_logger($logger);
38+
// end-remove-logger

‎source/includes/monitoring/monitor.php renamed to ‎source/includes/monitoring-logging/monitor.php

File renamed without changes.

‎source/monitoring-logging.txt

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,9 +10,14 @@ Monitoring and Logging
1010

1111
Monitoring </monitoring-logging/monitoring>
1212
Change Streams </monitoring-logging/change-streams>
13+
Logging </monitoring-logging/logging>
1314

1415
.. /monitoring/command-monitoring
1516
.. /monitoring/connection-monitoring
1617

1718
- :ref:`Monitor Application Events <php-monitoring>`: Monitor changes
18-
in your application
19+
in your application
20+
- :ref:`Logging <php-logging>`: Configure logging to receive messages
21+
about {+library-short+} events
22+
- :ref:`Change Streams <php-change-streams>`: Monitor data changes in
23+
your application

‎source/monitoring-logging/logging.txt

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
.. _php-logging:
2+
3+
=================
4+
Log Driver Events
5+
=================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:keywords: debugging, printing
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to use the {+library-short+} to
24+
set up and configure **logging**. Logging allows you to receive
25+
information about database operations, server connections, errors,
26+
and other events that occur while your application runs.
27+
28+
The {+library-short+} supports `Psr\\Log\\LoggerInterface
29+
<https://www.php-fig.org/psr/psr-3>`__, a PSR-3
30+
logger interface that configures your application to receive log messages.
31+
You can register one or more instances of a class that implements
32+
``Psr\Log\LoggerInterface`` to receive log messages. The {+library-short+} is built on top of
33+
the MongoDB C driver and the {+extension-short+}, so the logger receives event notifications
34+
from each component.
35+
36+
Configure Logging
37+
-----------------
38+
39+
To configure your application to receive messages about driver events,
40+
create an instance of a logger class that implements the ``Psr\Log\LoggerInterface``
41+
interface. Then, use the ``MongoDB\add_logger()`` function to register
42+
your logger.
43+
44+
After registering a logger, the {+library-short+} generates log messages
45+
that resemble the following sample message:
46+
47+
.. code-block:: none
48+
:copyable: false
49+
50+
[0] => Array
51+
(
52+
[0] => debug
53+
[1] => Created client with hash: ...
54+
[2] => PHONGO
55+
)
56+
57+
The sample log message includes the following information:
58+
59+
- Log level: Indicates the severity of the message. The ``debug`` level corresponds to
60+
standard driver activities. To view a list of possible levels, see `PSR\\Log\\LogLevel <https://www.php-fig.org/psr/psr-3/#5-psrlogloglevel>`__.
61+
- Message: Describes the logged event, which signals the creation of a new client.
62+
- Domain string: Specifies the driver component that emitted the log message. The
63+
``PHONGO`` domain indicates that the {+extension-short+} generated the event.
64+
65+
.. note:: Log Message Format
66+
67+
The preceding example shows a log message stored in an array. However,
68+
the format of your log messages might differ depending on your logging
69+
implementation.
70+
71+
Create a Monolog Logger
72+
~~~~~~~~~~~~~~~~~~~~~~~
73+
74+
You can use `Monolog <https://packagist.org/packages/monolog/monolog>`__, a
75+
PHP logging library, to configure logging in your application. Monolog simplifies
76+
logging configuration by providing a ``Monolog\Logger`` class. This class implements
77+
the ``Psr\Log\LoggerInterface`` interface and provides handlers that direct logs to
78+
specified locations.
79+
80+
To use Monolog, install the ``monolog/monolog`` package by running
81+
the following command:
82+
83+
.. code-block:: shell
84+
85+
composer require monolog/monolog
86+
87+
Then, you can create a logger by defining a ``Monolog\Logger`` object
88+
and registering it with the {+library-short+}.
89+
90+
This example performs the following actions:
91+
92+
- Creates a Monolog logger called ``mongodb-logger``
93+
- Uses a handler to write all logs with a severity of ``debug`` or higher
94+
to a file called ``mongodb.log`` in your project directory
95+
- Registers the logger
96+
97+
.. literalinclude:: /includes/monitoring-logging/logging.php
98+
:language: php
99+
:start-after: start-monolog-logger
100+
:end-before: end-monolog-logger
101+
:dedent:
102+
103+
Create a Custom Logger
104+
~~~~~~~~~~~~~~~~~~~~~~
105+
106+
To create a custom PSR-3 logger, create a class that implements the
107+
``Psr\Log\LoggerInterface`` interface. You can implement ``Psr\Log\LoggerInterface``
108+
by defining a class that extends the ``Psr\Log\AbstractLogger`` class.
109+
``AbstractLogger`` implements ``LoggerInterface`` and a generic ``log()`` method,
110+
which receives log messages at each severity level.
111+
112+
This example performs the following actions:
113+
114+
- Creates a logger class named ``MyLogger`` that extends the ``AbstractLogger`` class
115+
and records the log level, description, and domain of each event
116+
- Creates a ``MyLogger`` object and registers the logger
117+
- Prints each log message
118+
119+
.. literalinclude:: /includes/monitoring-logging/logging.php
120+
:language: php
121+
:start-after: start-custom-logger
122+
:end-before: end-custom-logger
123+
:dedent:
124+
125+
Remove a Logger
126+
---------------
127+
128+
To unregister a logger, pass your logger object as a parameter to the ``MongoDB\remove_logger()``
129+
function. After calling this function, your logger no longer receives log
130+
messages about your application.
131+
132+
The following example unregisters a logger:
133+
134+
.. literalinclude:: /includes/monitoring-logging/logging.php
135+
:language: php
136+
:start-after: start-remove-logger
137+
:end-before: end-remove-logger
138+
:dedent:
139+
140+
Additional Information
141+
----------------------
142+
143+
To learn more about PSR-3 loggers, see `PSR-3: Logger Interface
144+
<https://www.php-fig.org/psr/psr-3/>`__ in the PHP-FIG documentation.
145+
146+
To learn more about Monolog, see the :github:`monolog </Seldaek/monolog>`
147+
GitHub repository.
148+
149+
API Documentation
150+
~~~~~~~~~~~~~~~~~
151+
152+
To learn more about the {+library-short+} methods discussed in this guide, see the
153+
following API documentation:
154+
155+
- :phpmethod:`MongoDB\add_logger()`
156+
- :phpmethod:`MongoDB\remove_logger()`
157+
158+
To learn more about how the underlying C driver generates log messages, see `Logging
159+
<https://mongoc.org/libmongoc/current/logging.html>`__ in the ``libmongoc``
160+
API documentation.

‎source/monitoring-logging/monitoring.txt

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -124,7 +124,7 @@ the ``CommandSubscriber`` interface. The class defines each ``CommandSubscriber`
124124
and includes custom logic for the ``commandStarted()`` method, which prints details
125125
about each new command that the server receives:
126126

127-
.. literalinclude:: /includes/monitoring/monitor.php
127+
.. literalinclude:: /includes/monitoring-logging/monitor.php
128128
:start-after: start-command-subscriber
129129
:end-before: end-command-subscriber
130130
:language: php
@@ -191,7 +191,7 @@ the ``SDAMSubscriber`` interface. The class defines each ``SDAMSubscriber`` meth
191191
and includes custom logic for the ``serverOpening()`` method, which prints details
192192
about servers added to the topology:
193193

194-
.. literalinclude:: /includes/monitoring/monitor.php
194+
.. literalinclude:: /includes/monitoring-logging/monitor.php
195195
:start-after: start-sdam-subscriber
196196
:end-before: end-sdam-subscriber
197197
:language: php
@@ -216,7 +216,7 @@ The following code registers the command and SDAM event subscribers
216216
created in the :ref:`php-subscribe` section of this page with a
217217
``MongoDB\Client``:
218218

219-
.. literalinclude:: /includes/monitoring/monitor.php
219+
.. literalinclude:: /includes/monitoring-logging/monitor.php
220220
:start-after: start-add-subs
221221
:end-before: end-add-subs
222222
:language: php
@@ -243,7 +243,7 @@ To unregister a subscriber from your client, use the
243243
The following code shows how to remove the subscriber created in
244244
the :ref:`php-subscribe-command` section of this page:
245245

246-
.. literalinclude:: /includes/monitoring/monitor.php
246+
.. literalinclude:: /includes/monitoring-logging/monitor.php
247247
:start-after: start-remove-sub
248248
:end-before: end-remove-sub
249249
:language: php

0 commit comments

Comments
 (0)