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

gix_trace/
lib.rs
