Docs Menu

Docs HomeDevelop ApplicationsMongoDB DriversRust Driver

Tracing & Logging

On this page

  • Overview
  • Enable Tracing and Logging
  • Implement Tracing
  • Implement Logging
  • Additional Information

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.

Tip

To learn more about logging severity levels, see the Wikipedia entry on the Syslog standard for message logging.

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

Important

tracing Crate is Unstable

Because the tracing crate does not have a 1.0 version release, you can consider the functionality to be unstable.

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 = "2.8.2"
features = ["tracing-unstable"]

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

Component
Target
Description
Command
mongodb::command
Events describe commands sent to the database and whether they succeed or fail.
Server selection
mongodb::server_selection
Events describe the driver's process of selecting a server in a MongoDB deployment.
Connection
mongodb::connection
Events describe the behavior of driver connection pools and the connections they contain.

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.

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 = "2.8.2"
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();

Tip

To learn more about registering a subscriber, see the tracing documentation.

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 }, None).await?;

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 = "2.8.2"
features = ["tracing-unstable"]

Tip

To learn more about the log and log-always flags, see the tracing documentation.

To learn more about the third-party logging crate env_logger, see its documentation.

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();

Tip

Alternative Logging Configurations

To see examples of other ways to configure the logger, visit the env_logger GitHub repository.

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 }, None).await?;

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

Tip

Monitoring

In addition to logging, you can enable monitoring in your application. To learn more, see the Monitoring guides.

←  Time Series CollectionsRun a Command →