Skip to content

Commit f37d0fe

Browse files
norareidynorareidy
committed
DOCSP-47063: Logging
1 parent 90a66cc commit f37d0fe

File tree

4 files changed

+236
-1
lines changed

4 files changed

+236
-1
lines changed

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

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
<?php
2+
3+
require 'vendor/autoload.php';
4+
5+
use Psr\Log\AbstractLogger;
6+
use Psr\Log\LoggerInterface;
7+
use Psr\Log\LogLevel;
8+
use MongoDB\PsrLogAdapter;
9+
10+
use function MongoDB\add_logger;
11+
use function MongoDB\remove_logger;
12+
13+
// start-register-logger
14+
class MyLogger extends AbstractLogger
15+
{
16+
public array $logs = [];
17+
18+
public function log($level, $message, array $context = []): void
19+
{
20+
$this->logs[] = [$level, $message, $context['domain']];
21+
}
22+
}
23+
24+
$logger = new MyLogger();
25+
add_logger($logger);
26+
27+
$uri = "mongodb://a.mongo.cosmos.azure.com:19555/";
28+
$client = new MongoDB\Client($uri);
29+
print_r($logger->logs);
30+
// end-register-logger
31+
32+
// start-write-messages
33+
PsrLogAdapter::writeLog(PsrLogAdapter::WARN, 'domain1', 'This is a warning message');
34+
PsrLogAdapter::writeLog(PsrLogAdapter::CRITICAL, 'domain2', 'This is a critical message');
35+
36+
print_r($logger->logs);
37+
// end-write-messages
38+
39+
// start-remove-logger
40+
remove_logger($logger);
41+
// end-remove-logger

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

File renamed without changes.

‎source/monitoring-logging.txt

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

1111
Cluster Monitoring </monitoring-logging/cluster-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:`Cluster Monitoring <php-cluster-monitoring>`: Monitor changes
18-
in your cluster configuration
19+
in your cluster configuration
20+
- :ref:`Logging <php-logging>`: Configure logging to receive messages
21+
about {+library-short+} events

‎source/monitoring-logging/logging.txt

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
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**.
25+
26+
The {+library-short+} supports `Psr\\Log\\LoggerInterface
27+
<https://www.php-fig.org/psr/psr-3/#3-psrlogloggerinterface>`__, a PSR-3
28+
logger interface that allows your application to receive log messages.
29+
You can register one or more ``Psr\Log\LoggerInterface`` objects to
30+
send ``libmongoc`` and {+extension-short+} messages to the logger.
31+
32+
Register a Logger
33+
-----------------
34+
35+
To configure your application to receive messages about driver events,
36+
create a logger class that implements the ``Psr\Log\LoggerInterface``
37+
interface. Then, use the ``MongoDB\add_logger()`` function to register
38+
your logger.
39+
40+
To implement ``Psr\Log\LoggerInterface``, you can create a class that
41+
extends the ``Psr\Log\AbstractLogger`` class. ``AbstractLogger`` implements
42+
``LoggerInterface`` and a generic ``log()`` method, which receives each type
43+
of log message.
44+
45+
Each message includes the following information:
46+
47+
- Log level: Indicates the severity of the message. To view a list of
48+
possible levels, see `PSR\\Log\\LogLevel <https://www.php-fig.org/psr/psr-3/#5-psrlogloglevel>`__.
49+
- Message: Describes the logged event.
50+
- Domain string: Specifies the driver component that emitted the log message.
51+
52+
Example
53+
~~~~~~~
54+
55+
This example performs the following actions:
56+
57+
- Creates a logger called ``MyLogger`` that extends the ``AbstractLogger`` class
58+
and prints the severity level, description, and domain of each event
59+
- Registers the logger
60+
- Creates a client that connects to a CosmosDB cluster
61+
- Prints each log message
62+
63+
.. io-code-block::
64+
:copyable:
65+
66+
.. input:: /includes/monitoring-logging/logging.php
67+
:start-after: start-register-logger
68+
:end-before: end-register-logger
69+
:language: php
70+
:dedent:
71+
72+
.. output::
73+
:visible: false
74+
75+
Array
76+
(
77+
[0] => Array
78+
(
79+
[0] => debug
80+
[1] => Connection string: 'mongodb://a.mongo.cosmos.azure.com:19555/'
81+
[2] => PHONGO
82+
)
83+
[1] => Array
84+
(
85+
[0] => debug
86+
[1] => Creating Manager, phongo-1.21.0[stable] - mongoc-1.30.1(bundled), libbson-1.30.1(bundled), php-8.4.4
87+
[2] => PHONGO
88+
)
89+
[2] => Array
90+
(
91+
[0] => debug
92+
[1] => Setting driver handshake data: { name: 'ext-mongodb:PHP / PHPLIB ', version: '1.21.0 / 1.21.1 ', platform: 'PHP 8.4.4 ' }
93+
[2] => PHONGO
94+
)
95+
[3] => Array
96+
(
97+
[0] => info
98+
[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
99+
[2] => mongoc
100+
)
101+
[4] => Array
102+
(
103+
[0] => debug
104+
[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";}}}
105+
[2] => PHONGO
106+
)
107+
[5] => Array
108+
(
109+
[0] => debug
110+
[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";}}}
111+
[2] => PHONGO
112+
)
113+
)
114+
115+
The preceding output includes log messages with a ``debug`` severity level, which
116+
describe normal driver activities. It also includes a message about the CosmosDB
117+
connection with an ``info`` severity level that describes a noteworthy but non-urgent
118+
event.
119+
120+
Write Custom Log Messages
121+
-------------------------
122+
123+
You can generate custom log messages by using the ``PsrLogAdapter::writeLog()``
124+
function. This function allows you to write directly to the logger and
125+
can assist with application debugging. Pass the severity level, domain, and
126+
description as parameters to ``writeLog()``.
127+
128+
The following example writes log messages that have ``warning`` and
129+
``critical`` severity levels to the logger:
130+
131+
.. io-code-block::
132+
:copyable:
133+
134+
.. input:: /includes/monitoring-logging/logging.php
135+
:start-after: start-register-logger
136+
:end-before: end-register-logger
137+
:language: php
138+
:dedent:
139+
140+
.. output::
141+
:visible: false
142+
143+
Array
144+
(
145+
[0] => Array
146+
(
147+
[0] => warning
148+
[1] => This is a warning message
149+
[2] => domain1
150+
)
151+
[1] => Array
152+
(
153+
[0] => critical
154+
[1] => This is a critical message
155+
[2] => domain2
156+
)
157+
)
158+
159+
Remove a Logger
160+
---------------
161+
162+
To unregister a logger, pass your logger object as a parameter to the ``MongoDB\remove_logger()``
163+
function. After calling this function, your logger no longer receives log
164+
messages about your application.
165+
166+
The following example unregisters a logger:
167+
168+
.. literalinclude:: /includes/monitoring-logging/logging.php
169+
:language: php
170+
:start-after: start-remove-logger
171+
:end-before: end-remove-logger
172+
:dedent:
173+
174+
Additional Information
175+
----------------------
176+
177+
To learn more about the PSR-3 logger, see `PSR-3: Logger Interface
178+
<https://www.php-fig.org/psr/psr-3/>`__ in the PHP-FIG documentation.
179+
180+
API Documentation
181+
~~~~~~~~~~~~~~~~~
182+
183+
To learn more about the {+library-short+} methods discussed in this guide, see the
184+
following API documentation:
185+
186+
- :phpmethod:`MongoDB\add_logger()`
187+
- :phpmethod:`MongoDB\remove_logger()`
188+
189+
To learn more about C driver logging behavior, see `Logging
190+
<https://mongoc.org/libmongoc/current/logging.html>`__ in the ``libmongoc``
191+
API documentation.

0 commit comments

Comments
 (0)