Docs Menu
Docs Home
/
Languages
/
Kotlin
/
Kotlin Coroutine
/
Fundamentals

Logging

On this page

  • Overview
  • Set Up a Logger
  • Background
  • Example - Set Up
  • Configure Your Logger
  • Example - Configure
  • Logger Names
  • Example - Names

Overview

In this guide, you can learn how to set up and configure a logger in the 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

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 guide on monitoring.

Set Up a Logger

This section gives background on the dependencies necessary to set up a logger and provides an example logger setup.

Background

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.

Setting up a logger is optional. When you start your application the MongoDB 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:

WARNING: SLF4J not found on the classpath.  Logging is disabled for the 'org.mongodb.driver' component

To set up a logger, you must include the following in your project.

  • The slf4j-api artifact

  • A logging framework

  • A binding

Note

For the most popular logging frameworks, there is often a single binding artifact that lists the slf4j-api and the logging framework as dependencies. This means that you can set up a logger by adding one artifact to your project's dependency list. You will see this in the example below.

A binding is a piece of code that connects the slf4j-api artifact with a logging framework. The following example shows how to bind the slf4j-api artifact to the two most popular logging frameworks, Log4j2 and Logback.

Example - Set Up

This example shows how to set up your logger. Click the tab corresponding to the logging framework you would like to use in your project.

Tip

Dependency Versions

The following versions listed are illustrative rather than a source of truth. You should check the official documentation for SLF4J and your logging framework of choice for guaranteed up-to-date version information.

Select the build tool you are using in your project.

Add the following dependency to your pom.xml file.

<dependencies>
  <dependency>
    <groupId>ch.qos.logback</groupId>
    <artifactId>logback-classic</artifactId>
    <version>1.2.11</version>
  </dependency>
</dependencies>

Add the following dependency to your build.gradle.kts file:

dependencies {
   implementation("ch.qos.logback:logback-classic:1.2.11")
}

Once you have included the preceding dependency, connect to your MongoDB instance and retrieve a document with the following code:

val mongoClient = MongoClient.create("<connection string>");
val database = mongoClient.getDatabase(DB_NAME_PLACEHOLDER);
val collection = database.getCollection<Document>(COLLECTION_NAME_PLACEHOLDER);
collection.find().firstOrNull()
...
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

The default log level of Logback is DEBUG. To learn how to change your Logback logger's log level, see the example in the Configure Your Logger section of this page.

For more information on Logback, see the Logback manual.

Select the build tool you are using in your project.

Add the following dependency to your pom.xml file.

<dependencies>
  <dependency>
    <groupId>org.apache.logging.log4j</groupId>
    <artifactId>log4j-slf4j-impl</artifactId>
    <version>2.17.1</version>
  </dependency>
</dependencies>

Add the following dependency to your build.gradle.kts file.

dependencies {
  implementation("org.apache.logging.log4j:log4j-slf4j-impl:2.17.1")
}

Once you have included the preceding dependency, log an error using the following code:

val loggerParent = LoggerFactory.getLogger("parent")
val loggerChild = LoggerFactory.getLogger("parent.child")
val loggerParent = LoggerFactory.getLogger("parent")
val loggerChild = LoggerFactory.getLogger("parent.child")
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 Kotlin driver will not produce output from Log4J2 without configuration. To learn how to change your Log4J2 logger's log level, see the example in the Configure Your Logger section of this page.

For more information on Log4j2, see the Log4j2 manual.

Configure Your Logger

To configure your logger, you must use the configuration system of the logging framework bound to SLF4J.

In the following example we show how you can use your logging framework's configuration system to set your logger's log level.

A logger's log level specifies a lower bound for how urgent a message must be for the logger to output that message.

Example - Configure

This example shows how to configure your logger's log level to INFO. Select the tab corresponding to the logging framework you are using in your project.

Specify Logback configurations in a file named logback.xml. Your logback.xml file does not have to be in a specific location, but it must be accessible from your classpath.

The Logback framework defines the following log levels. The following lists the log levels, ordered from most urgent to least urgent:

  • ERROR

  • WARN

  • INFO

  • DEBUG

  • TRACE

Set your logback.xml file to the following.

<configuration>
   <appender name="CONSOLE"
             class="ch.qos.logback.core.ConsoleAppender">
      <encoder>
         <pattern>
               %-4relative [%thread] %-5level %logger{30} - %msg%n
         </pattern>
      </encoder>
   </appender>
   <root level="INFO">
      <appender-ref ref="CONSOLE" />
   </root>
</configuration>

To test that your logger configuration was successful, run the following code.

val mongoClient = MongoClient.create("<connection string>");
val database = mongoClient.getDatabase(DB_NAME_PLACEHOLDER);
val collection = database.getCollection<Document>(COLLECTION_NAME_PLACEHOLDER);
collection.find().firstOrNull()
...
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.

Specify Log4j2 configurations in a file named log4j2.xml. Your log4j2.xml file does not have to be in a specific location, but it must be accessible from your classpath.

The Log4j2 framework defines the following log levels. The following lists the log levels, ordered from most urgent to least urgent:

  • FATAL

  • ERROR

  • WARN

  • INFO

  • DEBUG

  • TRACE

  • ALL

Set your log4j2.xml file to the following.

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="INFO">
   <Appenders>
      <Console name="Console" target="SYSTEM_OUT">
            <PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n"/>
      </Console>
   </Appenders>
   <Loggers>
      <Root level="INFO">
            <AppenderRef ref="Console"/>
      </Root>
   </Loggers>
</Configuration>

To test that your logger configuration was successful, run the following code.

val mongoClient = MongoClient.create("<connection string>");
val database = mongoClient.getDatabase(DB_NAME_PLACEHOLDER);
val collection = database.getCollection<Document>(COLLECTION_NAME_PLACEHOLDER);
collection.find().firstOrNull()
...
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.

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".

For a concrete example, this is what a logger hierarchy looks like in code.

import org.slf4j.LoggerFactory
val loggerParent = LoggerFactory.getLogger("parent")
val loggerChild = LoggerFactory.getLogger("parent.child")

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 Kotlin.

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:

  • org.mongodb.driver.authenticator : authentication

  • org.mongodb.driver.client : events related to MongoClient instances

  • org.mongodb.driver.cluster : monitoring of MongoDB servers

  • org.mongodb.driver.connection : connections and connection pools

  • org.mongodb.driver.connection.tls : TLS/SSL

  • org.mongodb.driver.operation : operations, including logging related to automatic retries

  • org.mongodb.driver.protocol : commands sent to and replies received from MongoDB servers

  • org.mongodb.driver.uri : connection string parsing

  • org.mongodb.driver.management : JMX (Java Management Extensions)

Example - Names

This example shows how to change the log level for a specific driver logger. We set the root logger to OFF and the org.mongodb.driver.connection logger to INFO. This will cause the application to only log messages related to connecting to a MongoDB instance.

Select the tab corresponding to the logging framework you are using in your project.

Set your logback.xml file to the following.

<configuration>
   <appender name="CONSOLE"
             class="ch.qos.logback.core.ConsoleAppender">
      <encoder>
         <pattern>
               %-4relative [%thread] %-5level %logger{30} - %msg%n
         </pattern>
      </encoder>
   </appender>
   <logger name="org.mongodb.driver.connection" level="INFO" additivity="true"/>
   <root level="OFF">
      <appender-ref ref="CONSOLE" />
   </root>
</configuration>

To test that your logger configuration was successful, run the following code:

val mongoClient = MongoClient.create("<connection string>");
val database = mongoClient.getDatabase(DB_NAME_PLACEHOLDER);
val collection = database.getCollection<Document>(COLLECTION_NAME_PLACEHOLDER);
collection.find().firstOrNull()
...
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.

Set your log4j2.xml file to the following.

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="INFO">
   <Appenders>
      <Console name="Console" target="SYSTEM_OUT">
            <PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n"/>
      </Console>
   </Appenders>
   <Loggers>
      <Logger name="org.mongodb.driver.connection" level="INFO"/>
      <Root level="OFF">
            <AppenderRef ref="Console"/>
      </Root>
   </Loggers>
</Configuration>

To test that your logger configuration was successful, run the following code.

val mongoClient = MongoClient.create("<connection string>");
val database = mongoClient.getDatabase(DB_NAME_PLACEHOLDER);
val collection = database.getCollection<Document>(COLLECTION_NAME_PLACEHOLDER);
collection.find().firstOrNull()
...
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.

Back

Collations

Next

Monitoring