diff --git a/snooty.toml b/snooty.toml index 1f20e7e9..c0c9ebdd 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 00000000..525ee65b --- /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 00000000..a573f3c9 --- /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 00000000..2308da3e --- /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 00000000..8e5737d3 --- /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 00000000..f2658537 --- /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 4aa780f6..a2287066 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 ee9285ea..01b57477 100644 --- a/source/logging-and-monitoring/logging.txt +++ b/source/logging-and-monitoring/logging.txt @@ -8,4 +8,403 @@ 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.833 [main] DEBUG org.mongodb.driver.connection - Checkout started for connection to + 12:14:55.834 [main] DEBUG org.mongodb.driver.connection - Connection created: address=, driver-generated ID=3 + 12:14:55.836 [main] DEBUG org.mongodb.driver.connection - Connection ready: address=, driver-generated ID=3, established in=4 ms + 12:14:55.843 [main] DEBUG org.mongodb.driver.connection - Connection checked out: address=, driver-generated ID=3, duration=9 ms + + .. 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 + + ... + 317 [main] INFO org.mongodb.driver.client - MongoClient with metadata {"driver": {"name": "", "version": ""}, "os": {"type": "", "name": "", "architecture": "", "version": ""}, "platform": ""} created with settings + 345 [cluster-ClusterId{value='', description='null'}-] INFO org.mongodb.driver.cluster - Monitor thread successfully connected to server with description ServerDescription{address=, type=, cryptd=false, state=CONNECTED, ok=true, minWireVersion=0, maxWireVersion=, maxDocumentSize=16777216, logicalSessionTimeoutMinutes=30, roundTripTimeNanos=, minRoundTripTimeNanos= + + + + + + + + + + + + + + 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 + + ... + 21:19:25.696 [main] INFO org.mongodb.driver.client - MongoClient with metadata {"driver": {"name": "", "version": ""}, "os": {"type": "", "name": "", "architecture": "", "version": ""}, "platform": ""} created with settings + 21:19:25.710 [cluster-ClusterId{value='', description='null'}-] INFO org.mongodb.driver.cluster - Monitor thread successfully connected to server with description ServerDescription{address=, type=, cryptd=false, state=CONNECTED, ok=true, minWireVersion=0, maxWireVersion=, maxDocumentSize=16777216, logicalSessionTimeoutMinutes=30, roundTripTimeNanos=, minRoundTripTimeNanos= + + + + %-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 + + ... + 255 [main] DEBUG org.mongodb.driver.connection - Connection pool created for using options + 301 [cluster-ClusterId{value='', description='null'}-] DEBUG org.mongodb.driver.connection - Connection pool ready for + 321 [main] DEBUG org.mongodb.driver.connection - Checkout started for connection to + 323 [main] DEBUG org.mongodb.driver.connection - Connection created: address=, driver-generated ID=3 + 335 [main] DEBUG org.mongodb.driver.connection - Connection ready: address=, driver-generated ID=3, established in= ms + 336 [main] DEBUG org.mongodb.driver.connection - Connection checked out: address=, driver-generated ID=3, duration= ms + 363 [main] DEBUG org.mongodb.driver.connection - Connection checked in: address=, driver-generated ID=3 + + .. 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 + + ... + 21:27:17.035 [main] DEBUG org.mongodb.driver.connection - Connection pool created for using options + 21:27:17.058 [cluster-ClusterId{value='', description='null'}-] DEBUG org.mongodb.driver.connection - Connection pool ready for + 21:27:17.064 [main] DEBUG org.mongodb.driver.connection - Checkout started for connection to + 21:27:17.069 [main] DEBUG org.mongodb.driver.connection - Connection created: address=, driver-generated ID=3 + 21:27:17.075 [main] DEBUG org.mongodb.driver.connection - Connection ready: address=, driver-generated ID=3, established in= ms + 21:27:17.075 [main] DEBUG org.mongodb.driver.connection - Connection checked out: address=, driver-generated ID=3, duration= ms + 21:27:17.086 [main] DEBUG org.mongodb.driver.connection - Connection checked in: address=, driver-generated ID=3 + +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 `__ +