Merge pull request #30 from mongodben/DOCSP-29229

mongodben · web-flow · commit 39a6a8d0847e · 2023-05-03T12:26:37.000-04:00
(DOCSP-29229): Kotlin Logging page
diff --git a/examples/build.gradle.kts b/examples/build.gradle.kts
@@ -20,10 +20,9 @@ dependencies {
     implementation("org.slf4j:slf4j-api:1.7.32")
     implementation("ch.qos.logback:logback-classic:1.2.6")
     implementation("io.github.cdimascio:dotenv-kotlin:6.4.1")
+    implementation("org.apache.logging.log4j:log4j-slf4j-impl:2.17.1")
     implementation("io.netty:netty-all:4.1.91.Final")
     implementation("io.netty:netty-tcnative-boringssl-static:2.0.53.Final:${osdetector.classifier}")
-
-
 }
 
 tasks.test {
diff --git a/examples/src/test/kotlin/LoggingTest.kt b/examples/src/test/kotlin/LoggingTest.kt
@@ -0,0 +1,62 @@
+
+
+import InsertTest.Companion.client
+import com.mongodb.kotlin.client.coroutine.MongoClient
+import io.github.cdimascio.dotenv.dotenv
+import kotlinx.coroutines.flow.firstOrNull
+import kotlinx.coroutines.runBlocking
+import org.bson.Document
+import org.junit.jupiter.api.AfterAll
+import org.junit.jupiter.api.Assertions.*
+import org.junit.jupiter.api.TestInstance
+// :snippet-start: slf4j-import
+import org.slf4j.LoggerFactory
+// :snippet-end:
+import java.util.*
+import kotlin.test.*
+
+@TestInstance(TestInstance.Lifecycle.PER_CLASS)
+internal class LoggingTest {
+
+    companion object {
+        val dotenv = dotenv()
+        val CONNECTION_URI_PLACEHOLDER = dotenv["MONGODB_CONNECTION_URI"]
+        val DB_NAME_PLACEHOLDER = "logging"
+        val COLLECTION_NAME_PLACEHOLDER = "logging"
+
+        @AfterAll
+        @JvmStatic
+        private fun afterAll() {
+            runBlocking {
+                client.close()
+            }
+        }
+    }
+    @Test
+    fun triggerLogging() = runBlocking {
+        // :snippet-start: trigger-logging
+        val mongoClient = MongoClient.create(CONNECTION_URI_PLACEHOLDER);
+        val database = mongoClient.getDatabase(DB_NAME_PLACEHOLDER);
+        val collection = database.getCollection<Document>(COLLECTION_NAME_PLACEHOLDER);
+        collection.find().firstOrNull()
+        // :snippet-end:
+        assertEquals(null, collection.find().firstOrNull())
+
+        // clean up
+        if(collection.countDocuments() > 0){
+            collection.drop()
+        }
+    }
+
+    @Test
+    fun slf4jTest() {
+        // :snippet-start: slf4j
+        val loggerParent = LoggerFactory.getLogger("parent")
+        val loggerChild = LoggerFactory.getLogger("parent.child")
+        // :snippet-end:
+        assertEquals("parent", loggerParent.name)
+        assertEquals("parent.child", loggerChild.name)
+    }
+
+}
+
diff --git a/source/examples/generated/LoggingTest.snippet.slf4j-import.kt b/source/examples/generated/LoggingTest.snippet.slf4j-import.kt
@@ -0,0 +1 @@
+import org.slf4j.LoggerFactory
diff --git a/source/examples/generated/LoggingTest.snippet.slf4j.kt b/source/examples/generated/LoggingTest.snippet.slf4j.kt
@@ -0,0 +1,2 @@
+val loggerParent = LoggerFactory.getLogger("parent")
+val loggerChild = LoggerFactory.getLogger("parent.child")
diff --git a/source/examples/generated/LoggingTest.snippet.trigger-logging.kt b/source/examples/generated/LoggingTest.snippet.trigger-logging.kt
@@ -0,0 +1,4 @@
+val mongoClient = MongoClient.create(CONNECTION_URI_PLACEHOLDER);
+val database = mongoClient.getDatabase(DB_NAME_PLACEHOLDER);
+val collection = database.getCollection<Document>(COLLECTION_NAME_PLACEHOLDER);
+collection.find().firstOrNull()
diff --git a/source/fundamentals/logging.txt b/source/fundamentals/logging.txt
@@ -17,24 +17,14 @@ Logging
 Overview
 --------
 
-.. What is on this page?
-
 In this guide, you can learn how to set up and configure a logger in the
-MongoDB Java driver.
-
-.. What do any new terms mean?
-
-.. Not applicable. We are treating definition of logger as understood.
-
-.. What can you expect to see on this page?
+MongoDB Kotlin driver.
 
 You will learn how to:
 
 - Set up a logger using the Simple Logging Facade For Java (SLF4J)
 - Configure the log level of your logger
 
-.. Who should read this? Where should I go if this isn't the page I was looking for?
-
 This guide shows how to record events in the driver.
 If you would like to learn how to use information about the activity of the
 driver in code, consider reading our
@@ -49,13 +39,13 @@ logger and provides an example logger setup.
 Background
 ~~~~~~~~~~
 
-The MongoDB Java driver uses the Simple Logging Facade For Java (SLF4J).
+The MongoDB Kotlin driver uses the Simple Logging Facade For Java (SLF4J).
 SLF4J allows you to specify your logging framework of choice at deployment time.
 For more information on SLF4J,
 `see the SLF4J documentation <http://www.slf4j.org/>`__.
 
 Setting up a logger is optional. When you start your application the MongoDB
-Java driver looks for the ``slf4j-api`` artifact in your classpath. If the driver
+Kotlin driver looks for the ``slf4j-api`` artifact in your classpath. If the driver
 can't find the ``slf4j-api`` artifact, the driver logs the following warning with
 ``java.util.logging`` and disables all further logging:
 
@@ -118,24 +108,25 @@ tab corresponding to the logging framework you would like to use in your project
          .. tab:: Gradle
             :tabid: gradle
 
-            Add the following dependency to your ``build.gradle`` file.
+            Add the following dependency to your ``build.gradle.kts`` file:
 
             .. include:: /includes/logback-gradle-versioned.rst
 
       Once you have included the preceding dependency, connect to your
-      MongoDB instance and retrieve a document with the following code.
+      MongoDB instance and retrieve a document with the following code:
 
-      .. include:: /includes/fundamentals/logging.rst
+      .. io-code-block::
 
-      You should see output that resembles the following:
+         .. input:: /examples/generated/LoggingTest.snippet.trigger-logging.kt
+            :language: kotlin
 
-      .. code-block:: none
-         :copyable: false
+         .. output::
+            :language: console
 
-         ...
-         12:14:55.853 [main] DEBUG org.mongodb.driver.connection - Opened connection [connectionId{localValue:3, serverValue:3}] to <MongoDB hostname>
-         12:14:55.861 [main] DEBUG org.mongodb.driver.protocol.command - Command "find" started on database <database> using a connection with driver-generated ID 3 and server-generated ID 3 to <MongoDB hostname>. The request ID is 5. Command: {"find": "<collection>", "filter": {}, "limit": 1, "singleBatch": true, "$db": "<database>", "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 <MongoDB hostname. The request ID is 5. Command reply: {"cursor": {"id": 0, "ns": "<database>.<collection>", "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}}}
+            ...
+            12:14:55.853 [main] DEBUG org.mongodb.driver.connection - Opened connection [connectionId{localValue:3, serverValue:3}] to <MongoDB hostname>
+            12:14:55.861 [main] DEBUG org.mongodb.driver.protocol.command - Command "find" started on database <database> using a connection with driver-generated ID 3 and server-generated ID 3 to <MongoDB hostname>. The request ID is 5. Command: {"find": "<collection>", "filter": {}, "limit": 1, "singleBatch": true, "$db": "<database>", "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 <MongoDB hostname. The request ID is 5. Command reply: {"cursor": {"id": 0, "ns": "<database>.<collection>", "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
 
@@ -163,34 +154,30 @@ tab corresponding to the logging framework you would like to use in your project
          .. tab:: Gradle
             :tabid: gradle
 
-            Add the following dependency to your ``build.gradle`` file.
+            Add the following dependency to your ``build.gradle.kts`` file.
 
             .. include:: /includes/log4j2-gradle-versioned.rst
 
       Once you have included the preceding dependency, log an error using the
-      following code.
+      following code:
 
-      .. code-block:: java
+      .. literalinclude:: /examples/generated/LoggingTest.snippet.slf4j.kt
+         :language: kotlin
 
-         import org.slf4j.Logger;
-         import org.slf4j.LoggerFactory;
+      .. io-code-block::
 
-         ...
+         .. input:: /examples/generated/LoggingTest.snippet.slf4j.kt
+            :language: kotlin
 
-         Logger logger = LoggerFactory.getLogger("MyApp");
-         logger.error("Logging an Error");
+         .. output::
+            :language: console
 
-      You should see output that resembles the following:
-
-      .. code-block:: none
-         :copyable: false
-
-         12:35:00.438 [main] ERROR <my package path> - Logging an Error
+            12:35:00.438 [main] ERROR <my package path> - Logging an Error
 
       .. note:: Default Log Level
 
          The default log level of Log4J2 is ERROR. This means that running
-         standard operations in the MongoDB Java driver will not produce output
+         standard operations in the MongoDB Kotlin driver will not produce output
          from Log4J2 without configuration. To learn how to change your Log4J2
          logger's log level, see the
          :ref:`example in the Configure Your Logger section of this page <configure-log-level>`.
@@ -259,16 +246,17 @@ project.
       To test that your logger configuration was successful, run the following
       code.
 
-      .. include:: /includes/fundamentals/logging.rst
+      .. io-code-block::
 
-      You should see output that resembles the following.
+         .. input:: /examples/generated/LoggingTest.snippet.trigger-logging.kt
+            :language: kotlin
 
-      .. code-block:: none
-         :copyable: false
+         .. output::
+            :language: console
 
-         ...
-         1317 [cluster-ClusterId{value='<your cluster id>', description='null'}-<your connection uri>] INFO  org.mongodb.driver.cluster - Discovered replica set primary <your connection uri>
-         1568 [main] INFO  org.mongodb.driver.connection - Opened connection [connectionId{localValue:7, serverValue:<server value>}] to <your connection uri>
+            ...
+            1317 [cluster-ClusterId{value='<your cluster id>', description='null'}-<your connection uri>] INFO  org.mongodb.driver.cluster - Discovered replica set primary <your connection uri>
+            1568 [main] INFO  org.mongodb.driver.connection - Opened connection [connectionId{localValue:7, serverValue:<server value>}] to <your connection uri>
 
       For more information on configuring Logback, see the
       `the Logback Manual <https://logback.qos.ch/manual/configuration.html>`__.
@@ -314,16 +302,17 @@ project.
       To test that your logger configuration was successful, run the following
       code.
 
-      .. include:: /includes/fundamentals/logging.rst
+      .. io-code-block::
 
-      You should see output that resembles the following.
+         .. input:: /examples/generated/LoggingTest.snippet.trigger-logging.kt
+            :language: kotlin
 
-      .. code-block:: none
-         :copyable: false
+         .. output::
+            :language: console
 
-         ...
-         10:14:57.633 [cluster-ClusterId{value=<your cluster id>, description='null'}-<your connection uri>] INFO  org.mongodb.driver.cluster - Discovered replica set primary <your connection uri>
-         10:14:57.790 [main] INFO  org.mongodb.driver.connection - Opened connection [connectionId{localValue:7, serverValue:<your server value>}] to <your connection uri>
+            ...
+            10:14:57.633 [cluster-ClusterId{value=<your cluster id>, description='null'}-<your connection uri>] INFO  org.mongodb.driver.cluster - Discovered replica set primary <your connection uri>
+            10:14:57.790 [main] INFO  org.mongodb.driver.connection - Opened connection [connectionId{localValue:7, serverValue:<your server value>}] to <your connection uri>
 
       For more information on configuring Log4j2, see the official
       `Log4j2 configuration guide
@@ -340,22 +329,18 @@ ancestor of ``"grandparent.parent.child"``.
 
 For a concrete example, this is what a logger hierarchy looks like in code.
 
-.. code-block:: java
-
-   import org.slf4j.Logger;
-   import org.slf4j.LoggerFactory;
+.. literalinclude:: /examples/generated/LoggingTest.snippet.slf4j-import.kt
+   :language: kotlin
 
-   ...
-
-   Logger logger_parent = LoggerFactory.getLogger("parent");
-   Logger logger_child = LoggerFactory.getLogger("parent.child");
+.. literalinclude:: /examples/generated/LoggingTest.snippet.slf4j.kt
+   :language: kotlin
 
 A logger inherits the properties of its ancestor logger and can define
-its own. You can think of this as similar to class inheritance in Java.
+its own. You can think of this as similar to class inheritance in Kotlin.
 
-The MongoDB Java driver defines the following logger names to organize different
+The MongoDB Kotlin driver defines the following logger names to organize different
 logging events in the driver. Here are the logger names defined in the driver
-and the logging events they correspond to.
+and the logging events they correspond to:
 
 * ``org.mongodb.driver.authenticator`` : authentication
 * ``org.mongodb.driver.client`` : events related to ``MongoClient`` instances
@@ -404,18 +389,19 @@ project.
          </configuration>
 
       To test that your logger configuration was successful, run the following
-      code.
+      code:
 
-      .. include:: /includes/fundamentals/logging.rst
+      .. io-code-block::
 
-      You should see output that resembles the following.
+         .. input:: /examples/generated/LoggingTest.snippet.trigger-logging.kt
+            :language: kotlin
 
-      .. code-block:: none
-         :copyable: false
+         .. output::
+            :language: console
 
-         ...
-         829  [cluster-rtt-ClusterId{value='<some value>', description='null'}-<your connection URI>] INFO  org.mongodb.driver.connection - Opened connection [connectionId{localValue:2, serverValue:<your server value>}] to <your connection uri>
-         977  [main] INFO  org.mongodb.driver.connection - Opened connection [connectionId{localValue:7, serverValue:<your server value>}] to <your connection uri>
+            ...
+            829  [cluster-rtt-ClusterId{value='<some value>', description='null'}-<your connection URI>] INFO  org.mongodb.driver.connection - Opened connection [connectionId{localValue:2, serverValue:<your server value>}] to <your connection uri>
+            977  [main] INFO  org.mongodb.driver.connection - Opened connection [connectionId{localValue:7, serverValue:<your server value>}] to <your connection uri>
 
       For more information on configuring Logback, see the
       `official Logback configuration guide <https://logback.qos.ch/manual/configuration.html#syntax>`__.
@@ -448,16 +434,17 @@ project.
       To test that your logger configuration was successful, run the following
       code.
 
-      .. include:: /includes/fundamentals/logging.rst
+      .. io-code-block::
 
-      You should see output that resembles the following.
+         .. input:: /examples/generated/LoggingTest.snippet.trigger-logging.kt
+            :language: kotlin
 
-      .. code-block:: none
-         :copyable: false
+         .. output::
+            :language: console
 
-         ...
-         15:40:23.005 [cluster-ClusterId{value='<some value>', description='null'}-<your connection uri>] INFO  org.mongodb.driver.connection - Opened connection [connectionId{localValue:3, serverValue:<your server value>}] to <your connection uri>
-         15:40:23.159 [main] INFO  org.mongodb.driver.connection - Opened connection [connectionId{localValue:7, serverValue:<your server value>}] to <your connection uri>
+            ...
+            15:40:23.005 [cluster-ClusterId{value='<some value>', description='null'}-<your connection uri>] INFO  org.mongodb.driver.connection - Opened connection [connectionId{localValue:3, serverValue:<your server value>}] to <your connection uri>
+            15:40:23.159 [main] INFO  org.mongodb.driver.connection - Opened connection [connectionId{localValue:7, serverValue:<your server value>}] to <your connection uri>
 
       For more information on configuring Log4j2, see the
       `official Log4J2 configuration guide <https://logging.apache.org/log4j/2.x/manual/configuration.html>`__.
diff --git a/source/includes/log4j2-gradle-versioned.rst b/source/includes/log4j2-gradle-versioned.rst
@@ -1,6 +1,6 @@
 .. code-block:: groovy
 
    dependencies {
-     implementation 'org.apache.logging.log4j:log4j-slf4j-impl:{+log4j2Version+}'
+     implementation("org.apache.logging.log4j:log4j-slf4j-impl:{+log4j2Version+}")
    }
 
diff --git a/source/includes/logback-gradle-versioned.rst b/source/includes/logback-gradle-versioned.rst
@@ -1,6 +1,6 @@
-.. code-block:: groovy
+.. code-block:: kotlin
 
    dependencies {
-      implementation 'ch.qos.logback:logback-classic:{+logbackVersion+}'
+      implementation("ch.qos.logback:logback-classic:{+logbackVersion+}")
    }
 

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+val loggerParent = LoggerFactory.getLogger("parent")`
	`2`	`+val loggerChild = LoggerFactory.getLogger("parent.child")`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`.. code-block:: groovy`
`2`	`2`
`3`	`3`	`dependencies {`
`4`		`- implementation 'org.apache.logging.log4j:log4j-slf4j-impl:{+log4j2Version+}'`
	`4`	`+ implementation("org.apache.logging.log4j:log4j-slf4j-impl:{+log4j2Version+}")`
`5`	`5`	`}`
`6`	`6`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`		`-.. code-block:: groovy`
	`1`	`+.. code-block:: kotlin`
`2`	`2`
`3`	`3`	`dependencies {`
`4`		`- implementation 'ch.qos.logback:logback-classic:{+logbackVersion+}'`
	`4`	`+ implementation("ch.qos.logback:logback-classic:{+logbackVersion+}")`
`5`	`5`	`}`
`6`	`6`