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

MongoClient mongoClient = MongoClients.create(<my uri>);
MongoDatabase database = mongoClient.getDatabase(<my database>);
MongoCollection<Document> collection = database.getCollection(<my collection>);
collection.find().first();

You should see output that resembles the following:

...
16:03:59.468 [main] DEBUG org.mongodb.driver.connection - Opened connection [connectionId{localValue:7, serverValue:<server value>}] to <connection uri>
16:03:59.483 [main] DEBUG org.mongodb.driver.protocol.command - Sending command '{"find": "<my collection>", "filter": {}, "limit": 1, "singleBatch": true, "$db": "<my database>", "lsid": {"id": {"$binary": {"base64": "<_id>", "subType": "04"}}}}' with request id 13 to database <my database> on connection [connectionId{localValue:7, serverValue:<server value>}] to server <connection uri>
16:03:59.502 [main] DEBUG org.mongodb.driver.protocol.command - Execution of command with request id 13 completed successfully in 27.79 ms on connection [connectionId{localValue:7, serverValue:<server value>}] to server <connection uri>

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

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
...
Logger logger = LoggerFactory.getLogger("MyApp");
logger.error("Logging an Error");

You should see output that resembles the following:

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

MongoClient mongoClient = MongoClients.create(<my uri>);
MongoDatabase database = mongoClient.getDatabase(<my database>);
MongoCollection<Document> collection = database.getCollection(<my collection>);
collection.find().first();

You should see output that resembles the following.

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

MongoClient mongoClient = MongoClients.create(<my uri>);
MongoDatabase database = mongoClient.getDatabase(<my database>);
MongoCollection<Document> collection = database.getCollection(<my collection>);
collection.find().first();

You should see output that resembles the following.

...
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.Logger;
import org.slf4j.LoggerFactory;
...
Logger logger_parent = LoggerFactory.getLogger("parent");
Logger logger_child = 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 Java.

The MongoDB Java 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 deployments
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 deployments
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.

MongoClient mongoClient = MongoClients.create(<my uri>);
MongoDatabase database = mongoClient.getDatabase(<my database>);
MongoCollection<Document> collection = database.getCollection(<my collection>);
collection.find().first();

You should see output that resembles the following.

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

MongoClient mongoClient = MongoClients.create(<my uri>);
MongoDatabase database = mongoClient.getDatabase(<my database>);
MongoCollection<Document> collection = database.getCollection(<my collection>);
collection.find().first();

You should see output that resembles the following.

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

Monitoring

Logging.leafygreen-ui-m0pgrr{-webkit-align-self:center;-ms-flex-item-align:center;align-self:center;padding:0 10px;visibility:hidden;}.leafygreen-ui-a30zj9{color:#889397;vertical-align:middle;margin-top:-2px;}.css-1l4s55v{margin-top:-175px;position:absolute;padding-bottom:2px;}

Overview

Set Up a Logger

Background

Note

Example - Set Up

Tip

Dependency Versions

Note

Default Log Level

Note

Default Log Level

Configure Your Logger

Example - Configure

Logger Names

Example - Names

Logging