tracing/
macros.rs

1/// Constructs a new span.
2///
3/// See [the top-level documentation][lib] for details on the syntax accepted by
4/// this macro.
5///
6/// [lib]: crate#using-the-macros
7///
8/// # Examples
9///
10/// Creating a new span:
11/// ```
12/// # use tracing::{span, Level};
13/// # fn main() {
14/// let span = span!(Level::TRACE, "my span");
15/// let _enter = span.enter();
16/// // do work inside the span...
17/// # }
18/// ```
19#[macro_export]
20macro_rules! span {
21    (target: $target:expr, parent: $parent:expr, $lvl:expr, $name:expr) => {
22        $crate::span!(target: $target, parent: $parent, $lvl, $name,)
23    };
24    (target: $target:expr, parent: $parent:expr, $lvl:expr, $name:expr, $($fields:tt)*) => {
25        {
26            use $crate::__macro_support::Callsite as _;
27            static __CALLSITE: $crate::__macro_support::MacroCallsite = $crate::callsite2! {
28                name: $name,
29                kind: $crate::metadata::Kind::SPAN,
30                target: $target,
31                level: $lvl,
32                fields: $($fields)*
33            };
34            let mut interest = $crate::collect::Interest::never();
35            if $crate::level_enabled!($lvl)
36                && { interest = __CALLSITE.interest(); !interest.is_never() }
37                && __CALLSITE.is_enabled(interest)
38            {
39                let meta = __CALLSITE.metadata();
40                // span with explicit parent
41                $crate::Span::child_of(
42                    $parent,
43                    meta,
44                    &$crate::valueset!(meta.fields(), $($fields)*),
45                )
46            } else {
47                let span = __CALLSITE.disabled_span();
48                $crate::if_log_enabled! { $lvl, {
49                    span.record_all(&$crate::valueset!(__CALLSITE.metadata().fields(), $($fields)*));
50                }};
51                span
52            }
53        }
54    };
55    (target: $target:expr, $lvl:expr, $name:expr, $($fields:tt)*) => {
56        {
57            use $crate::__macro_support::{Callsite as _, Registration};
58            static __CALLSITE: $crate::__macro_support::MacroCallsite = $crate::callsite2! {
59                name: $name,
60                kind: $crate::metadata::Kind::SPAN,
61                target: $target,
62                level: $lvl,
63                fields: $($fields)*
64            };
65
66            let mut interest = $crate::collect::Interest::never();
67            if $crate::level_enabled!($lvl)
68                && { interest = __CALLSITE.interest(); !interest.is_never() }
69                && __CALLSITE.is_enabled(interest)
70            {
71                let meta = __CALLSITE.metadata();
72                // span with contextual parent
73                $crate::Span::new(
74                    meta,
75                    &$crate::valueset!(meta.fields(), $($fields)*),
76                )
77            } else {
78                let span = __CALLSITE.disabled_span();
79                $crate::if_log_enabled! { $lvl, {
80                    span.record_all(&$crate::valueset!(__CALLSITE.metadata().fields(), $($fields)*));
81                }};
82                span
83            }
84        }
85    };
86    (target: $target:expr, parent: $parent:expr, $lvl:expr, $name:expr) => {
87        $crate::span!(target: $target, parent: $parent, $lvl, $name,)
88    };
89    (parent: $parent:expr, $lvl:expr, $name:expr, $($fields:tt)*) => {
90        $crate::span!(
91            target: module_path!(),
92            parent: $parent,
93            $lvl,
94            $name,
95            $($fields)*
96        )
97    };
98    (parent: $parent:expr, $lvl:expr, $name:expr) => {
99        $crate::span!(
100            target: module_path!(),
101            parent: $parent,
102            $lvl,
103            $name,
104        )
105    };
106    (target: $target:expr, $lvl:expr, $name:expr, $($fields:tt)*) => {
107        $crate::span!(
108            target: $target,
109            $lvl,
110            $name,
111            $($fields)*
112        )
113    };
114    (target: $target:expr, $lvl:expr, $name:expr) => {
115        $crate::span!(target: $target, $lvl, $name,)
116    };
117    ($lvl:expr, $name:expr, $($fields:tt)*) => {
118        $crate::span!(
119            target: module_path!(),
120            $lvl,
121            $name,
122            $($fields)*
123        )
124    };
125    ($lvl:expr, $name:expr) => {
126        $crate::span!(
127            target: module_path!(),
128            $lvl,
129            $name,
130        )
131    };
132}
133
134/// Records multiple values on a span in a single call. As with recording
135/// individual values, all fields must be declared when the span is created.
136///
137/// This macro supports two optional sigils:
138/// - `%` uses the Display implementation.
139/// - `?` uses the Debug implementation.
140///
141/// For more details, see the [top-level documentation][lib].
142///
143/// [lib]: tracing/#recording-fields
144///
145/// # Examples
146///
147/// ```
148/// # use tracing::{field, info_span, record_all};
149/// let span = info_span!("my span", field1 = field::Empty, field2 = field::Empty, field3 = field::Empty).entered();
150/// record_all!(span, field1 = ?"1", field2 = %"2", field3 = 3);
151/// ```
152#[macro_export]
153macro_rules! record_all {
154    ($span:expr, $($fields:tt)*) => {
155        if let Some(meta) = $span.metadata() {
156            $span.record_all(&$crate::valueset!(
157                meta.fields(),
158                $($fields)*
159            ));
160        }
161    };
162}
163
164/// Constructs a span at the trace level.
165///
166/// [Fields] and [attributes] are set using the same syntax as the [`span!`]
167/// macro.
168///
169/// See [the top-level documentation][lib] for details on the syntax accepted by
170/// this macro.
171///
172/// [lib]: crate#using-the-macros
173/// [attributes]: crate#configuring-attributes
174/// [Fields]: crate#recording-fields
175/// [`span!`]: span!
176///
177/// # Examples
178///
179/// ```rust
180/// # use tracing::{trace_span, span, Level};
181/// # fn main() {
182/// trace_span!("my_span");
183/// // is equivalent to:
184/// span!(Level::TRACE, "my_span");
185/// # }
186/// ```
187///
188/// ```rust
189/// # use tracing::{trace_span, span, Level};
190/// # fn main() {
191/// let span = trace_span!("my span");
192/// span.in_scope(|| {
193///     // do work inside the span...
194/// });
195/// # }
196/// ```
197#[macro_export]
198macro_rules! trace_span {
199    (target: $target:expr, parent: $parent:expr, $name:expr, $($field:tt)*) => {
200        $crate::span!(
201            target: $target,
202            parent: $parent,
203            $crate::Level::TRACE,
204            $name,
205            $($field)*
206        )
207    };
208    (target: $target:expr, parent: $parent:expr, $name:expr) => {
209        $crate::trace_span!(target: $target, parent: $parent, $name,)
210    };
211    (parent: $parent:expr, $name:expr, $($field:tt)*) => {
212        $crate::span!(
213            target: module_path!(),
214            parent: $parent,
215            $crate::Level::TRACE,
216            $name,
217            $($field)*
218        )
219    };
220    (parent: $parent:expr, $name:expr) => {
221        $crate::trace_span!(parent: $parent, $name,)
222    };
223    (target:
tracing/macros.rs

tracing/
macros.rs
