Tracing & Logging
On this page
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.
Tip
To learn more about logging severity levels, see the Wikipedia entry on the Syslog standard for message logging.
Enable Tracing and 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 = "3.1.0" 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.
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();
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 }).await?;
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"]
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 }).await?;
Additional Information
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.