gix_trace/
lib.rs

1//! A crate providing macros for creating spans in various detail levels. `coarse!` should be used for top-level operations, whereas
2//! `detail!` should be used in plumbing crates unless their operations are likely to cost a lot of time.
3//!
4//! The application is supposed to explicitly turn on tracing via `gix-features`.
5//! Crates that use `gix-features` should use `gix_features::trace`, and those who don't can use `gix_trace` directly.
6//! ## Feature Flags
7#![cfg_attr(
8    all(doc, feature = "document-features"),
9    doc = ::document_features::document_features!()
10)]
11#![cfg_attr(all(doc, feature = "document-features"), feature(doc_cfg, doc_auto_cfg))]
12#![deny(missing_docs, rust_2018_idioms, unsafe_code)]
13
14/// The level at which the tracing item should be created.
15///
16/// It's used to filter items early.
17#[derive(Debug, Copy, Clone, PartialEq, Eq, Ord, PartialOrd)]
18pub enum Level {
19    /// A coarse-grained trace level, one that should span entire operations with low frequency.
20    Coarse = 1,
21    /// Finer grained trace level that further subdivides coarse-level traces.
22    ///
23    /// Note that these should only be created for areas of the code which have significant cost.
24    Detail = 2,
25}
26
27/// The maximum allowed level for tracing items, as compiled in.
28#[cfg(feature = "tracing-detail")]
29pub const MAX_LEVEL: Level = Level::Detail;
30/// The maximum allowed level for tracing items, as compiled in.
31#[cfg(not(feature = "tracing-detail"))]
32pub const MAX_LEVEL: Level = Level::Coarse;
33
34#[cfg(feature = "tracing")]
35mod enabled;
36
37#[cfg(feature = "tracing")]
38pub use enabled::{field, Span};
39
40impl Span {
41    /// Execute `f` in with this span active, consuming it.
42    pub fn into_scope<T>(self, f: impl FnOnce() -> T) -> T {
43        f()
44    }
45}
46
47#[cfg(feature = "tracing")]
48#[doc(hidden)]
49pub use enabled::{metadata, Event, MetaOnlyCallsite, Metadata};
50
51#[cfg(not(feature = "tracing"))]
52mod disabled;
53#[cfg(not(feature = "tracing"))]
54pub use disabled::Span;
55
56///
57pub mod event {
58    #[cfg(feature = "tracing")]
59    pub use tracing_core::Level;
60
61    /// All available tracing levels for use in `event!()` macro.
62    #[cfg(not(feature = "tracing"))]
63    #[repr(usize)]
64    #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq)]
65    pub enum Level {
66        /// The "trace" level.
67        ///
68        /// Designates very low priority, often extremely verbose, information.
69        TRACE = 0,
70        /// The "debug" level.
71        ///
72        /// Designates lower priority information.
73        DEBUG = 1,
74        /// The "info" level.
75        ///
76        /// Designates useful information.
77        INFO = 2,
78        /// The "warn" level.
79        ///
80        /// Designates hazardous situations.
81        WARN = 3,
82        /// The "error" level.
83        ///
84        /// Designates very serious errors.
85        ERROR = 4,
86    }
87}
88
89/// Create a new [coarse][Level::Coarse] span.
90#[macro_export]
91macro_rules! coarse {
92    (target: $target:expr, $name:expr, $($field:tt)*) => {
93        $crate::span!(
94            target: $target,
95            $crate::Level::Coarse,
96            $name,
97            $($field)*
98        )
99    };
100    (target: $target:expr, $name:expr) => {
101        $crate::coarse!(target: $target, $name,)
102    };
103    ($name:expr, $($field:tt)*) => {
104        $crate::span!(
105            target: module_path!(),
106            $crate::Level::Coarse,
107            $name,
108            $($field)*
109        )
110    };
111    ($name:expr) => {$crate::coarse!($name,)};
112}
113
114/// Create a new [detail][Level::Detail] span.
115#[macro_export]
116macro_rules! detail {
117    (target: $target:expr, $name:expr, $($field:tt)*) => {
118        $crate::span!(
119            target: $target,
120            $crate::Level::Detail,
121            $name,
122            $($field)*
123        )
124    };
125    (target: $target:expr, $name:expr) => {
126        $crate::detail!(target: $target, $name,)
127    };
128    ($name:expr, $($field:tt)*) => {
129        $crate::span!(
130            target: module_path!(),
131            $crate::Level::Detail,
132            $name,
133            $($field)*
134        )
135    };
136    ($name:expr) => {$crate::coarse!($name,)};
137}
138
139/// Emit an error event.
140#[macro_export]
141macro_rules! error {
142    (target: $target:expr, { $($field:tt)* }, $($arg:tt)* ) => (
143        $crate::event!(target: $target, $crate::event::Level::ERROR, { $($field)* }, $($arg)*)
144    );
145    (target: $target:expr, $($k:ident).+ $($field:tt)* ) => (
146        $crate::event!(target: $target, $crate::event::Level::ERROR, { $($k).+ $($field)* })
147    );
148    (target: $target:expr, ?$($k:ident).+ $($field:tt)* ) => (
149        $crate::event!(target: $target, $crate::event::Level::ERROR, { ?$($k).+ $($field)* })
150    );
151    (target: $target:expr, %$($k:ident).+ $($field:tt)* ) => (
152        $crate::event!(target: $target, $crate::event::Level::ERROR, { %$($k).+ $($field)* })
153    );
154    (target: $target:expr, $($arg:tt)+ ) => (
155        $crate::event!(target: $target, $crate::event::Level::ERROR, {}, $($arg)+)
156    );
157    ({ $($field:tt)+ }, $($arg:tt)+ ) => (
158        $crate::event!(
159            target: module_path!(),
160            $crate::event::Level::ERROR,
161            { $($field)+ },
162            $($arg)+
163        )
164    );
165    ($($k:ident).+ = $($field:tt)*) => (
166        $crate::event!(
167            target: module_path!(),
168            $crate::event::Level::ERROR,
169            { $($k).+ = $($field)*}
170        )
171    );
172    (?$($k:ident).+ = $($field:tt)*) => (
173        $crate::event!(
174            target: module_path!(),
175            $crate::event::Level::ERROR,
176            { ?$($k).+ = $($field)*}
177        )
178    );
179    (%$($k:ident).+ = $($field:tt)*) => (
180        $crate::event!(
181            target: module_path!(),
182            $crate::event::Level::ERROR,
183            { %$($k).+ = $($field)*}
184        )
185    );
186    ($($k:ident).+, $($field:tt)*) => (
187        $crate::event!(
188            target: module_path!(),
189            $crate::event::Level::ERROR,
190            { $($k).+, $($field)*}
191        )
192    );
193    (?$($k:ident).+, $($field:tt)*) => (
194        $crate::event!(
195            target: module_path!(),
196            $crate::event::Level::ERROR,
197            { ?$($k).+, $($field)*}
198        )
199    );
200    (%$($k:ident).+, $($field:tt)*) => (
201        $crate::event!(
202            target: module_path!(),
203            $crate::event::Level::ERROR,
204            { %$($k).+, $($field)*}
205        )
206    );
207    (?$($k:ident).+) => (
208        $crate::event!(
209            target: module_path!(),
210            $crate::event::Level::ERROR,
211            { ?$($k).+ }
212        )
213    );
214    (%$($k:ident).+) => (
215        $crate::event!(
216            target: module_path!(),
217            $crate::event::Level::ERROR,
218            { %$($k).+ }
219        )
220    );
221    ($($k:ident).+) => (
222        $crate::event!(
223            target: module_path!(),
224            $crate::event::Level::ERROR,
225            { $($k).+ }
226        )
227    );
228    ($($arg:tt)+) => (
229        $crate::event!(
230            target: module_path!(),
231            $crate::event::Level::ERROR,
232            {},
233            $($arg)+
234        )
235    );
236}
237
238/// Emit a warn event.
239#[macro_export]
240macro_rules! warn {
241    (target: $target:expr, { $($field:tt)* }, $($arg:tt)* ) => (
242        $crate::event!(target: $target, $crate::event::Level::WARN, { $($field)* }, $($arg)*)
243    );
244    (target: $target:expr, $($k:ident).+ $($field:tt)* ) => (
245        $crate::event!(target: $target, $crate::event::Level::WARN, { $($k).+ $($field)* })
246    );
247    (target: $target:expr, ?$($k:ident).+ $($field:tt)* ) => (
248        $crate::event!(target: $target, $crate::event::Level::WARN, { ?$($k).+ $($field)* })
249    );
250    (target: $target:expr, %$($k:ident).+ $($field:tt)* ) => (
251        $crate::event!(target: $target, $crate::event::Level::WARN, { %$($k).+ $($field)* })
252    );
253    (target: $target:expr, $($arg:tt)+ ) => (
254        $crate::event!(target: $target, $crate::event::Level::WARN, {}, $($arg)+)
255    );
256    ({ $($field:tt)+ }, $($arg:tt)+ ) => (
257        $crate::event!(
258            target: module_path!(),
259            $crate::event::Level::WARN,
260            { $($field)+ },
261            $($arg)+
262        )
263    );
264    ($($k:ident).+ = $($field:tt)*) => (
265        $crate::event!(
266            target: module_path!(),
267            $crate::event::Level::WARN,
268            { $($k).+ = $($field)*}
269        )
270    );
271    (?$($k:ident).+ = $($field:tt)*) => (
272        $crate::event!(
273            target: module_path!(),
274            $crate::event::Level::WARN,
275            { ?$($k).+ = $($field)*}
276        )
277    );
278    (%$($k:ident).+ = $($field:tt)*) => (
279        $crate::event!(
280            target: module_path!(),
281            $crate::event::Level::WARN,
282            { %$($k).+ = $($field)*}
283        )
284    );
285    ($($k:ident).+, $($field:tt)*) => (
286        $crate::event!(
287            target: module_path!(),
288            $crate::event::Level::WARN,
289            { $($k).+, $($field)*}
290        )
291    );
292    (?$($k:ident).+, $($field:tt)*) => (
293        $crate::event!(
294            target: module_path!(),
295            $crate::event::Level::WARN,
296            { ?$($k).+, $($field)*}
297        )
298    );
299    (%$($k:ident).+, $($field:tt)*) => (
300        $crate::event!(
301            target: module_path!(),
302            $crate::event::Level::WARN,
303            { %$($k).+, $($field)*}
304        )
305    );
306    (?$($k:ident).+) => (
307        $crate::event!(
308            target: module_path!(),
309            $crate::event::Level::WARN,
310            { ?$($k).+ }
311        )
312    );
313    (%$($k:ident).+) => (
314        $crate::event!(
315            target: module_path!(),
316            $crate::event::Level::WARN,
317            { %$($k).+ }
318        )
319    );
320    ($($k:ident).+) => (
321        $crate::event!(
322            target: module_path!(),
323            $crate::event::Level::WARN,
324            { $($k).+ }
325        )
326    );
327    ($($arg:tt)+) => (
328        $crate::event!(
329            target: module_path!(),
330            $crate::event::Level::WARN,
331            {},
332            $($arg)+
333        )
334    );
335}
336
337/// Emit an info event.
338#[macro_export]
339macro_rules! info {
340    (target: $target:expr, { $($field:tt)* }, $($arg:tt)* ) => (
341        $crate::event!(target: $target, $crate::event::Level::INFO, { $($field)* }, $($arg)*)
342    );
343    (target: $target:expr, $($k:ident).+ $($field:tt)* ) => (
344        $crate::event!(target: $target, $crate::event::Level::INFO, { $($k).+ $($field)* })
345    );
346    (target: $target:expr, ?$($k:ident).+ $($field:tt)* ) => (
347        $crate::event!(target: $target, $crate::event::Level::INFO, { ?$($k).+ $($field)* })
348    );
349    (target: $target:expr, %$($k:ident).+ $($field:tt)* ) => (
350        $crate::event!(target: $target, $crate::event::Level::INFO, { %$($k).+ $($field)* })
351    );
352    (target: $target:expr, $($arg:tt)+ ) => (
353        $crate::event!(target: $target, $crate::event::Level::INFO, {}, $($arg)+)
354    );
355    ({ $($field:tt)+ }, $($arg:tt)+ ) => (
356        $crate::event!(
357            target: module_path!(),
358            $crate::event::Level::INFO,
359            { $($field)+ },
360            $($arg)+
361        )
362    );
363    ($($k:ident).+ = $($field:tt)*) => (
364        $crate::event!(
365            target: module_path!(),
366            $crate::event::Level::INFO,
367            { $($k).+ = $($field)*}
368        )
369    );
370    (?$($k:ident).+ = $($field:tt)*) => (
371        $crate::event!(
372            target: module_path!(),
373            $crate::event::Level::INFO,
374            { ?$($k).+ = $($field)*}
375        )
376    );
377    (%$($k:ident).+ = $($field:tt)*) => (
378        $crate::event!(
379            target: module_path!(),
380            $crate::event::Level::INFO,
381            { %$($k).+ = $($field)*}
382        )
383    );
384    ($($k:ident).+, $($field:tt)*) => (
385        $crate::event!(
386            target: module_path!(),
387            $crate::event::Level::INFO,
388            { $($k).+, $($field)*}
389        )
390    );
391    (?$($k:ident).+, $($field:tt)*) => (
392        $crate::event!(
393            target: module_path!(),
394            $crate::event::Level::INFO,
395            { ?$($k).+, $($field)*}
396        )
397    );
398    (%$($k:ident).+, $($field:tt)*) => (
399        $crate::event!(
400            target: module_path!(),
401            $crate::event::Level::INFO,
402            { %$($k).+, $($field)*}
403        )
404    );
405    (?$($k:ident).+) => (
406        $crate::event!(
407            target: module_path!(),
408            $crate::event::Level::INFO,
409            { ?$($k).+ }
410        )
411    );
412    (%$($k:ident).+) => (
413        $crate::event!(
414            target: module_path!(),
415            $crate::event::Level::INFO,
416            { %$($k).+ }
417        )
418    );
419    ($($k:ident).+) => (
420        $crate::event!(
421            target: module_path!(),
422            $crate::event::Level::INFO,
423            { $($k).+ }
424        )
425    );
426    ($($arg:tt)+) => (
427        $crate::event!(
428            target: module_path!(),
429            $crate::event::Level::INFO,
430            {},
431            $($arg)+
432        )
433    );
434}
435
436/// Emit a debug event.
437#[macro_export]
438macro_rules! debug {
439    (target: $target:expr, { $($field:tt)* }, $($arg:tt)* ) => (
440        $crate::event!(target: $target, $crate::event::Level::DEBUG, { $($field)* }, $($arg)*)
441    );
442    (target: $target:expr, $($k:ident).+ $($field:tt)* ) => (
443        $crate::event!(target: $target, $crate::event::Level::DEBUG, { $($k).+ $($field)* })
444    );
445    (target: $target:expr, ?$($k:ident).+ $($field:tt)* ) => (
446        $crate::event!(target: $target, $crate::event::Level::DEBUG, { ?$($k).+ $($field)* })
447    );
448    (target: $target:expr, %$($k:ident).+ $($field:tt)* ) => (
449        $crate::event!(target: $target, $crate::event::Level::DEBUG, { %$($k).+ $($field)* })
450    );
451    (target: $target:expr, $($arg:tt)+ ) => (
452        $crate::event!(target: $target, $crate::event::Level::DEBUG, {}, $($arg)+)
453    );
454    ({ $($field:tt)+ }, $($arg:tt)+ ) => (
455        $crate::event!(
456            target: module_path!(),
457            $crate::event::Level::DEBUG,
458            { $($field)+ },
459            $($arg)+
460        )
461    );
462    ($($k:ident).+ = $($field:tt)*) => (
463        $crate::event!(
464            target: module_path!(),
465            $crate::event::Level::DEBUG,
466            { $($k).+ = $($field)*}
467        )
468    );
469    (?$($k:ident).+ = $($field:tt)*) => (
470        $crate::event!(
471            target: module_path!(),
472            $crate::event::Level::DEBUG,
473            { ?$($k).+ = $($field)*}
474        )
475    );
476    (%$($k:ident).+ = $($field:tt)*) => (
477        $crate::event!(
478            target: module_path!(),
479            $crate::event::Level::DEBUG,
480            { %$($k).+ = $($field)*}
481        )
482    );
483    ($($k:ident).+, $($field:tt)*) => (
484        $crate::event!(
485            target: module_path!(),
486            $crate::event::Level::DEBUG,
487            { $($k).+, $($field)*}
488        )
489    );
490    (?$($k:ident).+, $($field:tt)*) => (
491        $crate::event!(
492            target: module_path!(),
493            $crate::event::Level::DEBUG,
494            { ?$($k).+, $($field)*}
495        )
496    );
497    (%$($k:ident).+, $($field:tt)*) => (
498        $crate::event!(
499            target: module_path!(),
500            $crate::event::Level::DEBUG,
501            { %$($k).+, $($field)*}
502        )
503    );
504    (?$($k:ident).+) => (
505        $crate::event!(
506            target: module_path!(),
507            $crate::event::Level::DEBUG,
508            { ?$($k).+ }
509        )
510    );
511    (%$($k:ident).+) => (
512        $crate::event!(
513            target: module_path!(),
514            $crate::event::Level::DEBUG,
515            { %$($k).+ }
516        )
517    );
518    ($($k:ident).+) => (
519        $crate::event!(
520            target: module_path!(),
521            $crate::event::Level::DEBUG,
522            { $($k).+ }
523        )
524    );
525    ($($arg:tt)+) => (
526        $crate::event!(
527            target: module_path!(),
528            $crate::event::Level::DEBUG,
529            {},
530            $($arg)+
531        )
532    );
533}
534
535/// Emit a trace event.
536#[macro_export]
537macro_rules! trace {
538    (target: $target:expr, { $($field:tt)* }, $($arg:tt)* ) => (
539        $crate::event!(target: $target, $crate::event::Level::TRACE, { $($field)* }, $($arg)*)
540    );
541    (target: $target:expr, $($k:ident).+ $($field:tt)* ) => (
542        $crate::event!(target: $target, $crate::event::Level::TRACE, { $($k).+ $($field)* })
543    );
544    (target: $target:expr, ?$($k:ident).+ $($field:tt)* ) => (
545        $crate::event!(target: $target, $crate::event::Level::TRACE, { ?$($k).+ $($field)* })
546    );
547    (target: $target:expr, %$($k:ident).+ $($field:tt)* ) => (
548        $crate::event!(target: $target, $crate::event::Level::TRACE, { %$($k).+ $($field)* })
549    );
550    (target: $target:expr, $($arg:tt)+ ) => (
551        $crate::event!(target: $target, $crate::event::Level::TRACE, {}, $($arg)+)
552    );
553    ({ $($field:tt)+ }, $($arg:tt)+ ) => (
554        $crate::event!(
555            target: module_path!(),
556            $crate::event::Level::TRACE,
557            { $($field)+ },
558            $($arg)+
559        )
560    );
561    ($($k:ident).+ = $($field:tt)*) => (
562        $crate::event!(
563            target: module_path!(),
564            $crate::event::Level::TRACE,
565            { $($k).+ = $($field)*}
566        )
567    );
568    (?$($k:ident).+ = $($field:tt)*) => (
569        $crate::event!(
570            target: module_path!(),
571            $crate::event::Level::TRACE,
572            { ?$($k).+ = $($field)*}
573        )
574    );
575    (%$($k:ident).+ = $($field:tt)*) => (
576        $crate::event!(
577            target: module_path!(),
578            $crate::event::Level::TRACE,
579            { %$($k).+ = $($field)*}
580        )
581    );
582    ($($k:ident).+, $($field:tt)*) => (
583        $crate::event!(
584            target: module_path!(),
585            $crate::event::Level::TRACE,
586            { $($k).+, $($field)*}
587        )
588    );
589    (?$($k:ident).+, $($field:tt)*) => (
590        $crate::event!(
591            target: module_path!(),
592            $crate::event::Level::TRACE,
593            { ?$($k).+, $($field)*}
594        )
595    );
596    (%$($k:ident).+, $($field:tt)*) => (
597        $crate::event!(
598            target: module_path!(),
599            $crate::event::Level::TRACE,
600            { %$($k).+, $($field)*}
601        )
602    );
603    (?$($k:ident).+) => (
604        $crate::event!(
605            target: module_path!(),
606            $crate::event::Level::TRACE,
607            { ?$($k).+ }
608        )
609    );
610    (%$($k:ident).+) => (
611        $crate::event!(
612            target: module_path!(),
613            $crate::event::Level::TRACE,
614            { %$($k).+ }
615        )
616    );
617    ($($k:ident).+) => (
618        $crate::event!(
619            target: module_path!(),
620            $crate::event::Level::TRACE,
621            { $($k).+ }
622        )
623    );
624    ($($arg:tt)+) => (
625        $crate::event!(
626            target: module_path!(),
627            $crate::event::Level::TRACE,
628            {},
629            $($arg)+
630        )
631    );
632}
gix_trace/lib.rs

gix_trace/
lib.rs
