]>
Commit | Line | Data |
---|---|---|
f035d41b XL |
1 | //! Utilities for implementing and composing [`tracing`] subscribers. |
2 | //! | |
3 | //! [`tracing`] is a framework for instrumenting Rust programs to collect | |
4 | //! scoped, structured, and async-aware diagnostics. The [`Subscriber`] trait | |
5 | //! represents the functionality necessary to collect this trace data. This | |
6 | //! crate contains tools for composing subscribers out of smaller units of | |
7 | //! behaviour, and batteries-included implementations of common subscriber | |
8 | //! functionality. | |
9 | //! | |
10 | //! `tracing-subscriber` is intended for use by both `Subscriber` authors and | |
11 | //! application authors using `tracing` to instrument their applications. | |
12 | //! | |
29967ef6 XL |
13 | //! *Compiler support: [requires `rustc` 1.42+][msrv]* |
14 | //! | |
15 | //! [msrv]: #supported-rust-versions | |
16 | //! | |
f035d41b XL |
17 | //! ## Included Subscribers |
18 | //! | |
19 | //! The following `Subscriber`s are provided for application authors: | |
20 | //! | |
21 | //! - [`fmt`] - Formats and logs tracing data (requires the `fmt` feature flag) | |
22 | //! | |
23 | //! ## Feature Flags | |
24 | //! | |
25 | //! - `env-filter`: Enables the [`EnvFilter`] type, which implements filtering | |
26 | //! similar to the [`env_logger` crate]. Enabled by default. | |
27 | //! - `fmt`: Enables the [`fmt`] module, which provides a subscriber | |
28 | //! implementation for printing formatted representations of trace events. | |
29 | //! Enabled by default. | |
30 | //! - `ansi`: Enables `fmt` support for ANSI terminal colors. Enabled by | |
31 | //! default. | |
32 | //! - `registry`: enables the [`registry`] module. Enabled by default. | |
33 | //! - `json`: Enables `fmt` support for JSON output. In JSON output, the ANSI feature does nothing. | |
34 | //! | |
35 | //! ### Optional Dependencies | |
36 | //! | |
37 | //! - [`tracing-log`]: Enables better formatting for events emitted by `log` | |
38 | //! macros in the `fmt` subscriber. On by default. | |
39 | //! - [`chrono`]: Enables human-readable time formatting in the `fmt` subscriber. | |
40 | //! Enabled by default. | |
41 | //! - [`smallvec`]: Causes the `EnvFilter` type to use the `smallvec` crate (rather | |
42 | //! than `Vec`) as a performance optimization. Enabled by default. | |
43 | //! - [`parking_lot`]: Use the `parking_lot` crate's `RwLock` implementation | |
44 | //! rather than the Rust standard library's implementation. | |
45 | //! | |
29967ef6 XL |
46 | //! ## Supported Rust Versions |
47 | //! | |
48 | //! Tracing is built against the latest stable release. The minimum supported | |
49 | //! version is 1.42. The current Tracing version is not guaranteed to build on | |
50 | //! Rust versions earlier than the minimum supported version. | |
51 | //! | |
52 | //! Tracing follows the same compiler support policies as the rest of the Tokio | |
53 | //! project. The current stable Rust compiler and the three most recent minor | |
54 | //! versions before it will always be supported. For example, if the current | |
55 | //! stable compiler version is 1.45, the minimum supported version will not be | |
56 | //! increased past 1.42, three minor versions prior. Increasing the minimum | |
57 | //! supported compiler version is not considered a semver breaking change as | |
58 | //! long as doing so complies with this policy. | |
59 | //! | |
f035d41b XL |
60 | //! [`tracing`]: https://docs.rs/tracing/latest/tracing/ |
61 | //! [`Subscriber`]: https://docs.rs/tracing-core/latest/tracing_core/subscriber/trait.Subscriber.html | |
62 | //! [`EnvFilter`]: filter/struct.EnvFilter.html | |
63 | //! [`fmt`]: fmt/index.html | |
64 | //! [`tracing-log`]: https://crates.io/crates/tracing-log | |
65 | //! [`smallvec`]: https://crates.io/crates/smallvec | |
66 | //! [`chrono`]: https://crates.io/crates/chrono | |
67 | //! [`env_logger` crate]: https://crates.io/crates/env_logger | |
68 | //! [`parking_lot`]: https://crates.io/crates/parking_lot | |
69 | //! [`registry`]: registry/index.html | |
6a06907d | 70 | #![doc(html_root_url = "https://docs.rs/tracing-subscriber/0.2.16")] |
3dfed10e | 71 | #![doc( |
29967ef6 | 72 | html_logo_url = "https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/logo-type.png", |
3dfed10e XL |
73 | issue_tracker_base_url = "https://github.com/tokio-rs/tracing/issues/" |
74 | )] | |
29967ef6 | 75 | #![cfg_attr(docsrs, feature(doc_cfg), deny(broken_intra_doc_links))] |
f035d41b XL |
76 | #![warn( |
77 | missing_debug_implementations, | |
78 | missing_docs, | |
79 | rust_2018_idioms, | |
80 | unreachable_pub, | |
81 | bad_style, | |
82 | const_err, | |
83 | dead_code, | |
84 | improper_ctypes, | |
85 | non_shorthand_field_patterns, | |
86 | no_mangle_generic_items, | |
87 | overflowing_literals, | |
88 | path_statements, | |
89 | patterns_in_fns_without_body, | |
90 | private_in_public, | |
91 | unconditional_recursion, | |
92 | unused, | |
93 | unused_allocation, | |
94 | unused_comparisons, | |
95 | unused_parens, | |
96 | while_true | |
97 | )] | |
5869c6ff XL |
98 | // Using struct update syntax when a struct has no additional fields avoids |
99 | // a potential source change if additional fields are added to the struct in the | |
100 | // future, reducing diff noise. Allow this even though clippy considers it | |
101 | // "needless". | |
102 | #![allow(clippy::needless_update)] | |
103 | ||
f035d41b XL |
104 | use tracing_core::span::Id; |
105 | ||
106 | #[macro_use] | |
107 | macro_rules! try_lock { | |
108 | ($lock:expr) => { | |
109 | try_lock!($lock, else return) | |
110 | }; | |
111 | ($lock:expr, else $els:expr) => { | |
112 | if let Ok(l) = $lock { | |
113 | l | |
114 | } else if std::thread::panicking() { | |
115 | $els | |
116 | } else { | |
117 | panic!("lock poisoned") | |
118 | } | |
119 | }; | |
120 | } | |
121 | ||
122 | pub mod field; | |
123 | pub mod filter; | |
124 | #[cfg(feature = "fmt")] | |
125 | #[cfg_attr(docsrs, doc(cfg(feature = "fmt")))] | |
126 | pub mod fmt; | |
127 | pub mod layer; | |
128 | pub mod prelude; | |
129 | pub mod registry; | |
130 | pub mod reload; | |
131 | pub(crate) mod sync; | |
132 | pub(crate) mod thread; | |
133 | pub mod util; | |
134 | ||
135 | #[cfg(feature = "env-filter")] | |
136 | #[cfg_attr(docsrs, doc(cfg(feature = "env-filter")))] | |
137 | pub use filter::EnvFilter; | |
138 | ||
139 | pub use layer::Layer; | |
140 | ||
141 | #[cfg(feature = "registry")] | |
142 | #[cfg_attr(docsrs, doc(cfg(feature = "registry")))] | |
143 | pub use registry::Registry; | |
144 | ||
145 | /// | |
146 | #[cfg(feature = "registry")] | |
147 | #[cfg_attr(docsrs, doc(cfg(feature = "registry")))] | |
148 | pub fn registry() -> Registry { | |
149 | Registry::default() | |
150 | } | |
151 | ||
152 | #[cfg(feature = "fmt")] | |
153 | #[cfg_attr(docsrs, doc(cfg(feature = "fmt")))] | |
154 | pub use fmt::Subscriber as FmtSubscriber; | |
155 | ||
156 | #[cfg(feature = "fmt")] | |
157 | #[cfg_attr(docsrs, doc(cfg(feature = "fmt")))] | |
158 | pub use fmt::fmt; | |
159 | ||
160 | use std::default::Default; | |
161 | /// Tracks the currently executing span on a per-thread basis. | |
162 | #[derive(Debug)] | |
163 | pub struct CurrentSpan { | |
164 | current: thread::Local<Vec<Id>>, | |
165 | } | |
166 | ||
167 | impl CurrentSpan { | |
168 | /// Returns a new `CurrentSpan`. | |
169 | pub fn new() -> Self { | |
170 | Self { | |
171 | current: thread::Local::new(), | |
172 | } | |
173 | } | |
174 | ||
175 | /// Returns the [`Id`] of the span in which the current thread is | |
176 | /// executing, or `None` if it is not inside of a span. | |
177 | /// | |
178 | /// | |
179 | /// [`Id`]: https://docs.rs/tracing/latest/tracing/span/struct.Id.html | |
180 | pub fn id(&self) -> Option<Id> { | |
181 | self.current.with(|current| current.last().cloned())? | |
182 | } | |
183 | ||
184 | /// Records that the current thread has entered the span with the provided ID. | |
185 | pub fn enter(&self, span: Id) { | |
186 | self.current.with(|current| current.push(span)); | |
187 | } | |
188 | ||
189 | /// Records that the current thread has exited a span. | |
190 | pub fn exit(&self) { | |
191 | self.current.with(|current| { | |
192 | let _ = current.pop(); | |
193 | }); | |
194 | } | |
195 | } | |
196 | ||
197 | impl Default for CurrentSpan { | |
198 | fn default() -> Self { | |
199 | Self::new() | |
200 | } | |
201 | } | |
202 | ||
203 | mod sealed { | |
204 | pub trait Sealed<A = ()> {} | |
205 | } |