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]: self#compile-time-filters
66 pub const STATIC_MAX_LEVEL: LevelFilter = get_max_level_inner();
67
get_max_level_inner() -> LevelFilter68 const 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