Skip to content

Commit

Permalink
Merge pull request #282 from epage/syntax
Browse files Browse the repository at this point in the history
docs(ref): Improve scannability of RUST_LOG docs
  • Loading branch information
epage authored Nov 10, 2023
2 parents 85dde7d + 2eff19f commit 6f64347
Showing 1 changed file with 36 additions and 47 deletions.
83 changes: 36 additions & 47 deletions src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -85,78 +85,67 @@
//!
//! ## Enabling logging
//!
//! Log levels are controlled on a per-module basis, and **by default all
//! logging is disabled except for the `error` level**.
//! **By default all logging is disabled except for the `error` level**
//!
//! Logging is controlled via the **`RUST_LOG`** environment variable. The
//! value of this environment variable is a comma-separated list of *logging
//! directives*. A logging directive is of the form:
//! The **`RUST_LOG`** environment variable controls logging with the syntax:
//! ```text
//! RUST_LOG=[target][=][level][,...]
//! ```
//! Or in other words, its a comma-separated list of directives.
//! Directives can filter by **target**, by **level**, or both (using `=`).
//!
//! For example,
//! ```text
//! example::log::target=level
//! RUST_LOG=data=debug,hardware=debug
//! ```
//!
//! The log target is typically equal to the path of the module the message
//! **target** is typically the path of the module the message
//! in question originated from, though it can be overridden.
//!
//! The path is rooted in the name of the crate it was compiled for, so if
//! your program is in a file called, for example, `hello.rs`, the path would
//! simply be `hello`.
//!
//! Furthermore, the log can be filtered using prefix-search based on the
//! specified log target. A value of, for example, `RUST_LOG=example`, would
//! match all of the messages with targets:
//! specified log target.
//!
//! * `example`
//! * `example::test`
//! * `example::test::module::submodule`
//! * `examples::and_more_examples`
//! For example, `RUST_LOG=example` would match the following targets:
//! - `example`
//! - `example::test`
//! - `example::test::module::submodule`
//! - `examples::and_more_examples`
//!
//! When providing the crate name or a module path, explicitly specifying the
//! log level is optional. If omitted, all logging for the item will be
//! enabled.
//!
//! The names of the log levels that may be specified correspond to the
//! variations of the [`log::Level`][level-enum] enum from the `log`
//! crate. They are:
//!
//! * `error`
//! * `warn`
//! * `info`
//! * `debug`
//! * `trace`
//! **level** is the maximum [`log::Level`][level-enum] to be shown and includes:
//! - `error`
//! - `warn`
//! - `info`
//! - `debug`
//! - `trace`
//! - `off` (pseudo level to disable all logging for the target)
//!
//! There is also a pseudo logging level, `off`, which may be specified to
//! disable all logging for a given module or for the entire application. As
//! with the logging levels, the letter case is not significant[^fn-off].
//!
//! [^fn-off]: Similar to the universe of log level names, the `off` pseudo
//! log level feature is also provided by the underlying `log` crate.
//!
//! The letter case is not significant for the logging level names; e.g.,
//! Logging level names are case-insensitive; e.g.,
//! `debug`, `DEBUG`, and `dEbuG` all represent the same logging level. For
//! consistency, our convention is to use the lower case names. Where our docs
//! do use other forms, they do so in the context of specific examples, so you
//! won't be surprised if you see similar usage in the wild.
//!
//! As the log level for a module is optional, the module to enable logging for
//! is also optional. **If only a level is provided, then the global log
//! level for all modules is set to this value.**
//!
//! Some examples of valid values of `RUST_LOG` are:
//!
//! * `hello` turns on all logging for the 'hello' module
//! * `trace` turns on all logging for the application, regardless of its name
//! * `TRACE` turns on all logging for the application, regardless of its name (same as previous)
//! * `info` turns on all info logging
//! * `INFO` turns on all info logging (same as previous)
//! * `hello=debug` turns on debug logging for 'hello'
//! * `hello=DEBUG` turns on debug logging for 'hello' (same as previous)
//! * `hello,std::option` turns on hello, and std's option logging
//! * `error,hello=warn` turn on global error logging and also warn for hello
//! * `error,hello=off` turn on global error logging, but turn off logging for hello
//! * `off` turns off all logging for the application
//! * `OFF` turns off all logging for the application (same as previous)
//! - `RUST_LOG=hello` turns on all logging for the `hello` module
//! - `RUST_LOG=trace` turns on all logging for the application, regardless of its name
//! - `RUST_LOG=TRACE` turns on all logging for the application, regardless of its name (same as previous)
//! - `RUST_LOG=info` turns on all info logging
//! - `RUST_LOG=INFO` turns on all info logging (same as previous)
//! - `RUST_LOG=hello=debug` turns on debug logging for `hello`
//! - `RUST_LOG=hello=DEBUG` turns on debug logging for `hello` (same as previous)
//! - `RUST_LOG=hello,std::option` turns on `hello`, and std's option logging
//! - `RUST_LOG=error,hello=warn` turn on global error logging and also warn for `hello`
//! - `RUST_LOG=error,hello=off` turn on global error logging, but turn off logging for `hello`
//! - `RUST_LOG=off` turns off all logging for the application
//! - `RUST_LOG=OFF` turns off all logging for the application (same as previous)
//!
//! ## Filtering results
//!
Expand Down

0 comments on commit 6f64347

Please sign in to comment.