Tracing & Logging

Overview

In this guide, you can learn how to use the Rust driver to configure tracing and logging for your application. Tracing and logging are two frameworks for observing your application. Logging allows you to view a discrete, event-based log of driver activities, while tracing provides a continuous view.

In the Rust driver, the functionalities of tracing and logging do not differ greatly. However, when you enable tracing, the driver emits messages in a more structured format, which can make it more convenient for your application to consume event messages programmatically.

Tracers and loggers log messages at a severity, or verbosity, level that you can specify. By enabling one of these components in your application, you can receive information about your application's activities at different levels of detail.

Enable Tracing and Logging

The driver implements the tracing crate to enable the driver to emit messages for driver events.

To enable tracing, logging, or both, you must add the tracing dependency and the tracing-unstable feature flag to your mongodb dependency in your Cargo.toml file:

[dependencies]
tracing = "0.1.37"
[dependencies.mongodb]
version = "3.1.0"
features = ["tracing-unstable"]

The following table describes components that you can emit events against and their corresponding targets:

To specify the logging component and severity level, you can set the RUST_LOG environment variable when you compile and run your application. Specify the logging component by setting the value of RUST_LOG to one of the targets provided in the preceding table and including a severity level.

The following code shows a command to execute a program that records connection events at the debug level:

$ RUST_LOG='mongodb::connection=debug' cargo run

The following sections describe how to consume events using either tracing or logging.

Implement Tracing

To enable tracing, you must also add the tracing-subscriber dependency to your Cargo.toml file. The following code shows a sample dependencies list that contains the driver dependencies and the tracing-subscriber crate:

[dependencies]
tracing = "0.1.37"
tracing-subscriber = "0.3.17"
[dependencies.mongodb]
version = "3.1.0"
features = ["tracing-unstable"]

Then, in your application, you must register a type implementing the tracing::Subscriber trait to consume events with tracing. The following code shows how to register a tracing subscriber that uses the specifications of the RUST_LOG environment variable:

tracing_subscriber::fmt::init();

If you run your application and trace against commands at the debug level, the driver emits messages whenever you execute an operation. The following code shows the command for this tracing specification:

$ RUST_LOG='mongodb::command=debug' cargo run

With debug level tracing specified, when you perform a write operation, the driver generates trace messages:

let my_coll = client.database("db").collection("test_coll");
my_coll.insert_one(doc! { "x" : 1 }).await?;

2023-07-21T17:37:13.587794Z DEBUG mongodb::command: Command started topologyId="..." command="{\"insert\":\"test_coll\", ...}" databaseName="test" commandName="insert" requestId=12 driverConnectionId=1 serverConnectionId=133839 serverHost="..." serverPort=27017
2023-07-21T17:37:13.630401Z DEBUG mongodb::command: Command succeeded topologyId="..." reply="{\"n\":1, ...}" commandName="insert" requestId=12 driverConnectionId=1 serverConnectionId=133839 serverHost="..." serverPort=27017 durationMS=42

Implement Logging

To enable logging, you must also add the log or log-always feature flag to the tracing dependency in your Cargo.toml file. You must also add a dependency for a logging crate, such as env_logger:

[dependencies]
tracing = { version = "0.1.37", features = ["log"] }
env_logger = "0.10.0"
[dependencies.mongodb]
version = "3.1.0"
features = ["tracing-unstable"]

Then, in your application, you must register a global logger to consume events with logging. The following code shows how to register a logger that uses the specifications of the RUST_LOG environment variable:

env_logger::init();

If you run your application and log against connections at the debug level, the driver emits messages whenever you open, use, and close a connection. The following code shows the command for this logging specification:

$ RUST_LOG='mongodb::connection=debug' cargo run

With debug level tracing specified, when you open and use a connection, the driver generates log messages:

let my_coll = client.database("db").collection("test_coll");
my_coll.insert_one(doc! { "x" : 1 }).await?;

[2023-07-21T18:13:00Z DEBUG mongodb::connection] Connection pool created topologyId="..." serverHost="..." serverPort=27017
[2023-07-21T18:13:00Z DEBUG mongodb::connection] Connection pool created topologyId="..." serverHost="..." serverPort=27017
[2023-07-21T18:13:00Z DEBUG mongodb::connection] Connection pool created topologyId="..." serverHost="..." serverPort=27017
[2023-07-21T18:13:00Z DEBUG mongodb::connection] Connection pool ready topologyId="..." serverHost="..." serverPort=27017
[2023-07-21T18:13:00Z DEBUG mongodb::connection] Connection checkout started topologyId="..." serverHost="..." serverPort=27017
[2023-07-21T18:13:00Z DEBUG mongodb::connection] Connection created topologyId="..." serverHost="..." serverPort=27017 driverConnectionId=1
...

Additional Information

To learn more about setting client options, see the guide on Connection Options.