1//! Trace verbosity level filtering.
2//!
3//! # Compile time filters
4//!
5//! Trace verbosity levels can be statically disabled at compile time via Cargo
6//! features, similar to the [`log` crate]. Trace instrumentation at disabled
7//! levels will be skipped and will not even be present in the resulting binary
8//! unless the verbosity level is specified dynamically. This level is
9//! configured separately for release and debug builds. The features are:
10//!
11//! * `max_level_off`
12//! * `max_level_error`
13//! * `max_level_warn`
14//! * `max_level_info`
15//! * `max_level_debug`
16//! * `max_level_trace`
17//! * `release_max_level_off`
18//! * `release_max_level_error`
19//! * `release_max_level_warn`
20//! * `release_max_level_info`
21//! * `release_max_level_debug`
22//! * `release_max_level_trace`
23//!
24//! These features control the value of the `STATIC_MAX_LEVEL` constant. The
25//! instrumentation macros macros check this value before recording an event or
26//! constructing a span. By default, no levels are disabled.
27//!
28//! For example, a crate can disable trace level instrumentation in debug builds
29//! and trace, debug, and info level instrumentation in release builds with the
30//! following configuration:
31//!
32//! ```toml
33//! [dependencies]
34//! tracing = { version = "0.1", features = ["max_level_debug", "release_max_level_warn"] }
35//! ```
36//! ## Notes
37//!
38//! Please note that `tracing`'s static max level features do *not* control the
39//! [`log`] records that may be emitted when [`tracing`'s "log" feature flag][f] is
40//! enabled. This is to allow `tracing` to be disabled entirely at compile time
41//! while still emitting `log` records --- such as when a library using
42//! `tracing` is used by an application using `log` that doesn't want to
43//! generate any `tracing`-related code, but does want to collect `log` records.
44//!
45//! This means that if the "log" feature is in use, some code may be generated
46//! for `log` records emitted by disabled `tracing` events. If this is not
47//! desirable, `log` records may be disabled separately using [`log`'s static
48//! max level features][`log` crate].
49//!
50//! [`log`]: https://docs.rs/log/
51//! [`log` crate]: https://docs.rs/log/latest/log/#compile-time-filters
52//! [f]: https://docs.rs/tracing/latest/tracing/#emitting-log-records
53pub use tracing_core::{metadata::ParseLevelFilterError, LevelFilter};
54
55/// The statically configured maximum trace level.
56///
57/// See the [module-level documentation] for information on how to configure
58/// this.
59///
60/// This value is checked by the `event!` and `span!` macros. Code that
61/// manually constructs events or spans via the `Event::record` function or
62/// `Span` constructors should compare the level against this value to
63/// determine if those spans or events are enabled.
64///
65/// [module-level documentation]: self#compile-time-filters
66pub const STATIC_MAX_LEVEL: LevelFilter = get_max_level_inner();
67
68const fn get_max_level_inner() -> LevelFilter {
69 if cfg!(not(debug_assertions)) {
70 if cfg!(feature = "release_max_level_off") {
71 LevelFilter::OFF
72 } else if cfg!(feature = "release_max_level_error") {
73 LevelFilter::ERROR
74 } else if cfg!(feature = "release_max_level_warn") {
75 LevelFilter::WARN
76 } else if cfg!(feature = "release_max_level_info") {
77 LevelFilter::INFO
78 } else if cfg!(feature = "release_max_level_debug") {
79 LevelFilter::DEBUG
80 } else {
81 // Same as branch cfg!(feature = "release_max_level_trace")
82 LevelFilter::TRACE
83 }
84 } else if cfg!(feature = "max_level_off") {
85 LevelFilter::OFF
86 } else if cfg!(feature = "max_level_error") {
87 LevelFilter::ERROR
88 } else if cfg!(feature = "max_level_warn") {
89 LevelFilter::WARN
90 } else if cfg!(feature = "max_level_info") {
91 LevelFilter::INFO
92 } else if cfg!(feature = "max_level_debug") {
93 LevelFilter::DEBUG
94 } else {
95 // Same as branch cfg!(feature = "max_level_trace")
96 LevelFilter::TRACE
97 }
98}
99