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]: super#compile-time-filters |
66 | pub const STATIC_MAX_LEVEL: LevelFilter = MAX_LEVEL; |
67 | |
68 | cfg_if::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 | |