From 25b4dd42434df07ff5a653c12906b183e437f021 Mon Sep 17 00:00:00 2001 From: Josh McKinney Date: Wed, 1 Oct 2025 14:32:47 -0700 Subject: [PATCH] Add tracing crate Fixes https://github.com/rust-lang-nursery/rust-cookbook/issues/706 --- Cargo.toml | 4 +- src/SUMMARY.md | 2 + src/development_tools/debugging/tracing.md | 17 +++++++ .../debugging/tracing/tracing-console.md | 50 +++++++++++++++++++ src/links.md | 4 ++ 5 files changed, 76 insertions(+), 1 deletion(-) create mode 100644 src/development_tools/debugging/tracing.md create mode 100644 src/development_tools/debugging/tracing/tracing-console.md diff --git a/Cargo.toml b/Cargo.toml index fb2b2b67..6170fea2 100755 --- a/Cargo.toml +++ b/Cargo.toml @@ -61,8 +61,10 @@ tempfile = "3.14" thiserror = "2" anyhow = "1.0" threadpool = "1.8" -toml = "0.8" tokio = { version = "1", features = ["full"] } +toml = "0.8" +tracing = "0.1" +tracing-subscriber = "0.3" unicode-segmentation = "1.2.1" url = "2.5" walkdir = "2.5" diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 9318d355..933565e2 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -2,6 +2,7 @@ [Table of Contents](intro.md) [About](about.md) + - [Algorithms](algorithms.md) - [Generate Random Values](algorithms/randomness.md) - [Sort a Vector](algorithms/sorting.md) @@ -28,6 +29,7 @@ - [Debugging](development_tools/debugging.md) - [Log Messages](development_tools/debugging/log.md) - [Configure Logging](development_tools/debugging/config_log.md) + - [Tracing Messages](development_tools/debugging/tracing.md) - [Versioning](development_tools/versioning.md) - [Build Time Tooling](development_tools/build_tools.md) - [Encoding](encoding.md) diff --git a/src/development_tools/debugging/tracing.md b/src/development_tools/debugging/tracing.md new file mode 100644 index 00000000..2a0d675e --- /dev/null +++ b/src/development_tools/debugging/tracing.md @@ -0,0 +1,17 @@ +# Tracing + +[`tracing`](https://crates.io/crates/tracing) is a framework for instrumenting Rust programs to +collect structured, event-based diagnostic information. It is alternative to the older +[`log`](https://crates.io/crates/log) crate and has adapters to be backwards compatible. + +To enable tracing in your applicaiont, add the following crates to your project: + +```shell +cargo add tracing tracing-subscriber +``` + +For libraries, tracing-subscriber is usually not required. + +{{#include tracing/tracing-console.md}} + +{{#include ../../links.md}} diff --git a/src/development_tools/debugging/tracing/tracing-console.md b/src/development_tools/debugging/tracing/tracing-console.md new file mode 100644 index 00000000..c2111eeb --- /dev/null +++ b/src/development_tools/debugging/tracing/tracing-console.md @@ -0,0 +1,50 @@ +## Log messages to the console + +[![tracing-badge]][tracing] [![tracing-subscriber-badge]][tracing-subscriber] [![cat-debugging-badge]][cat-debugging] + +The `tracing` crate provides macros to emit log events to a tracing subscriber. The +`tracing-subscriber` crate configures where to send the events. To install the default tracing +subscriber, call [`tracing_subscriber::fmt::init()`]. + +[`tracing_subscriber::fmt::init()`]: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/fn.init.html + +```rust +use tracing::{debug, error, info, trace, warn}; + +fn main() { + tracing_subscriber::fmt::init(); + + error!("This is an error!"); + warn!("This is a warning."); + info!("This is an informational message."); + + // with the default configuration, debug! and trace! messages are not shown + debug!("This is a debug message."); + trace!("This is a trace message."); +} +``` + +The default log level is `INFO`. Tracing will drop events logged at lower levels. Running this code +prints the following to the console: + + + +
2024-12-01T07:56:14.778440Z ERROR tracing_console: This is an error!
+2024-12-01T07:56:14.778568Z  WARN tracing_console: This is a warning.
+2024-12-01T07:56:14.778596Z  INFO tracing_console: This is an informational message.
+
+ +To configure a more verbose default level, set the `RUST_LOG` environment variable: + +```shell +RUST_LOG=trace cargo run --example log-debug +``` + +Cargo prints these following extra lines in addition to the ones above: + +
2024-12-01T07:56:14.778613Z DEBUG tracing_console: This is a debug message.
+2024-12-01T07:56:14.778640Z TRACE tracing_console: This is a trace message.
+
diff --git a/src/links.md b/src/links.md index d916e45e..6ceb16b3 100644 --- a/src/links.md +++ b/src/links.md @@ -143,6 +143,10 @@ Keep lines sorted. [threadpool]: https://docs.rs/threadpool/ [toml-badge]: https://badge-cache.kominick.com/crates/v/toml.svg?label=toml [toml]: https://docs.rs/toml/ +[tracing-badge]: https://badge-cache.kominick.com/crates/v/tracing.svg?label=tracing +[tracing]: https://docs.rs/tracing/ +[tracing-subscriber-badge]: https://badge-cache.kominick.com/crates/v/tracing-subscriber.svg?label=tracing-subscriber +[tracing-subscriber]: https://docs.rs/tracing-subscriber/ [url-badge]: https://badge-cache.kominick.com/crates/v/url.svg?label=url [url]: https://docs.rs/url/ [unicode-segmentation-badge]: https://badge-cache.kominick.com/crates/v/unicode-segmentation.svg?label=unicode-segmentation