Log Driver Events

Overview

In this guide, you can learn how to use the Ruby driver to configure logging for your application. Logging allows you to view a discrete, event-based log of driver activities.

Loggers log messages at a severity, or verbosity, level that you can specify. When you enable logging in your application, you can receive information about your application's activities at different levels of detail. The driver allows you to log information categorized at the following severity levels:

unknown
fatal
error
warn
info
debug

The preceding list is ordered by decreasing severity level, with unknown as the highest severity level. When you specify a severity level, the driver also logs all messages with higher severity levels. For example, if you set the log level to error, the driver will also log messages with fatal and unknown severity levels.

The lower the severity level you specify, the more information the driver logs, which might impact the performance of your application.

Create a Logger

To configure your application to receive messages about driver events, create an instance of a Logger class. Optionally, specify a logging severity level. If you don't specify a severity level, the default severity level is INFO. Then, configure your Mongo::Client object to use the logger.

The following example performs the following actions:

Creates a logger and logs output to STDOUT. You can also log to a file by providing a file path.
Sets the severity level to DEBUG.
Configures the Mongo::Client to use the logger.
Tests the logger with an insert operation.

require 'mongo'
require 'logger'
# Create a new Logger instance
logger = Logger.new(STDOUT) # You can also log to a file by providing a file path
# Set the log level (optional)
logger.level = Logger::DEBUG # Options are DEBUG, INFO, WARN, ERROR, FATAL, UNKNOWN
# Configures the Mongo client to use the logger
client = Mongo::Client.new(['127.0.0.1:27017'], logger: logger)
# Tests the logger with an insert operation
client[:test_collection].insert_one({ name: 'Test' })

D, [2025-08-14T15:58:36.804464 ...] DEBUG -- : MONGODB | Topology type 'unknown' initializing.
D, [2025-08-14T15:58:36.804618 ...] DEBUG -- : MONGODB | There was a change in the members of the 'Unknown' topology.
D, [2025-08-14T15:58:36.804694 ...] DEBUG -- : MONGODB | Server 127.0.0.1:27017 initializing.
D, [2025-08-14T15:58:36.805036 ...] DEBUG -- : MONGODB | Waiting for up to 30.00 seconds for servers to be scanned: #<Cluster topology=Unknown[127.0.0.1:27017] servers=[#<Server address=127.0.0.1:27017 UNKNOWN>]>
D, [2025-08-14T15:58:36.817796 ...] DEBUG -- : MONGODB | Server description for 127.0.0.1:27017 changed from 'unknown' to 'standalone'.
D, [2025-08-14T15:58:36.818009 ...] DEBUG -- : MONGODB | Topology type 'Unknown' changed to type 'Single'.
D, [2025-08-14T15:58:36.819403 ...] DEBUG -- : MONGODB | 127.0.0.1:27017 req:6 conn:1:1 sconn:15 | admin.insert | STARTED | {"insert"=>"test_collection", "ordered"=>true, "documents"=>[{"name"=>"Test", "_id"=>BSON::ObjectId('689e3fec1524159575156479')}]..., ...}
D, [2025-08-14T15:58:36.835978 ...] DEBUG -- : MONGODB | 127.0.0.1:27017 req:6 | admin.insert | SUCCEEDED | 0.017s

The logger output contains the time of the operation, the severity level of the message, and the log message.

Set a Global Logging Level

You can set a global logging level, so you don't have to manually set a severity level for each logger. The following example shows how to set a global logging level:

# Sets the logger level globally
Mongo::Logger.level == LOGGER.DEBUG

API Documentation

For more information about logger options for the Ruby driver, see the following API documentation:

Back

Monitoring

Change Streams