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 53 pub 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]: ../index.html#compile-time-filters 66 pub const STATIC_MAX_LEVEL: LevelFilter = MAX_LEVEL; 67 68 cfg_if! { 69 if #[cfg(all(not(debug_assertions), feature = "release_max_level_off"))] { 70 const MAX_LEVEL: LevelFilter = LevelFilter::OFF; 71 } else if #[cfg(all(not(debug_assertions), feature = "release_max_level_error"))] { 72 const MAX_LEVEL: LevelFilter = LevelFilter::ERROR; 73 } else if #[cfg(all(not(debug_assertions), feature = "release_max_level_warn"))] { 74 const MAX_LEVEL: LevelFilter = LevelFilter::WARN; 75 } else if #[cfg(all(not(debug_assertions), feature = "release_max_level_info"))] { 76 const MAX_LEVEL: LevelFilter = LevelFilter::INFO; 77 } else if #[cfg(all(not(debug_assertions), feature = "release_max_level_debug"))] { 78 const MAX_LEVEL: LevelFilter = LevelFilter::DEBUG; 79 } else if #[cfg(all(not(debug_assertions), feature = "release_max_level_trace"))] { 80 const MAX_LEVEL: LevelFilter = LevelFilter::TRACE; 81 } else if #[cfg(feature = "max_level_off")] { 82 const MAX_LEVEL: LevelFilter = LevelFilter::OFF; 83 } else if #[cfg(feature = "max_level_error")] { 84 const MAX_LEVEL: LevelFilter = LevelFilter::ERROR; 85 } else if #[cfg(feature = "max_level_warn")] { 86 const MAX_LEVEL: LevelFilter = LevelFilter::WARN; 87 } else if #[cfg(feature = "max_level_info")] { 88 const MAX_LEVEL: LevelFilter = LevelFilter::INFO; 89 } else if #[cfg(feature = "max_level_debug")] { 90 const MAX_LEVEL: LevelFilter = LevelFilter::DEBUG; 91 } else { 92 const MAX_LEVEL: LevelFilter = LevelFilter::TRACE; 93 } 94 } 95