Add tracing crate

Fixes #706

Author: joshka

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"

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)

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}}

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:
+
+<!-- 
+    Generated using https://crates.io/crates/to-html, running:
+    RUST_LOG=trace to-html --no-prompt  "cargo run --quiet --example=tracing-console
+-->
+
+<pre class="terminal"><code><span style='opacity:0.67'>2024-12-01T07:56:14.778440Z</span> <span style='color:var(--red,#a00)'>ERROR</span> <span style='opacity:0.67'>tracing_console:</span> This is an error!
+<span style='opacity:0.67'>2024-12-01T07:56:14.778568Z</span> <span style='color:var(--yellow,#a60)'> WARN</span> <span style='opacity:0.67'>tracing_console:</span> This is a warning.
+<span style='opacity:0.67'>2024-12-01T07:56:14.778596Z</span> <span style='color:var(--green,#0a0)'> INFO</span> <span style='opacity:0.67'>tracing_console:</span> This is an informational message.
+</code></pre>
+
+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:
+
+<pre class="terminal"><code><span style='opacity:0.67'>2024-12-01T07:56:14.778613Z</span> <span style='color:var(--blue,#00a)'>DEBUG</span> <span style='opacity:0.67'>tracing_console:</span> This is a debug message.
+<span style='opacity:0.67'>2024-12-01T07:56:14.778640Z</span> <span style='color:var(--magenta,#a0a)'>TRACE</span> <span style='opacity:0.67'>tracing_console:</span> This is a trace message.
+</code></pre>

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