diff --git a/snooty.toml b/snooty.toml index 1f20e7e..c0c9ebd 100644 --- a/snooty.toml +++ b/snooty.toml @@ -36,3 +36,5 @@ kotlin-docs = "https://kotlinlang.org" serialization-version = "1.6.0" kotlinx-dt-version = "0.6.1" mongocrypt-version = "{+full-version+}" +logbackVersion = "1.2.11" +log4j2Version = "2.17.1" diff --git a/source/includes/logging-and-monitoring/log4j2-gradle.rst b/source/includes/logging-and-monitoring/log4j2-gradle.rst new file mode 100644 index 0000000..525ee65 --- /dev/null +++ b/source/includes/logging-and-monitoring/log4j2-gradle.rst @@ -0,0 +1,6 @@ +.. code-block:: groovy + + dependencies { + implementation 'org.apache.logging.log4j:log4j-slf4j-impl:{+log4j2Version+}' + } + \ No newline at end of file diff --git a/source/includes/logging-and-monitoring/log4j2-maven.rst b/source/includes/logging-and-monitoring/log4j2-maven.rst new file mode 100644 index 0000000..a573f3c --- /dev/null +++ b/source/includes/logging-and-monitoring/log4j2-maven.rst @@ -0,0 +1,9 @@ +.. code-block:: xml + + + + org.apache.logging.log4j + log4j-slf4j-impl + {+log4j2Version+} + + diff --git a/source/includes/logging-and-monitoring/logback-gradle.rst b/source/includes/logging-and-monitoring/logback-gradle.rst new file mode 100644 index 0000000..2308da3 --- /dev/null +++ b/source/includes/logging-and-monitoring/logback-gradle.rst @@ -0,0 +1,5 @@ +.. code-block:: groovy + + dependencies { + implementation 'ch.qos.logback:logback-classic:{+logbackVersion+}' + } diff --git a/source/includes/logging-and-monitoring/logback-maven.rst b/source/includes/logging-and-monitoring/logback-maven.rst new file mode 100644 index 0000000..8e5737d --- /dev/null +++ b/source/includes/logging-and-monitoring/logback-maven.rst @@ -0,0 +1,9 @@ +.. code-block:: xml + + + + ch.qos.logback + logback-classic + {+logbackVersion+} + + diff --git a/source/includes/logging-and-monitoring/logging.rst b/source/includes/logging-and-monitoring/logging.rst new file mode 100644 index 0000000..f265853 --- /dev/null +++ b/source/includes/logging-and-monitoring/logging.rst @@ -0,0 +1,6 @@ +.. code-block:: kotlin + + val mongoClient = MongoClient.create(); + val database = mongoClient.getDatabase(); + val collection = database.getCollection(); + collection.find().first(); diff --git a/source/logging-and-monitoring.txt b/source/logging-and-monitoring.txt index 4aa780f..a228706 100644 --- a/source/logging-and-monitoring.txt +++ b/source/logging-and-monitoring.txt @@ -13,8 +13,8 @@ Logging and Monitoring .. toctree:: - Monitoring Logging + Monitoring Change Streams Overview diff --git a/source/logging-and-monitoring/logging.txt b/source/logging-and-monitoring/logging.txt index ee9285e..e7d848f 100644 --- a/source/logging-and-monitoring/logging.txt +++ b/source/logging-and-monitoring/logging.txt @@ -8,4 +8,394 @@ Log Driver Events :local: :backlinks: none :depth: 2 - :class: singlecol \ No newline at end of file + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to set up and configure a logger in the {+driver-short+}. + +This guide shows how to record events in the driver. If you want to learn how to +use information about the activity of the driver in code, see the :ref:`kotlin-sync-monitoring` +guide. + +Set Up a Logger +--------------- + +The {+driver-short+} uses Simple Logging Facade For Java (SLF4J) to allow you to specify +your logging framework of choice. For more information about SLF4J, see the `SLF4J documentation +`__. + +Setting up a logger is optional. To set up a logger, you must include the following in +your project: + +- The ``slf4j-api`` artifact in your classpath +- A logging framework +- A **binding** that connects the ``slf4j-api`` artifact to a logging framework + +If the driver can't find the ``slf4j-api`` artifact in your classpath, the driver outputs +the following warning and disables all further logging: + +.. code-block:: + + WARNING: SLF4J not found on the classpath. Logging is disabled for the 'org.mongodb.driver' component + +Logger Setup Example +~~~~~~~~~~~~~~~~~~~~ + +The following example shows how to set up a logger. Select the :guilabel:`Logback` or +:guilabel:`Log4j2` tab to see the corresponding syntax: + +.. tabs:: + + .. tab:: Logback + :tabid: Logback-binding + + Select the :guilabel:`Maven` or :guilabel:`Gradle` tab to learn about how to set up + Logback with your project's dependency management tool: + + .. tabs:: + + .. tab:: Maven + :tabid: maven + + Add the following dependency to your ``pom.xml`` file. + + .. include:: /includes/logging-and-monitoring/logback-maven.rst + + .. tab:: Gradle + :tabid: gradle + + Add the following dependency to your ``build.gradle`` file. + + .. include:: /includes/logging-and-monitoring/logback-gradle.rst + + Once you have included the preceding dependency, connect to your + MongoDB instance and retrieve a document with the following code: + + .. include:: /includes/logging-and-monitoring/logging.rst + + The preceding code will ouput a message that resembles the following: + + .. code-block:: none + :copyable: false + + ... + 12:14:55.853 [main] DEBUG org.mongodb.driver.connection - Opened connection [connectionId{localValue:3, serverValue:3}] to + 12:14:55.861 [main] DEBUG org.mongodb.driver.protocol.command - Command "find" started on database using a connection with driver-generated ID 3 and server-generated ID 3 to . The request ID is 5. Command: {"find": "", "filter": {}, "limit": 1, "singleBatch": true, "$db": "", "lsid": {"id": {"$binary": {"base64": "<_id>", "subType": "04"}}}, "$readPreference": {"mode": "primaryPreferred"}} + 12:14:55.864 [main] DEBUG org.mongodb.driver.protocol.command - Command "find" succeeded in 4.34 ms using a connection with driver-generated ID 3 and server-generated ID 3 to .", "firstBatch": []}, "ok": 1.0, "$clusterTime": {"clusterTime": {"$timestamp": {"t": 1673778535, "i": 1}}, "signature": {"hash": {"$binary": {"base64": "<_id>", "subType": "00"}}, "keyId": 0}}, "operationTime": {"$timestamp": {"t": 1673778535, "i": 1}}} + + .. note:: Default Log Level + + The default log level of Logback is DEBUG. To learn how to change your + Logback logger's log level, see the + :ref:`Configure Log Level ` section of this page. + + .. tab:: Log4j2 + :tabid: Log4j2-binding + + Select the :guilabel:`Maven` or :guilabel:`Gradle` tab to learn about how to set up + Log4j2 with your project's dependency management tool. + + .. tabs:: + + .. tab:: Maven + :tabid: maven + + Add the following dependency to your ``pom.xml`` file. + + .. include:: /includes/logging-and-monitoring/log4j2-maven.rst + + .. tab:: Gradle + :tabid: gradle + + Add the following dependency to your ``build.gradle`` file. + + .. include:: /includes/logging-and-monitoring/log4j2-gradle.rst + + Once you have included the preceding dependency, log an error by using the + following code: + + .. code-block:: kotlin + + import org.slf4j.Logger; + import org.slf4j.LoggerFactory; + + ... + + val logger = LoggerFactory.getLogger("MyApp"); + logger.error("Logging an Error"); + + The preceding code will ouput a message that resembles the following: + + .. code-block:: none + :copyable: false + + 12:35:00.438 [main] ERROR - Logging an Error + + .. note:: Default Log Level + + The default log level of Log4J2 is ERROR. This means that running + standard operations in the {+driver-short+} will not produce output + from Log4J2 without configuration. To learn how to change your Log4J2 + logger's log level, see the + :ref:`Configure Log Level ` section of this page. + +.. _kotlin-sync-configure-log-level: + +Configure Log Level +------------------- + +You can configure the log level of your logger by using the configuration system of the logging +framework bound to SLF4J. The log level specifies a lower bound for how urgent a message +must be for the logger to output that message. + +Logger Configuration Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following example configures the log level to ``INFO``. Select the :guilabel:`Logback` or +:guilabel:`Log4j2` tab to see the corresponding syntax: + +.. tabs:: + + .. tab:: Logback + :tabid: Logback-binding + + Specify Logback configurations in a file named ``logback.xml``. + You must be able to access this file from your classpath. + + The Logback framework defines the following log levels ordered from most urgent to + least urgent: + + - ``ERROR`` + - ``WARN`` + - ``INFO`` + - ``DEBUG`` + - ``TRACE`` + + Set your ``logback.xml`` file to the following: + + .. code-block:: xml + + + + + + %-4relative [%thread] %-5level %logger{30} - %msg%n + + + + + + + + + To test that your logger configuration was successful, run the following + code: + + .. include:: /includes/logging-and-monitoring/logging.rst + + This code produces output that resembles the following: + + .. code-block:: none + :copyable: false + + ... + 1317 [cluster-ClusterId{value='', description='null'}-] INFO org.mongodb.driver.cluster - Discovered replica set primary + 1568 [main] INFO org.mongodb.driver.connection - Opened connection [connectionId{localValue:7, serverValue:}] to + + .. tabs:: + + .. tab:: Log4j2 + :tabid: Log4j2-binding + + Specify Log4j2 configurations in a file named ``log4j2.xml``. + You must be able to access this file from your classpath. + + The Log4j2 framework defines the following log levels, ordered from most urgent to + least urgent: + + - ``FATAL`` + - ``ERROR`` + - ``WARN`` + - ``INFO`` + - ``DEBUG`` + - ``TRACE`` + - ``ALL`` + + Set your ``log4j2.xml`` file to the following: + + .. code-block:: xml + + + + + + + + + + + + + + + + To test that your logger configuration was successful, run the following + code: + + .. include:: /includes/logging-and-monitoring/logging.rst + + This code produces output that resembles the following: + + .. code-block:: none + :copyable: false + + ... + 10:14:57.633 [cluster-ClusterId{value=, description='null'}-] INFO org.mongodb.driver.cluster - Discovered replica set primary + 10:14:57.790 [main] INFO org.mongodb.driver.connection - Opened connection [connectionId{localValue:7, serverValue:}] to + +Logger Names +------------ + +Your logger uses logger names to help organize different logging events. Logger names +are strings that form a hierarchy. A logger is an ancestor of another logger if its +name followed by a ``"."`` is a prefix of the other logger's name. For example, +``"grandparent"`` is an ancestor of ``"grandparent.parent"``, which is an ancestor of +``"grandparent.parent.child"``. A logger inherits the properties of its ancestor logger and +can also define its own properties. + +The {+driver-short+} defines the following logger names to organize different logging events: + +.. list-table:: + :widths: 40 60 + :header-rows: 1 + + * - Logger Name + - Description + + * - ``org.mongodb.driver.authenticator`` + - Logs authentication events + + * - ``org.mongodb.driver.client`` + - Logs events related to MongoClient instances + + * - ``org.mongodb.driver.cluster`` + - Logs events related to monitoring of MongoDB deployments + + * - ``org.mongodb.driver.connection`` + - Logs connections and connection pools + + * - ``org.mongodb.driver.connection.tls`` + - Logs TLS events + + * - ``org.mongodb.driver.operation`` + - Logs operations, including logging related to automatic retries + + * - ``org.mongodb.driver.protocol`` + - Logs commands sent to and replies received from MongoDB deployments + + * - ``org.mongodb.driver.uri`` + - Logs connection string parsing events + + * - ``org.mongodb.driver.management`` + - Logs Java Management Extensions (JMX) events + +Logger Name Example +~~~~~~~~~~~~~~~~~~~ + +The following example disables the root logger and sets the log level for the +``org.mongodb.driver.connection`` logger to ``DEBUG``. This will cause the driver to log +messages only related to connections and connection pools at the ``DEBUG`` level or higher. +Select the :guilabel:`Logback` or :guilabel:`Log4j2` tab to see the corresponding syntax: + +.. tabs:: + + .. tab:: Logback + :tabid: Logback-binding + + Set your ``logback.xml`` file to the following: + + .. code-block:: xml + :emphasize-lines: 10 + + + + + + %-4relative [%thread] %-5level %logger{30} - %msg%n + + + + + + + + + + To test that your logger configuration was successful, run the following + code. + + .. include:: /includes/logging-and-monitoring/logging.rst + + This code produces output that resembles the following. + + .. code-block:: none + :copyable: false + + ... + 829 [cluster-rtt-ClusterId{value='', description='null'}-] INFO org.mongodb.driver.connection - Opened connection [connectionId{localValue:2, serverValue:}] to + 977 [main] INFO org.mongodb.driver.connection - Opened connection [connectionId{localValue:7, serverValue:}] to + + .. tab:: Log4j2 + :tabid: Log4j2-binding + + Set your ``log4j2.xml`` file to the following: + + .. code-block:: xml + :emphasize-lines: 9 + + + + + + + + + + + + + + + + + To test that your logger configuration was successful, run the following + code. + + .. include:: /includes/logging-and-monitoring/logging.rst + + This code produces output that resembles the following: + + .. code-block:: none + :copyable: false + + ... + 15:40:23.005 [cluster-ClusterId{value='', description='null'}-] INFO org.mongodb.driver.connection - Opened connection [connectionId{localValue:3, serverValue:}] to + 15:40:23.159 [main] INFO org.mongodb.driver.connection - Opened connection [connectionId{localValue:7, serverValue:}] to + +Additional Information +---------------------- + +To learn more about MongoDB's logging capabilities, see :manual:`Log Messages ` in the {+mdb-server+} +manual. + +For complete information about the logging frameworks discussed in this guide, see the +following external documentation: + +- `SLF4J documentation `__ +- `Logback documentation `__ +- `Log4j2 documentation `__ +