Tracing and Logging

The driver utilizes the tracing crate to emit events at points of interest. To enable this, you must turn on the tracing-unstable feature flag.

Stability Guarantees

This functionality is considered unstable as the tracing crate has not reached 1.0 yet. Future minor versions of the driver may upgrade the tracing dependency to a new version which is not backwards-compatible with Subscribers that depend on older versions of tracing. Additionally, future minor releases may make changes such as:

  • add or remove tracing events
  • add or remove values attached to tracing events
  • change the types and/or names of values attached to tracing events
  • add or remove driver-defined tracing spans
  • change the severity level of tracing events

Such changes will be called out in release notes.

Event Targets

Currently, events are emitted under the following targets:

TargetDescription
mongodb::commandEvents describing commands sent to the database and their success or failure.
mongodb::server_selectionEvents describing the driver's process of selecting a server in the database deployment to send a command to.
mongodb::connectionEvents describing the behavior of driver connection pools and the connections they contain.

Consuming Events

To consume events in your application, in addition to enabling the tracing-unstable feature flag, you must either register a tracing-compatible subscriber or a log-compatible logger, as detailed in the following sections.

Consuming Events with tracing

To consume events with tracing, you will need to register a type implementing the tracing::Subscriber trait in your application, as discussed in the tracing docs.

Here's a minimal example of a program using the driver which uses a tracing subscriber.

First, add the following to Cargo.toml:

tracing = "LATEST_VERSION_HERE"
tracing-subscriber = "LATEST_VERSION_HERE"
mongodb = { version = "LATEST_VERSION_HERE", features = ["tracing-unstable"] }

And then in main.rs:

extern crate mongodb;
extern crate tokio;
extern crate tracing_subscriber;
use std::env;
use mongodb::{bson::doc, error::Result, Client};

#[tokio::main]
async fn main() -> Result<()> {
    // Register a global tracing subscriber which will obey the RUST_LOG environment variable
    // config.
    tracing_subscriber::fmt::init();

    // Create a MongoDB client.
    let mongodb_uri =
        env::var("MONGODB_URI").expect("The MONGODB_URI environment variable was not set.");
    let client = Client::with_uri_str(mongodb_uri).await?;

    // Insert a document.
    let coll = client.database("test").collection("test_coll");
    coll.insert_one(doc! { "x" : 1 }, None).await?;

    Ok(())
}

This program can be run from the command line as follows, using the RUST_LOG environment variable to configure verbosity levels and observe command-related events with severity debug or higher:

RUST_LOG='mongodb::command=debug' MONGODB_URI='YOUR_URI_HERE' cargo run

The output will look something like the following:

2023-02-03T19:20:16.091822Z DEBUG mongodb::command: Command started topologyId="63dd5e706af9908fc834fd94" command="{\"insert\":\"test_coll\",\"ordered\":true,\"$db\":\"test\",\"lsid\":{\"id\":{\"$binary\":{\"base64\":\"y/v7PiLaRwOhT0RBFRDtNw==\",\"subType\":\"04\"}}},\"documents\":[{\"_id\":{\"$oid\":\"63dd5e706af9908fc834fd95\"},\"x\":1}]}" databaseName="test" commandName="insert" requestId=4 driverConnectionId=1 serverConnectionId=16 serverHost="localhost" serverPort=27017
2023-02-03T19:20:16.092700Z DEBUG mongodb::command: Command succeeded topologyId="63dd5e706af9908fc834fd94" reply="{\"n\":1,\"ok\":1.0}" commandName="insert" requestId=4 driverConnectionId=1 serverConnectionId=16 serverHost="localhost" serverPort=27017 durationMS=0

Consuming Events with log

Alternatively, to consume events with log, you will need to add tracing as a dependency of your application, and enable either its log or log-always feature. Those features are described in detail here.

Here's a minimal example of a program using the driver which uses env_logger.

In Cargo.toml:

tracing = { version = "LATEST_VERSION_HERE", features = ["log"] }
mongodb = { version = "LATEST_VERSION_HERE", features = ["tracing-unstable"] }
env_logger = "LATEST_VERSION_HERE"

And in main.rs:

extern crate mongodb;
extern crate tokio;
extern crate env_logger;
use std::env;
use mongodb::{bson::doc, error::Result, Client};

#[tokio::main]
async fn main() -> Result<()> {
    // Register a global logger.
    env_logger::init();

    // Create a MongoDB client.
    let mongodb_uri =
        env::var("MONGODB_URI").expect("The MONGODB_URI environment variable was not set.");
    let client = Client::with_uri_str(mongodb_uri).await?;

    // Insert a document.
    let coll = client.database("test").collection("test_coll");
    coll.insert_one(doc! { "x" : 1 }, None).await?;

    Ok(())
}

This program can be run from the command line as follows, using the RUST_LOG environment variable to configure verbosity levels and observe command-related messages with severity debug or higher:

RUST_LOG='mongodb::command=debug' MONGODB_URI='YOUR_URI_HERE' cargo run

The output will look something like the following:

2023-02-03T19:20:16.091822Z DEBUG mongodb::command: Command started topologyId="63dd5e706af9908fc834fd94" command="{\"insert\":\"test_coll\",\"ordered\":true,\"$db\":\"test\",\"lsid\":{\"id\":{\"$binary\":{\"base64\":\"y/v7PiLaRwOhT0RBFRDtNw==\",\"subType\":\"04\"}}},\"documents\":[{\"_id\":{\"$oid\":\"63dd5e706af9908fc834fd95\"},\"x\":1}]}" databaseName="test" commandName="insert" requestId=4 driverConnectionId=1 serverConnectionId=16 serverHost="localhost" serverPort=27017
2023-02-03T19:20:16.092700Z DEBUG mongodb::command: Command succeeded topologyId="63dd5e706af9908fc834fd94" reply="{\"n\":1,\"ok\":1.0}" commandName="insert" requestId=4 driverConnectionId=1 serverConnectionId=16 serverHost="localhost" serverPort=27017 durationMS=0