Skip to content

Commit 2198d16

Browse files
mongoKartmongoKart
authored
docsp-26773 - logging (#68)
* autobuilder * wip * first draft * fixes * fixes * fixes * fixes * add page links * DB feedback * fix warnings * fix warnings * fix * fix autobuilder * remove extra backticks * logging link * spacing * BD feedback * BD feedback 2 * BD feedback 3
1 parent b50a83b commit 2198d16

File tree

3 files changed

+155
-3
lines changed

3 files changed

+155
-3
lines changed

‎source/fundamentals.txt‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ Fundamentals
1919
/fundamentals/enterprise-authentication
2020
/fundamentals/linq
2121
/fundamentals/class-mapping
22+
/fundamentals/logging
2223

2324
- :ref:`Connecting to MongoDB <csharp-connection>`
2425
- :ref:`csharp-crud`
@@ -29,4 +30,4 @@ Fundamentals
2930
- :ref:`csharp-enterprise-authentication-mechanisms`
3031
- :ref:`csharp-linq`
3132
- :ref:`csharp-class-mapping`
32-
33+
- :ref:`csharp-logging`

‎source/fundamentals/connection/connection-options.txt‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -218,7 +218,7 @@ relevant options.
218218
| **Connection URI Example**: ``localThresholdMS=0``
219219

220220
* - **LoggingSettings**
221-
- | The settings used for logging.
221+
- | The settings used for :ref:`logging. <csharp-logging>`
222222
|
223223
| **Data Type**: `LoggingSettings <{+api-root+}/T_MongoDB_Driver_Core_Configuration_LoggingSettings.htm>`__
224224
| **Default**: ``null``
@@ -295,7 +295,7 @@ relevant options.
295295

296296
readPreference=primaryPreferred
297297
&maxStalenessSeconds=90
298-
&readPreferenceTags=dc:ny,rack:1``
298+
&readPreferenceTags=dc:ny,rack:1
299299

300300
|
301301

‎source/fundamentals/logging.txt‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
.. _csharp-logging:
2+
3+
=======
4+
Logging
5+
=======
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
Overview
14+
--------
15+
16+
Starting in version 2.18, the {+driver-short+} uses the standard
17+
`.NET logging API. <https://learn.microsoft.com/en-us/dotnet/core/extensions/logging?tabs=command-line>`__
18+
In this guide, you can learn how to use the driver to configure logging for your
19+
application.
20+
21+
Configure Logging
22+
-----------------
23+
24+
To specify the logging settings for your application, create a new instance of the
25+
``LoggingSettings`` class, then assign it to the ``LoggingSettings`` property of your
26+
``MongoClientSettings`` object.
27+
28+
The ``LoggingSettings`` constructor accepts the following parameters:
29+
30+
.. list-table::
31+
:header-rows: 1
32+
:widths: 25 75
33+
34+
* - Property
35+
- Description
36+
37+
* - ``LoggerFactory``
38+
- | The ``ILoggerFactory`` object that creates an ``ILogger``. You can create
39+
an ``ILoggerFactory`` object by using the ``LoggerFactory.Create()`` method.
40+
|
41+
| **Data Type**: `ILoggerFactory <https://learn.microsoft.com/en-us/dotnet/api/microsoft.extensions.logging.iloggerfactory?view=dotnet-plat-ext-7.0>`__
42+
| **Default**: ``null``
43+
44+
* - ``MaxDocumentSize``
45+
- | Optional. The maximum number of characters for extended JSON documents in logged
46+
messages.
47+
|
48+
| For example, when the driver logs the ``CommandStarted`` message, it truncates
49+
the ``Command`` field to the number of characters specified in this parameter.
50+
|
51+
| **Data Type**: {+int-data-type+}
52+
| **Default**: ``1000``
53+
54+
The following code sample shows how to create a ``MongoClient`` that
55+
logs all debug messages to the console:
56+
57+
.. code-block:: csharp
58+
59+
using var loggerFactory = LoggerFactory.Create(b =>
60+
{
61+
b.AddSimpleConsole();
62+
b.SetMinimumLevel(LogLevel.Debug);
63+
});
64+
65+
var settings = MongoClientSettings.FromConnectionString("<your connection string>");
66+
settings.LoggingSettings = new LoggingSettings(loggerFactory);
67+
var client = new MongoClient(settings);
68+
69+
Log Messages by Category
70+
------------------------
71+
72+
Each message generated by a MongoDB cluster is assigned a *category*. This lets you
73+
specify different log levels for different types of messages.
74+
75+
MongoDB uses the following categories to classify messages:
76+
77+
.. list-table::
78+
:header-rows: 1
79+
:widths: 25 75
80+
81+
* - Category
82+
- Description
83+
84+
* - ``MongoDB.Command``
85+
- | The progress of commands run against your cluster, represented by
86+
``CommandStartedEvent``, ``CommandSucceededEvent``, and ``CommandFailedEvent``
87+
88+
* - ``MongoDB.SDAM``
89+
- | Changes in the topology of the cluster, including
90+
``ClusterAddedServerEvent``, ``ClusterRemovedServerEvent``,
91+
``ServerHeartbeatStartedEvent``, ``ClusterDescriptionChangedEvent``,
92+
and ``ServerDescriptionChangedEvent``
93+
94+
* - ``MongoDB.ServerSelection``
95+
- | The decisions that determine which server to send a particular command to
96+
97+
* - ``MongoDB.Connection``
98+
- | Changes in the cluster connection pool, including ``ConnectionPoolReadyEvent``,
99+
``ConnectionPoolClosedEvent``, ``ConnectionCreatedEvent``, and
100+
``ConnectionCheckoutEvent``
101+
102+
* - ``MongoDB.Internal.*``
103+
- | Prefix for all other {+driver-short+} internal components
104+
105+
.. tip::
106+
107+
You can specify the minimum verbosity for all logging categories by configuring the
108+
``Default`` category.
109+
110+
Configure Log Verbosity
111+
-----------------------
112+
113+
You can configure the log verbosity of each message category by using the standard .NET
114+
logging mechanism. The following code sample shows how to configure a ``MongoClient``
115+
to log two types of messages:
116+
117+
- All messages with log level ``Error`` or higher from all categories
118+
- All messages with log level ``Debug`` or higher from the SDAM category
119+
120+
In this example, the configuration is done in-memory. The code creates a
121+
``Dictionary<string, string>`` where the key is ``"LogLevel:<category>"`` and the value
122+
is the minimum log level of messages in that category. The code then adds the
123+
dictionary to a ``ConfigurationBuilder`` object, then adds the ``ConfigurationBuilder``
124+
to a ``LoggerFactory``.
125+
126+
.. code-block:: csharp
127+
128+
var categoriesConfiguration = new Dictionary<string, string>
129+
{
130+
{ "LogLevel:Default", "Error" },
131+
{ "LogLevel:MongoDB.SDAM", "Debug" }
132+
};
133+
134+
var config = new ConfigurationBuilder()
135+
.AddInMemoryCollection(categoriesConfiguration)
136+
.Build();
137+
138+
using var loggerFactory = LoggerFactory.Create(b =>
139+
{
140+
b.AddConfiguration(config);
141+
b.AddSimpleConsole();
142+
});
143+
144+
var settings = MongoClientSettings.FromConnectionString("<your connection string>");
145+
settings.LoggingSettings = new LoggingSettings(loggerFactory);
146+
var client = new MongoClient(settings);
147+
148+
.. tip::
149+
150+
For more information on configuring log verbosity, see the
151+
`Microsoft .NET logging documentation. <https://learn.microsoft.com/en-us/dotnet/core/extensions/logging?tabs=command-line#configure-logging>`__

0 commit comments

Comments
 (0)