logging.txt

.. _csharp-logging:

=======
Logging
=======

.. facet::
   :name: genre
   :values: reference

.. meta::
   :keywords: loggerfactory, logger, audit
   :description: Learn to configure logging in the .NET/C# Driver using the standard .NET logging API, including setting log verbosity and categories.

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 2
   :class: singlecol

Overview
--------

Starting in version 2.18, the {+driver-short+} uses the standard 
`.NET logging API. <https://learn.microsoft.com/en-us/dotnet/core/extensions/logging?tabs=command-line>`__
In this guide, you can learn how to use the driver to configure logging for your 
application. 

.. important::

   To use this feature, you must add the `Microsoft.Extensions.Logging.Console package
   <https://www.nuget.org/packages/Microsoft.Extensions.Logging.Console/>`__
   to your project.

Configure Logging
-----------------

To specify the logging settings for your application, create a new instance of the 
``LoggingSettings`` class, then assign it to the ``LoggingSettings`` property of your 
``MongoClientSettings`` object.

The ``LoggingSettings`` constructor accepts the following parameters:

.. list-table::
   :header-rows: 1
   :widths: 25 75

   * - Property
     - Description

   * - ``LoggerFactory``
     - | The ``ILoggerFactory`` object that creates an ``ILogger``. You can create 
         an ``ILoggerFactory`` object by using the ``LoggerFactory.Create()`` method.
       |
       | **Data Type**: `ILoggerFactory <https://learn.microsoft.com/en-us/dotnet/api/microsoft.extensions.logging.iloggerfactory?view=dotnet-plat-ext-7.0>`__
       | **Default**: ``null``

   * - ``MaxDocumentSize``
     - | Optional. The maximum number of characters for extended JSON documents in logged 
         messages.
       |
       | For example, when the driver logs the ``CommandStarted`` message, it truncates 
         the ``Command`` field to the number of characters specified in this parameter.
       |
       | **Data Type**: {+int-data-type+}
       | **Default**: ``1000``

The following code sample shows how to create a ``MongoClient`` that 
logs all debug messages to the console: 

.. code-block:: csharp 
    
   using var loggerFactory = LoggerFactory.Create(b =>
   {
     b.AddSimpleConsole();
     b.SetMinimumLevel(LogLevel.Debug);
   });
 
   var settings = MongoClientSettings.FromConnectionString("<connection string>");
   settings.LoggingSettings = new LoggingSettings(loggerFactory);
   var client = new MongoClient(settings);

Log Messages by Category
------------------------

Each message generated by a MongoDB cluster is assigned a *category*. This lets you 
specify different log levels for different types of messages. 

MongoDB uses the following categories to classify messages:

.. list-table::
   :header-rows: 1
   :widths: 25 75

   * - Category
     - Description

   * - ``MongoDB.Command``
     - | The progress of commands run against your cluster, represented by
         ``CommandStartedEvent``, ``CommandSucceededEvent``, and ``CommandFailedEvent``

   * - ``MongoDB.SDAM``
     - | Changes in the topology of the cluster, including
         ``ClusterAddedServerEvent``, ``ClusterRemovedServerEvent``, 
         ``ServerHeartbeatStartedEvent``, ``ClusterDescriptionChangedEvent``, 
         and ``ServerDescriptionChangedEvent``

   * - ``MongoDB.ServerSelection``
     - | The decisions that determine which server to send a particular command to

   * - ``MongoDB.Connection``
     - | Changes in the cluster connection pool, including ``ConnectionPoolReadyEvent``, 
         ``ConnectionPoolClosedEvent``, ``ConnectionCreatedEvent``, and 
         ``ConnectionCheckoutEvent``

   * - ``MongoDB.Internal.*``
     - | Prefix for all other {+driver-short+} internal components

.. tip::
 
   You can specify the minimum verbosity for all logging categories by configuring the 
   ``Default`` category. 

Configure Log Verbosity
-----------------------

You can configure the log verbosity of each message category by using the standard .NET
logging mechanism. The following code sample shows how to configure a ``MongoClient`` 
to log two types of messages: 

- All messages with log level ``Error`` or higher from all categories 
- All messages with log level ``Debug`` or higher from the SDAM category 

In this example, the configuration is done in-memory. The code creates a 
``Dictionary<string, string>`` where the key is ``"LogLevel:<category>"`` and the value 
is the minimum log level of messages in that category. The code then adds the 
dictionary to a ``ConfigurationBuilder`` object, then adds the ``ConfigurationBuilder`` 
to a ``LoggerFactory``.

.. code-block:: csharp

   var categoriesConfiguration = new Dictionary<string, string>
   {
     { "LogLevel:Default", "Error" },
     { "LogLevel:MongoDB.SDAM", "Debug" }
   };

   var config = new ConfigurationBuilder()
     .AddInMemoryCollection(categoriesConfiguration)
     .Build();

   using var loggerFactory = LoggerFactory.Create(b =>
   {
     b.AddConfiguration(config);
     b.AddSimpleConsole();
   });

   var settings = MongoClientSettings.FromConnectionString("<connection string>");
   settings.LoggingSettings = new LoggingSettings(loggerFactory);
   var client = new MongoClient(settings);

.. tip::

   For more information on configuring log verbosity, see the 
   `Microsoft .NET logging documentation. <https://learn.microsoft.com/en-us/dotnet/core/extensions/logging?tabs=command-line#configure-logging>`__