span.rs source code [crates/tracing/src/span.rs]

1	//! Spans represent periods of time in which a program was executing in a
2	//! particular context.
3	//!
4	//! A span consists of [fields], user-defined key-value pairs of arbitrary data
5	//! that describe the context the span represents, and a set of fixed attributes
6	//! that describe all `tracing` spans and events. Attributes describing spans
7	//! include:
8	//!
9	//! - An [`Id`] assigned by the subscriber that uniquely identifies it in relation
10	//! to other spans.
11	//! - The span's [parent] in the trace tree.
12	//! - [Metadata] that describes static characteristics of all spans
13	//! originating from that callsite, such as its name, source code location,
14	//! [verbosity level], and the names of its fields.
15	//!
16	//! # Creating Spans
17	//!
18	//! Spans are created using the [`span!`] macro. This macro is invoked with the
19	//! following arguments, in order:
20	//!
21	//! - The [`target`] and/or [`parent`][parent] attributes, if the user wishes to
22	//! override their default values.
23	//! - The span's [verbosity level]
24	//! - A string literal providing the span's name.
25	//! - Finally, between zero and 32 arbitrary key/value fields.
26	//!
27	//! [`target`]: super::Metadata::target
28	//!
29	//! For example:
30	//! ```rust
31	//! use tracing::{span, Level};
32	//!
33	//! /// Construct a new span at the `INFO` level named "my_span", with a single
34	//! /// field named answer , with the value `42`.
35	//! let my_span = span!(Level::INFO, "my_span", answer = `42`);
36	//! ```
37	//!
38	//! The documentation for the [`span!`] macro provides additional examples of
39	//! the various options that exist when creating spans.
40	//!
41	//! The [`trace_span!`], [`debug_span!`], [`info_span!`], [`warn_span!`], and
42	//! [`error_span!`] exist as shorthand for constructing spans at various
43	//! verbosity levels.
44	//!
45	//! ## Recording Span Creation
46	//!
47	//! The [`Attributes`] type contains data associated with a span, and is
48	//! provided to the [`Subscriber`] when a new span is created. It contains
49	//! the span's metadata, the ID of [the span's parent][parent] if one was
50	//! explicitly set, and any fields whose values were recorded when the span was
51	//! constructed. The subscriber, which is responsible for recording `tracing`
52	//! data, can then store or record these values.
53	//!
54	//! # The Span Lifecycle
55	//!
56	//! ## Entering a Span
57	//!
58	//! A thread of execution is said to _enter_ a span when it begins executing,
59	//! and _exit_ the span when it switches to another context. Spans may be
60	//! entered through the [`enter`], [`entered`], and [`in_scope`] methods.
61	//!
62	//! The [`enter`] method enters a span, returning a [guard] that exits the span
63	//! when dropped
64	//! ```
65	//! # use tracing::{span, Level};
66	//! let my_var: u64 = `5`;
67	//! let my_span = span!(Level::TRACE, "my_span", my_var);
68	//!
69	//! // `my_span` exists but has not been entered.
70	//!
71	//! // Enter `my_span`...
72	//! let _enter = my_span.enter();
73	//!
74	//! // Perform some work inside of the context of `my_span`...
75	//! // Dropping the `_enter` guard will exit the span.
76	//!```
77	//!
78	//! <div class="example-wrap" style="display:inline-block"><pre class="compile_fail" style="white-space:normal;font:inherit;">
79	//! <strong>Warning</strong>: In asynchronous code that uses async/await syntax,
80	//! <code>Span::enter</code> may produce incorrect traces if the returned drop
81	//! guard is held across an await point. See
82	//! <a href="struct.Span.html#in-asynchronous-code">the method documentation</a>
83	//! for details.
84	//! </pre></div>
85	//!
86	//! The [`entered`] method is analogous to [`enter`], but moves the span into
87	//! the returned guard, rather than borrowing it. This allows creating and
88	//! entering a span in a single expression:
89	//!
90	//! ```
91	//! # use tracing::{span, Level};
92	//! // Create a span and enter it, returning a guard:
93	//! let span = span!(Level::INFO, "my_span").entered();
94	//!
95	//! // We are now inside the span! Like `enter()`, the guard returned by
96	//! // `entered()` will exit the span when it is dropped...
97	//!
98	//! // ...but, it can also be exited explicitly, returning the `Span`
99	//! // struct:
100	//! let span = span.exit();
101	//! ```
102	//!
103	//! Finally, [`in_scope`] takes a closure or function pointer and executes it
104	//! inside the span:
105	//!
106	//! ```
107	//! # use tracing::{span, Level};
108	//! let my_var: u64 = `5`;
109	//! let my_span = span!(Level::TRACE, "my_span", my_var = &my_var);
110	//!
111	//! my_span.in_scope(\|\| {
112	//! // perform some work in the context of `my_span`...
113	//! });
114	//!
115	//! // Perform some work outside of the context of `my_span`...
116	//!
117	//! my_span.in_scope(\|\| {
118	//! // Perform some more work in the context of `my_span`.
119	//! });
120	//! ```
121	//!
122	//! <pre class="ignore" style="white-space:normal;font:inherit;">
123	//! <strong>Note</strong>: Since entering a span takes <code>&self</code>, and
124	//! <code>Span</code>s are <code>Clone</code>, <code>Send</code>, and
125	//! <code>Sync</code>, it is entirely valid for multiple threads to enter the
126	//! same span concurrently.
127	//! </pre>
128	//!
129	//! ## Span Relationships
130	//!
131	//! Spans form a tree structure — unless it is a root span, all spans have a
132	//! _parent_, and may have one or more _children_. When a new span is created,
133	//! the current span becomes the new span's parent. The total execution time of
134	//! a span consists of the time spent in that span and in the entire subtree
135	//! represented by its children. Thus, a parent span always lasts for at least
136	//! as long as the longest-executing span in its subtree.
137	//!
138	//! ```
139	//! # use tracing::{Level, span};
140	//! // this span is considered the "root" of a new trace tree:
141	//! span!(Level::INFO, "root").in_scope(\|\| {
142	//! // since we are now inside "root", this span is considered a child
143	//! // of "root":
144	//! span!(Level::DEBUG, "outer_child").in_scope(\|\| {
145	//! // this span is a child of "outer_child", which is in turn a
146	//! // child of "root":
147	//! span!(Level::TRACE, "inner_child").in_scope(\|\| {
148	//! // and so on...
149	//! });
150	//! });
151	//! // another span created here would also be a child of "root".
152	//! });
153	//!```
154	//!
155	//! In addition, the parent of a span may be explicitly specified in
156	//! the `span!` macro. For example:
157	//!
158	//! ```rust
159	//! # use tracing::{Level, span};
160	//! // Create, but do not enter, a span called "foo".
161	//! let foo = span!(Level::INFO, "foo");
162	//!
163	//! // Create and enter a span called "bar".
164	//! let bar = span!(Level::INFO, "bar");
165	//! let _enter = bar.enter();
166	//!
167	//! // Although we have currently entered "bar", "baz"'s parent span
168	//! // will be "foo".
169	//! let baz = span!(parent: &foo, Level::INFO, "baz");
170	//! ```
171	//!
172	//! A child span should typically be considered _part_ of its parent. For
173	//! example, if a subscriber is recording the length of time spent in various
174	//! spans, it should generally include the time spent in a span's children as
175	//! part of that span's duration.
176	//!
177	//! In addition to having zero or one parent, a span may also _follow from_ any
178	//! number of other spans. This indicates a causal relationship between the span
179	//! and the spans that it follows from, but a follower is not* typically*
180	//! considered part of the duration of the span it follows. Unlike the parent, a
181	//! span may record that it follows from another span after it is created, using
182	//! the [`follows_from`] method.
183	//!
184	//! As an example, consider a listener task in a server. As the listener accepts
185	//! incoming connections, it spawns new tasks that handle those connections. We
186	//! might want to have a span representing the listener, and instrument each
187	//! spawned handler task with its own span. We would want our instrumentation to
188	//! record that the handler tasks were spawned as a result of the listener task.
189	//! However, we might not consider the handler tasks to be _part_ of the time
190	//! spent in the listener task, so we would not consider those spans children of
191	//! the listener span. Instead, we would record that the handler tasks follow
192	//! from the listener, recording the causal relationship but treating the spans
193	//! as separate durations.
194	//!
195	//! ## Closing Spans
196	//!
197	//! Execution may enter and exit a span multiple times before that span is
198	//! _closed_. Consider, for example, a future which has an associated
199	//! span and enters that span every time it is polled:
200	//! ```rust
201	//! # use std::future::Future;
202	//! # use std::task::{Context, Poll};
203	//! # use std::pin::Pin;
204	//! struct MyFuture {
205	//! // data
206	//! span: tracing::Span,
207	//! }
208	//!
209	//! impl Future for MyFuture {
210	//! type Output = ();
211	//!
212	//! fn poll(self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<Self::Output> {
213	//! let _enter = self.span.enter();
214	//! // Do actual future work...
215	//! # Poll::Ready(())
216	//! }
217	//! }
218	//! ```
219	//!
220	//! If this future was spawned on an executor, it might yield one or more times
221	//! before `poll` returns [`Poll::Ready`]. If the future were to yield, then
222	//! the executor would move on to poll the next future, which may _also_ enter
223	//! an associated span or series of spans. Therefore, it is valid for a span to
224	//! be entered repeatedly before it completes. Only the time when that span or
225	//! one of its children was the current span is considered to be time spent in
226	//! that span. A span which is not executing and has not yet been closed is said
227	//! to be _idle_.
228	//!
229	//! Because spans may be entered and exited multiple times before they close,
230	//! [`Subscriber`]s have separate trait methods which are called to notify them
231	//! of span exits and when span handles are dropped. When execution exits a
232	//! span, [`exit`] will always be called with that span's ID to notify the
233	//! subscriber that the span has been exited. When span handles are dropped, the
234	//! [`drop_span`] method is called with that span's ID. The subscriber may use
235	//! this to determine whether or not the span will be entered again.
236	//!
237	//! If there is only a single handle with the capacity to exit a span, dropping
238	//! that handle "closes" the span, since the capacity to enter it no longer
239	//! exists. For example:
240	//! ```
241	//! # use tracing::{Level, span};
242	//! {
243	//! span!(Level::TRACE, "my_span").in_scope(\|\| {
244	//! // perform some work in the context of `my_span`...
245	//! }); // --> Subscriber::exit(my_span)
246	//!
247	//! // The handle to `my_span` only lives inside of this block; when it is
248	//! // dropped, the subscriber will be informed via `drop_span`.
249	//!
250	//! } // --> Subscriber::drop_span(my_span)
251	//! ```
252	//!
253	//! However, if multiple handles exist, the span can still be re-entered even if
254	//! one or more is dropped. For determining when _all_ handles to a span have
255	//! been dropped, `Subscriber`s have a [`clone_span`] method, which is called
256	//! every time a span handle is cloned. Combined with `drop_span`, this may be
257	//! used to track the number of handles to a given span — if `drop_span` has
258	//! been called one more time than the number of calls to `clone_span` for a
259	//! given ID, then no more handles to the span with that ID exist. The
260	//! subscriber may then treat it as closed.
261	//!
262	//! # When to use spans
263	//!
264	//! As a rule of thumb, spans should be used to represent discrete units of work
265	//! (e.g., a given request's lifetime in a server) or periods of time spent in a
266	//! given context (e.g., time spent interacting with an instance of an external
267	//! system, such as a database).
268	//!
269	//! Which scopes in a program correspond to new spans depend somewhat on user
270	//! intent. For example, consider the case of a loop in a program. Should we
271	//! construct one span and perform the entire loop inside of that span, like:
272	//!
273	//! ```rust
274	//! # use tracing::{Level, span};
275	//! # let n = `1`;
276	//! let span = span!(Level::TRACE, "my_loop");
277	//! let _enter = span.enter();
278	//! for i in `0`..n {
279	//! # let _ = i;
280	//! // ...
281	//! }
282	//! ```
283	//! Or, should we create a new span for each iteration of the loop, as in:
284	//! ```rust
285	//! # use tracing::{Level, span};
286	//! # let n = `1u64`;
287	//! for i in `0`..n {
288	//! let span = span!(Level::TRACE, "my_loop", iteration = i);
289	//! let _enter = span.enter();
290	//! // ...
291	//! }
292	//! ```
293	//!
294	//! Depending on the circumstances, we might want to do either, or both. For
295	//! example, if we want to know how long was spent in the loop overall, we would
296	//! create a single span around the entire loop; whereas if we wanted to know how
297	//! much time was spent in each individual iteration, we would enter a new span
298	//! on every iteration.
299	//!
300	//! [fields]: super::field
301	//! [Metadata]: super::Metadata
302	//! [verbosity level]: super::Level
303	//! [`Poll::Ready`]: std::task::Poll::Ready
304	//! [`span!`]: super::span!
305	//! [`trace_span!`]: super::trace_span!
306	//! [`debug_span!`]: super::debug_span!
307	//! [`info_span!`]: super::info_span!
308	//! [`warn_span!`]: super::warn_span!
309	//! [`error_span!`]: super::error_span!
310	//! [`clone_span`]: super::subscriber::Subscriber::clone_span()
311	//! [`drop_span`]: super::subscriber::Subscriber::drop_span()
312	//! [`exit`]: super::subscriber::Subscriber::exit
313	//! [`Subscriber`]: super::subscriber::Subscriber
314	//! [`enter`]: Span::enter()
315	//! [`entered`]: Span::entered()
316	//! [`in_scope`]: Span::in_scope()
317	//! [`follows_from`]: Span::follows_from()
318	//! [guard]: Entered
319	//! [parent]: #span-relationships
320	pub use tracing_core::span::{Attributes, Id, Record};
321
322	use crate::stdlib::{
323	cmp, fmt,
324	hash::{Hash, Hasher},
325	marker::PhantomData,
326	mem,
327	ops::Deref,
328	};
329	use crate::{
330	dispatcher::{self, Dispatch},
331	field, Metadata,
332	};
333
334	/// Trait implemented by types which have a span `Id`.
335	pub trait AsId: crate::sealed::Sealed {
336	/// Returns the `Id` of the span that `self` corresponds to, or `None` if
337	/// this corresponds to a disabled span.
338	fn as_id(&self) -> Option<&Id>;
339	}
340
341	/// A handle representing a span, with the capability to enter the span if it
342	/// exists.
343	///
344	/// If the span was rejected by the current `Subscriber`'s filter, entering the
345	/// span will silently do nothing. Thus, the handle can be used in the same
346	/// manner regardless of whether or not the trace is currently being collected.
347	#[derive(Clone)]
348	pub struct Span {
349	/// A handle used to enter the span when it is not executing.
350	///
351	/// If this is `None`, then the span has either closed or was never enabled.
352	inner: Option<Inner>,
353	/// Metadata describing the span.
354	///
355	/// This might be `Some` even if `inner` is `None`, in the case that the
356	/// span is disabled but the metadata is needed for `log` support.
357	meta: Option<&'static Metadata<'static>>,
358	}
359
360	/// A handle representing the capacity to enter a span which is known to exist.
361	///
362	/// Unlike `Span`, this type is only constructed for spans which _have_ been
363	/// enabled by the current filter. This type is primarily used for implementing
364	/// span handles; users should typically not need to interact with it directly.
365	#[derive(Debug)]
366	pub(crate) struct Inner {
367	/// The span's ID, as provided by `subscriber`.
368	id: Id,
369
370	/// The subscriber that will receive events relating to this span.
371	///
372	/// This should be the same subscriber that provided this span with its
373	/// `id`.
374	subscriber: Dispatch,
375	}
376
377	/// A guard representing a span which has been entered and is currently
378	/// executing.
379	///
380	/// When the guard is dropped, the span will be exited.
381	///
382	/// This is returned by the [`Span::enter`] function.
383	///
384	/// [`Span::enter`]: super::Span::enter
385	#[derive(Debug)]
386	#[must_use = "once a span has been entered, it should be exited"]
387	pub struct Entered<'a> {
388	span: &'a Span,
389	}
390
391	/// An owned version of [`Entered`], a guard representing a span which has been
392	/// entered and is currently executing.
393	///
394	/// When the guard is dropped, the span will be exited.
395	///
396	/// This is returned by the [`Span::entered`] function.
397	///
398	/// [`Span::entered`]: super::Span::entered()
399	#[derive(Debug)]
400	#[must_use = "once a span has been entered, it should be exited"]
401	pub struct EnteredSpan {
402	span: Span,
403
404	/// ```compile_fail
405	/// use tracing::span::*;
406	/// trait AssertSend: Send {}
407	///
408	/// impl AssertSend for EnteredSpan {}
409	/// ```
410	_not_send: PhantomNotSend,
411	}
412
413	/// `log` target for all span lifecycle (creation/enter/exit/close) records.
414	#[cfg(feature = "log")]
415	const LIFECYCLE_LOG_TARGET: &str = "tracing::span";
416	/// `log` target for span activity (enter/exit) records.
417	#[cfg(feature = "log")]
418	const ACTIVITY_LOG_TARGET: &str = "tracing::span::active";
419
420	// ===== impl Span =====
421
422	impl Span {
423	/// Constructs a new `Span` with the given [metadata] and set of
424	/// [field values].
425	///
426	/// The new span will be constructed by the currently-active [`Subscriber`],
427	/// with the current span as its parent (if one exists).
428	///
429	/// After the span is constructed, [field values] and/or [`follows_from`]
430	/// annotations may be added to it.
431	///
432	/// [metadata]: super::Metadata
433	/// [`Subscriber`]: super::subscriber::Subscriber
434	/// [field values]: super::field::ValueSet
435	/// [`follows_from`]: super::Span::follows_from
436	pub fn new(meta: &'static Metadata<'static>, values: &field::ValueSet<'_>) -> Span {
437	dispatcher::get_default(\|dispatch\| Self::new_with(meta, values, dispatch))
438	}
439
440	#[inline]
441	#[doc(hidden)]
442	pub fn new_with(
443	meta: &'static Metadata<'static>,
444	values: &field::ValueSet<'_>,
445	dispatch: &Dispatch,
446	) -> Span {
447	let new_span = Attributes::new(meta, values);
448	Self::make_with(meta, new_span, dispatch)
449	}
450
451	/// Constructs a new `Span` as the root of its own trace tree, with the
452	/// given [metadata] and set of [field values].
453	///
454	/// After the span is constructed, [field values] and/or [`follows_from`]
455	/// annotations may be added to it.
456	///
457	/// [metadata]: super::Metadata
458	/// [field values]: super::field::ValueSet
459	/// [`follows_from`]: super::Span::follows_from
460	pub fn new_root(meta: &'static Metadata<'static>, values: &field::ValueSet<'_>) -> Span {
461	dispatcher::get_default(\|dispatch\| Self::new_root_with(meta, values, dispatch))
462	}
463
464	#[inline]
465	#[doc(hidden)]
466	pub fn new_root_with(
467	meta: &'static Metadata<'static>,
468	values: &field::ValueSet<'_>,
469	dispatch: &Dispatch,
470	) -> Span {
471	let new_span = Attributes::new_root(meta, values);
472	Self::make_with(meta, new_span, dispatch)
473	}
474
475	/// Constructs a new `Span` as child of the given parent span, with the
476	/// given [metadata] and set of [field values].
477	///
478	/// After the span is constructed, [field values] and/or [`follows_from`]
479	/// annotations may be added to it.
480	///
481	/// [metadata]: super::Metadata
482	/// [field values]: super::field::ValueSet
483	/// [`follows_from`]: super::Span::follows_from
484	pub fn child_of(
485	parent: impl Into<Option<Id>>,
486	meta: &'static Metadata<'static>,
487	values: &field::ValueSet<'_>,
488	) -> Span {
489	let mut parent = parent.into();
490	dispatcher::get_default(move \|dispatch\| {
491	Self::child_of_with(Option::take(&mut parent), meta, values, dispatch)
492	})
493	}
494
495	#[inline]
496	#[doc(hidden)]
497	pub fn child_of_with(
498	parent: impl Into<Option<Id>>,
499	meta: &'static Metadata<'static>,
500	values: &field::ValueSet<'_>,
501	dispatch: &Dispatch,
502	) -> Span {
503	let new_span = match parent.into() {
504	Some(parent) => Attributes::child_of(parent, meta, values),
505	None => Attributes::new_root(meta, values),
506	};
507	Self::make_with(meta, new_span, dispatch)
508	}
509
510	/// Constructs a new disabled span with the given `Metadata`.
511	///
512	/// This should be used when a span is constructed from a known callsite,
513	/// but the subscriber indicates that it is disabled.
514	///
515	/// Entering, exiting, and recording values on this span will not notify the
516	/// `Subscriber` but _may_ record log messages if the `log` feature flag is
517	/// enabled.
518	#[inline(always)]
519	pub fn new_disabled(meta: &'static Metadata<'static>) -> Span {
520	Self {
521	inner: None,
522	meta: Some(meta),
523	}
524	}
525
526	/// Constructs a new span that is completely disabled.
527	///
528	/// This can be used rather than `Option<Span>` to represent cases where a
529	/// span is not present.
530	///
531	/// Entering, exiting, and recording values on this span will do nothing.
532	#[inline(always)]
533	pub const fn none() -> Span {
534	Self {
535	inner: None,
536	meta: None,
537	}
538	}
539
540	/// Returns a handle to the span [considered by the `Subscriber`] to be the
541	/// current span.
542	///
543	/// If the subscriber indicates that it does not track the current span, or
544	/// that the thread from which this function is called is not currently
545	/// inside a span, the returned span will be disabled.
546	///
547	/// [considered by the `Subscriber`]:
548	/// super::subscriber::Subscriber::current_span
549	pub fn current() -> Span {
550	dispatcher::get_default(\|dispatch\| {
551	if let Some((id, meta)) = dispatch.current_span().into_inner() {
552	let id = dispatch.clone_span(&id);
553	Self {
554	inner: Some(Inner::new(id, dispatch)),
555	meta: Some(meta),
556	}
557	} else {
558	Self::none()
559	}
560	})
561	}
562
563	fn make_with(
564	meta: &'static Metadata<'static>,
565	new_span: Attributes<'_>,
566	dispatch: &Dispatch,
567	) -> Span {
568	let attrs = &new_span;
569	let id = dispatch.new_span(attrs);
570	let inner = Some(Inner::new(id, dispatch));
571
572	let span = Self {
573	inner,
574	meta: Some(meta),
575	};
576
577	if_log_enabled! { *meta.level(), {
578	let target = if attrs.is_empty() {
579	LIFECYCLE_LOG_TARGET
580	} else {
581	meta.target()
582	};
583	let values = attrs.values();
584	span.log(
585	target,
586	level_to_log!(*meta.level()),
587	format_args!("++ {};{}", meta.name(), crate::log::LogValueSet { values, is_first: `false` }),
588	);
589	}}
590
591	span
592	}
593
594	/// Enters this span, returning a guard that will exit the span when dropped.
595	///
596	/// If this span is enabled by the current subscriber, then this function will
597	/// call [`Subscriber::enter`] with the span's [`Id`], and dropping the guard
598	/// will call [`Subscriber::exit`]. If the span is disabled, this does
599	/// nothing.
600	///
601	/// # In Asynchronous Code
602	///
603	/// Warning: in asynchronous code that uses [async/await syntax][syntax],
604	/// `Span::enter` should be used very carefully or avoided entirely. Holding
605	/// the drop guard returned by `Span::enter` across `.await` points will
606	/// result in incorrect traces. For example,
607	///
608	/// ```
609	/// # use tracing::info_span;
610	/// # async fn some_other_async_function() {}
611	/// async fn my_async_function() {
612	/// let span = info_span!("my_async_function");
613	///
614	/// // WARNING: This span will remain entered until this
615	/// // guard is dropped...
616	/// let _enter = span.enter();
617	/// // ...but the `await` keyword may yield, causing the
618	/// // runtime to switch to another task, while remaining in
619	/// // this span!
620	/// some_other_async_function().await
621	///
622	/// // ...
623	/// }
624	/// ```
625	///
626	/// The drop guard returned by `Span::enter` exits the span when it is
627	/// dropped. When an async function or async block yields at an `.await`
628	/// point, the current scope is _exited_, but values in that scope are
629	/// not* dropped (because the async block will eventually resume*
630	/// execution from that await point). This means that _another_ task will
631	/// begin executing while _remaining_ in the entered span. This results in
632	/// an incorrect trace.
633	///
634	/// Instead of using `Span::enter` in asynchronous code, prefer the
635	/// following:
636	///
637	/// To enter a span for a synchronous section of code within an async*
638	/// block or function, prefer [`Span::in_scope`]. Since `in_scope` takes a
639	/// synchronous closure and exits the span when the closure returns, the
640	/// span will always be exited before the next await point. For example:
641	/// ```
642	/// # use tracing::info_span;
643	/// # async fn some_other_async_function(_: ()) {}
644	/// async fn my_async_function() {
645	/// let span = info_span!("my_async_function");
646	///
647	/// let some_value = span.in_scope(\|\| {
648	/// // run some synchronous code inside the span...
649	/// });
650	///
651	/// // This is okay! The span has already been exited before we reach
652	/// // the await point.
653	/// some_other_async_function(some_value).await;
654	///
655	/// // ...
656	/// }
657	/// ```
658	/// For instrumenting asynchronous code, `tracing` provides the*
659	/// [`Future::instrument` combinator][instrument] for
660	/// attaching a span to a future (async function or block). This will
661	/// enter the span _every_ time the future is polled, and exit it whenever
662	/// the future yields.
663	///
664	/// `Instrument` can be used with an async block inside an async function:
665	/// ```ignore
666	/// # use tracing::info_span;
667	/// use tracing::Instrument;
668	///
669	/// # async fn some_other_async_function() {}
670	/// async fn my_async_function() {
671	/// let span = info_span!("my_async_function");
672	/// async move {
673	/// // This is correct! If we yield here, the span will be exited,
674	/// // and re-entered when we resume.
675	/// some_other_async_function().await;
676	///
677	/// //more asynchronous code inside the span...
678	///
679	/// }
680	/// // instrument the async block with the span...
681	/// .instrument(span)
682	/// // ...and await it.
683	/// .await
684	/// }
685	/// ```
686	///
687	/// It can also be used to instrument calls to async functions at the
688	/// callsite:
689	/// ```ignore
690	/// # use tracing::debug_span;
691	/// use tracing::Instrument;
692	///
693	/// # async fn some_other_async_function() {}
694	/// async fn my_async_function() {
695	/// let some_value = some_other_async_function()
696	/// .instrument(debug_span!("some_other_async_function"))
697	/// .await;
698	///
699	/// // ...
700	/// }
701	/// ```
702	///
703	/// The* [`#[instrument]` attribute macro][attr] can automatically generate
704	/// correct code when used on an async function:
705	///
706	/// ```ignore
707	/// # async fn some_other_async_function() {}
708	/// #[tracing::instrument(level = "info")]
709	/// async fn my_async_function() {
710	///
711	/// // This is correct! If we yield here, the span will be exited,
712	/// // and re-entered when we resume.
713	/// some_other_async_function().await;
714	///
715	/// // ...
716	///
717	/// }
718	/// ```
719	///
720	/// [syntax]: https://rust-lang.github.io/async-book/01_getting_started/04_async_await_primer.html
721	/// [`Span::in_scope`]: Span::in_scope()
722	/// [instrument]: crate::Instrument
723	/// [attr]: macro@crate::instrument
724	///
725	/// # Examples
726	///
727	/// ```
728	/// # use tracing::{span, Level};
729	/// let span = span!(Level::INFO, "my_span");
730	/// let guard = span.enter();
731	///
732	/// // code here is within the span
733	///
734	/// drop(guard);
735	///
736	/// // code here is no longer within the span
737	///
738	/// ```
739	///
740	/// Guards need not be explicitly dropped:
741	///
742	/// ```
743	/// # use tracing::trace_span;
744	/// fn my_function() -> String {
745	/// // enter a span for the duration of this function.
746	/// let span = trace_span!("my_function");
747	/// let _enter = span.enter();
748	///
749	/// // anything happening in functions we call is still inside the span...
750	/// my_other_function();
751	///
752	/// // returning from the function drops the guard, exiting the span.
753	/// return "Hello world".to_owned();
754	/// }
755	///
756	/// fn my_other_function() {
757	/// // ...
758	/// }
759	/// ```
760	///
761	/// Sub-scopes may be created to limit the duration for which the span is
762	/// entered:
763	///
764	/// ```
765	/// # use tracing::{info, info_span};
766	/// let span = info_span!("my_great_span");
767	///
768	/// {
769	/// let _enter = span.enter();
770	///
771	/// // this event occurs inside the span.
772	/// info!("i'm in the span!");
773	///
774	/// // exiting the scope drops the guard, exiting the span.
775	/// }
776	///
777	/// // this event is not inside the span.
778	/// info!("i'm outside the span!")
779	/// ```
780	///
781	/// [`Subscriber::enter`]: super::subscriber::Subscriber::enter()
782	/// [`Subscriber::exit`]: super::subscriber::Subscriber::exit()
783	/// [`Id`]: super::Id
784	#[inline(always)]
785	pub fn enter(&self) -> Entered<'_> {
786	self.do_enter();
787	Entered { span: self }
788	}
789
790	/// Enters this span, consuming it and returning a [guard][`EnteredSpan`]
791	/// that will exit the span when dropped.
792	///
793	/// <pre class="compile_fail" style="white-space:normal;font:inherit;">
794	/// <strong>Warning</strong>: In asynchronous code that uses async/await syntax,
795	/// <code>Span::entered</code> may produce incorrect traces if the returned drop
796	/// guard is held across an await point. See <a href="#in-asynchronous-code">the
797	/// <code>Span::enter</code> documentation</a> for details.
798	/// </pre>
799	///
800	///
801	/// If this span is enabled by the current subscriber, then this function will
802	/// call [`Subscriber::enter`] with the span's [`Id`], and dropping the guard
803	/// will call [`Subscriber::exit`]. If the span is disabled, this does
804	/// nothing.
805	///
806	/// This is similar to the [`Span::enter`] method, except that it moves the
807	/// span by value into the returned guard, rather than borrowing it.
808	/// Therefore, this method can be used to create and enter a span in a
809	/// single expression, without requiring a `let`-binding. For example:
810	///
811	/// ```
812	/// # use tracing::info_span;
813	/// let _span = info_span!("something_interesting").entered();
814	/// ```
815	/// rather than:
816	/// ```
817	/// # use tracing::info_span;
818	/// let span = info_span!("something_interesting");
819	/// let _e = span.enter();
820	/// ```
821	///
822	/// Furthermore, `entered` may be used when the span must be stored in some
823	/// other struct or be passed to a function while remaining entered.
824	///
825	/// <pre class="ignore" style="white-space:normal;font:inherit;">
826	/// <strong>Note</strong>: The returned <a href="../struct.EnteredSpan.html">
827	/// <code>EnteredSpan</a></code> guard does not implement <code>Send</code>.
828	/// Dropping the guard will exit <em>this</em> span, and if the guard is sent
829	/// to another thread and dropped there, that thread may never have entered
830	/// this span. Thus, <code>EnteredSpan</code>s should not be sent between threads.
831	/// </pre>
832	///
833	/// [syntax]: https://rust-lang.github.io/async-book/01_getting_started/04_async_await_primer.html
834	///
835	/// # Examples
836	///
837	/// The returned guard can be [explicitly exited][EnteredSpan::exit],
838	/// returning the un-entered span:
839	///
840	/// ```
841	/// # use tracing::{Level, span};
842	/// let span = span!(Level::INFO, "doing_something").entered();
843	///
844	/// // code here is within the span
845	///
846	/// // explicitly exit the span, returning it
847	/// let span = span.exit();
848	///
849	/// // code here is no longer within the span
850	///
851	/// // enter the span again
852	/// let span = span.entered();
853	///
854	/// // now we are inside the span once again
855	/// ```
856	///
857	/// Guards need not be explicitly dropped:
858	///
859	/// ```
860	/// # use tracing::trace_span;
861	/// fn my_function() -> String {
862	/// // enter a span for the duration of this function.
863	/// let span = trace_span!("my_function").entered();
864	///
865	/// // anything happening in functions we call is still inside the span...
866	/// my_other_function();
867	///
868	/// // returning from the function drops the guard, exiting the span.
869	/// return "Hello world".to_owned();
870	/// }
871	///
872	/// fn my_other_function() {
873	/// // ...
874	/// }
875	/// ```
876	///
877	/// Since the [`EnteredSpan`] guard can dereference to the [`Span`] itself,
878	/// the span may still be accessed while entered. For example:
879	///
880	/// ```rust
881	/// # use tracing::info_span;
882	/// use tracing::field;
883	///
884	/// // create the span with an empty field, and enter it.
885	/// let span = info_span!("my_span", some_field = field::Empty).entered();
886	///
887	/// // we can still record a value for the field while the span is entered.
888	/// span.record("some_field", &"hello world!");
889	/// ```
890	///
891
892	/// [`Subscriber::enter`]: super::subscriber::Subscriber::enter()
893	/// [`Subscriber::exit`]: super::subscriber::Subscriber::exit()
894	/// [`Id`]: super::Id
895	#[inline(always)]
896	pub fn entered(self) -> EnteredSpan {
897	self.do_enter();
898	EnteredSpan {
899	span: self,
900	_not_send: PhantomNotSend,
901	}
902	}
903
904	/// Returns this span, if it was [enabled] by the current [`Subscriber`], or
905	/// the [current span] (whose lexical distance may be further than expected),
906	/// if this span [is disabled].
907	///
908	/// This method can be useful when propagating spans to spawned threads or
909	/// [async tasks]. Consider the following:
910	///
911	/// ```
912	/// let _parent_span = tracing::info_span!("parent").entered();
913	///
914	/// // ...
915	///
916	/// let child_span = tracing::debug_span!("child");
917	///
918	/// std::thread::spawn(move \|\| {
919	/// let _entered = child_span.entered();
920	///
921	/// tracing::info!("spawned a thread!");
922	///
923	/// // ...
924	/// });
925	/// ```
926	///
927	/// If the current [`Subscriber`] enables the [`DEBUG`] level, then both
928	/// the "parent" and "child" spans will be enabled. Thus, when the "spawaned
929	/// a thread!" event occurs, it will be inside of the "child" span. Because
930	/// "parent" is the parent of "child", the event will _also_ be inside of
931	/// "parent".
932	///
933	/// However, if the [`Subscriber`] only enables the [`INFO`] level, the "child"
934	/// span will be disabled. When the thread is spawned, the
935	/// `child_span.entered()` call will do nothing, since "child" is not
936	/// enabled. In this case, the "spawned a thread!" event occurs outside of
937	/// any* span, since the "child" span was responsible for propagating its*
938	/// parent to the spawned thread.
939	///
940	/// If this is not the desired behavior, `Span::or_current` can be used to
941	/// ensure that the "parent" span is propagated in both cases, either as a
942	/// parent of "child" _or_ directly. For example:
943	///
944	/// ```
945	/// let _parent_span = tracing::info_span!("parent").entered();
946	///
947	/// // ...
948	///
949	/// // If DEBUG is enabled, then "child" will be enabled, and `or_current`
950	/// // returns "child". Otherwise, if DEBUG is not enabled, "child" will be
951	/// // disabled, and `or_current` returns "parent".
952	/// let child_span = tracing::debug_span!("child").or_current();
953	///
954	/// std::thread::spawn(move \|\| {
955	/// let _entered = child_span.entered();
956	///
957	/// tracing::info!("spawned a thread!");
958	///
959	/// // ...
960	/// });
961	/// ```
962	///
963	/// When spawning [asynchronous tasks][async tasks], `Span::or_current` can
964	/// be used similarly, in combination with [`instrument`]:
965	///
966	/// ```
967	/// use tracing::Instrument;
968	/// # // lol
969	/// # mod tokio {
970	/// # pub(super) fn spawn(_: impl std::future::Future) {}
971	/// # }
972	///
973	/// let _parent_span = tracing::info_span!("parent").entered();
974	///
975	/// // ...
976	///
977	/// let child_span = tracing::debug_span!("child");
978	///
979	/// tokio::spawn(
980	/// async {
981	/// tracing::info!("spawned a task!");
982	///
983	/// // ...
984	///
985	/// }.instrument(child_span.or_current())
986	/// );
987	/// ```
988	///
989	/// In general, `or_current` should be preferred over nesting an
990	/// [`instrument`] call inside of an [`in_current_span`] call, as using
991	/// `or_current` will be more efficient.
992	///
993	/// ```
994	/// use tracing::Instrument;
995	/// # // lol
996	/// # mod tokio {
997	/// # pub(super) fn spawn(_: impl std::future::Future) {}
998	/// # }
999	/// async fn my_async_fn() {
1000	/// // ...
1001	/// }
1002	///
1003	/// let _parent_span = tracing::info_span!("parent").entered();
1004	///
1005	/// // Do this:
1006	/// tokio::spawn(
1007	/// my_async_fn().instrument(tracing::debug_span!("child").or_current())
1008	/// );
1009	///
1010	/// // ...rather than this:
1011	/// tokio::spawn(
1012	/// my_async_fn()
1013	/// .instrument(tracing::debug_span!("child"))
1014	/// .in_current_span()
1015	/// );
1016	/// ```
1017	///
1018	/// [enabled]: crate::Subscriber::enabled
1019	/// [`Subscriber`]: crate::Subscriber
1020	/// [current span]: Span::current
1021	/// [is disabled]: Span::is_disabled
1022	/// [`INFO`]: crate::Level::INFO
1023	/// [`DEBUG`]: crate::Level::DEBUG
1024	/// [async tasks]: std::task
1025	/// [`instrument`]: crate::instrument::Instrument::instrument
1026	/// [`in_current_span`]: crate::instrument::Instrument::in_current_span
1027	pub fn or_current(self) -> Self {
1028	if self.is_disabled() {
1029	return Self::current();
1030	}
1031	self
1032	}
1033
1034	#[inline(always)]
1035	fn do_enter(&self) {
1036	if let Some(inner) = self.inner.as_ref() {
1037	inner.subscriber.enter(&inner.id);
1038	}
1039
1040	if_log_enabled! { crate::Level::TRACE, {
1041	if let Some(_meta) = self.meta {
1042	self.log(ACTIVITY_LOG_TARGET, log::Level::Trace, format_args!("-> {};", _meta.name()));
1043	}
1044	}}
1045	}
1046
1047	// Called from [`Entered`] and [`EnteredSpan`] drops.
1048	//
1049	// Running this behaviour on drop rather than with an explicit function
1050	// call means that spans may still be exited when unwinding.
1051	#[inline(always)]
1052	fn do_exit(&self) {
1053	if let Some(inner) = self.inner.as_ref() {
1054	inner.subscriber.exit(&inner.id);
1055	}
1056
1057	if_log_enabled! { crate::Level::TRACE, {
1058	if let Some(_meta) = self.meta {
1059	self.log(ACTIVITY_LOG_TARGET, log::Level::Trace, format_args!("<- {};", _meta.name()));
1060	}
1061	}}
1062	}
1063
1064	/// Executes the given function in the context of this span.
1065	///
1066	/// If this span is enabled, then this function enters the span, invokes `f`
1067	/// and then exits the span. If the span is disabled, `f` will still be
1068	/// invoked, but in the context of the currently-executing span (if there is
1069	/// one).
1070	///
1071	/// Returns the result of evaluating `f`.
1072	///
1073	/// # Examples
1074	///
1075	/// ```
1076	/// # use tracing::{trace, span, Level};
1077	/// let my_span = span!(Level::TRACE, "my_span");
1078	///
1079	/// my_span.in_scope(\|\| {
1080	/// // this event occurs within the span.
1081	/// trace!("i'm in the span!");
1082	/// });
1083	///
1084	/// // this event occurs outside the span.
1085	/// trace!("i'm not in the span!");
1086	/// ```
1087	///
1088	/// Calling a function and returning the result:
1089	/// ```
1090	/// # use tracing::{info_span, Level};
1091	/// fn hello_world() -> String {
1092	/// "Hello world!".to_owned()
1093	/// }
1094	///
1095	/// let span = info_span!("hello_world");
1096	/// // the span will be entered for the duration of the call to
1097	/// // `hello_world`.
1098	/// let a_string = span.in_scope(hello_world);
1099	///
1100	pub fn in_scope<F: FnOnce() -> T, T>(&self, f: F) -> T {
1101	let _enter = self.enter();
1102	f()
1103	}
1104
1105	/// Returns a [`Field`][super::field::Field] for the field with the
1106	/// given `name`, if one exists,
1107	pub fn field<Q: ?Sized>(&self, field: &Q) -> Option<field::Field>
1108	where
1109	Q: field::AsField,
1110	{
1111	self.metadata().and_then(\|meta\| field.as_field(meta))
1112	}
1113
1114	/// Returns true if this `Span` has a field for the given
1115	/// [`Field`][super::field::Field] or field name.
1116	#[inline]
1117	pub fn has_field<Q: ?Sized>(&self, field: &Q) -> bool
1118	where
1119	Q: field::AsField,
1120	{
1121	self.field(field).is_some()
1122	}
1123
1124	/// Records that the field described by `field` has the value `value`.
1125	///
1126	/// This may be used with [`field::Empty`] to declare fields whose values
1127	/// are not known when the span is created, and record them later:
1128	/// ```
1129	/// use tracing::{trace_span, field};
1130	///
1131	/// // Create a span with two fields: `greeting`, with the value "hello world", and
1132	/// // `parting`, without a value.
1133	/// let span = trace_span!("my_span", greeting = "hello world", parting = field::Empty);
1134	///
1135	/// // ...
1136	///
1137	/// // Now, record a value for parting as well.
1138	/// // (note that the field name is passed as a string slice)
1139	/// span.record("parting", "goodbye world!");
1140	/// ```
1141	/// However, it may also be used to record a _new_ value for a field whose
1142	/// value was already recorded:
1143	/// ```
1144	/// use tracing::info_span;
1145	/// # fn do_something() -> Result<(), ()> { Err(()) }
1146	///
1147	/// // Initially, let's assume that our attempt to do something is going okay...
1148	/// let span = info_span!("doing_something", is_okay = `true`);
1149	/// let _e = span.enter();
1150	///
1151	/// match do_something() {
1152	/// Ok(something) => {
1153	/// // ...
1154	/// }
1155	/// Err(_) => {
1156	/// // Things are no longer okay!
1157	/// span.record("is_okay", `false`);
1158	/// }
1159	/// }
1160	/// ```
1161	///
1162	/// <pre class="ignore" style="white-space:normal;font:inherit;">
1163	/// <strong>Note</strong>: The fields associated with a span are part
1164	/// of its <a href="../struct.Metadata.html"><code>Metadata</code></a>.
1165	/// The <a href="../struct.Metadata.html"><code>Metadata</code></a>
1166	/// describing a particular span is constructed statically when the span
1167	/// is created and cannot be extended later to add new fields. Therefore,
1168	/// you cannot record a value for a field that was not specified when the
1169	/// span was created:
1170	/// </pre>
1171	///
1172	/// ```
1173	/// use tracing::{trace_span, field};
1174	///
1175	/// // Create a span with two fields: `greeting`, with the value "hello world", and
1176	/// // `parting`, without a value.
1177	/// let span = trace_span!("my_span", greeting = "hello world", parting = field::Empty);
1178	///
1179	/// // ...
1180	///
1181	/// // Now, you try to record a value for a new field, `new_field`, which was not
1182	/// // declared as `Empty` or populated when you created `span`.
1183	/// // You won't get any error, but the assignment will have no effect!
1184	/// span.record("new_field", "interesting_value_you_really_need");
1185	///
1186	/// // Instead, all fields that may be recorded after span creation should be declared up front,
1187	/// // using field::Empty when a value is not known, as we did for `parting`.
1188	/// // This `record` call will indeed replace field::Empty with "you will be remembered".
1189	/// span.record("parting", "you will be remembered");
1190	/// ```
1191	///
1192	/// [`field::Empty`]: super::field::Empty
1193	/// [`Metadata`]: super::Metadata
1194	pub fn record<Q: ?Sized, V>(&self, field: &Q, value: V) -> &Self
1195	where
1196	Q: field::AsField,
1197	V: field::Value,
1198	{
1199	if let Some(meta) = self.meta {
1200	if let Some(field) = field.as_field(meta) {
1201	self.record_all(
1202	&meta
1203	.fields()
1204	.value_set(&[(&field, Some(&value as &dyn field::Value))]),
1205	);
1206	}
1207	}
1208
1209	self
1210	}
1211
1212	/// Records all the fields in the provided `ValueSet`.
1213	pub fn record_all(&self, values: &field::ValueSet<'_>) -> &Self {
1214	let record = Record::new(values);
1215	if let Some(ref inner) = self.inner {
1216	inner.record(&record);
1217	}
1218
1219	if let Some(_meta) = self.meta {
1220	if_log_enabled! { *_meta.level(), {
1221	let target = if record.is_empty() {
1222	LIFECYCLE_LOG_TARGET
1223	} else {
1224	_meta.target()
1225	};
1226	self.log(
1227	target,
1228	level_to_log!(*_meta.level()),
1229	format_args!("{};{}", _meta.name(), crate::log::LogValueSet { values, is_first: `false` }),
1230	);
1231	}}
1232	}
1233
1234	self
1235	}
1236
1237	/// Returns `true` if this span was disabled by the subscriber and does not
1238	/// exist.
1239	///
1240	/// See also [`is_none`].
1241	///
1242	/// [`is_none`]: Span::is_none()
1243	#[inline]
1244	pub fn is_disabled(&self) -> bool {
1245	self.inner.is_none()
1246	}
1247
1248	/// Returns `true` if this span was constructed by [`Span::none`] and is
1249	/// empty.
1250	///
1251	/// If `is_none` returns `true` for a given span, then [`is_disabled`] will
1252	/// also return `true`. However, when a span is disabled by the subscriber
1253	/// rather than constructed by `Span::none`, this method will return
1254	/// `false`, while `is_disabled` will return `true`.
1255	///
1256	/// [`Span::none`]: Span::none()
1257	/// [`is_disabled`]: Span::is_disabled()
1258	#[inline]
1259	pub fn is_none(&self) -> bool {
1260	self.is_disabled() && self.meta.is_none()
1261	}
1262
1263	/// Indicates that the span with the given ID has an indirect causal
1264	/// relationship with this span.
1265	///
1266	/// This relationship differs somewhat from the parent-child relationship: a
1267	/// span may have any number of prior spans, rather than a single one; and
1268	/// spans are not considered to be executing _inside_ of the spans they
1269	/// follow from. This means that a span may close even if subsequent spans
1270	/// that follow from it are still open, and time spent inside of a
1271	/// subsequent span should not be included in the time its precedents were
1272	/// executing. This is used to model causal relationships such as when a
1273	/// single future spawns several related background tasks, et cetera.
1274	///
1275	/// If this span is disabled, or the resulting follows-from relationship
1276	/// would be invalid, this function will do nothing.
1277	///
1278	/// # Examples
1279	///
1280	/// Setting a `follows_from` relationship with a `Span`:
1281	/// ```
1282	/// # use tracing::{span, Id, Level, Span};
1283	/// let span1 = span!(Level::INFO, "span_1");
1284	/// let span2 = span!(Level::DEBUG, "span_2");
1285	/// span2.follows_from(span1);
1286	/// ```
1287	///
1288	/// Setting a `follows_from` relationship with the current span:
1289	/// ```
1290	/// # use tracing::{span, Id, Level, Span};
1291	/// let span = span!(Level::INFO, "hello!");
1292	/// span.follows_from(Span::current());
1293	/// ```
1294	///
1295	/// Setting a `follows_from` relationship with a `Span` reference:
1296	/// ```
1297	/// # use tracing::{span, Id, Level, Span};
1298	/// let span = span!(Level::INFO, "hello!");
1299	/// let curr = Span::current();
1300	/// span.follows_from(&curr);
1301	/// ```
1302	///
1303	/// Setting a `follows_from` relationship with an `Id`:
1304	/// ```
1305	/// # use tracing::{span, Id, Level, Span};
1306	/// let span = span!(Level::INFO, "hello!");
1307	/// let id = span.id();
1308	/// span.follows_from(id);
1309	/// ```
1310	pub fn follows_from(&self, from: impl Into<Option<Id>>) -> &Self {
1311	if let Some(ref inner) = self.inner {
1312	if let Some(from) = from.into() {
1313	inner.follows_from(&from);
1314	}
1315	}
1316	self
1317	}
1318
1319	/// Returns this span's `Id`, if it is enabled.
1320	pub fn id(&self) -> Option<Id> {
1321	self.inner.as_ref().map(Inner::id)
1322	}
1323
1324	/// Returns this span's `Metadata`, if it is enabled.
1325	pub fn metadata(&self) -> Option<&'static Metadata<'static>> {
1326	self.meta
1327	}
1328
1329	#[cfg(feature = "log")]
1330	#[inline]
1331	fn log(&self, target: &str, level: log::Level, message: fmt::Arguments<'_>) {
1332	if let Some(meta) = self.meta {
1333	if level_to_log!(*meta.level()) <= log::max_level() {
1334	let logger = log::logger();
1335	let log_meta = log::Metadata::builder().level(level).target(target).build();
1336	if logger.enabled(&log_meta) {
1337	if let Some(ref inner) = self.inner {
1338	logger.log(
1339	&log::Record::builder()
1340	.metadata(log_meta)
1341	.module_path(meta.module_path())
1342	.file(meta.file())
1343	.line(meta.line())
1344	.args(format_args!("{} span={}", message, inner.id.into_u64()))
1345	.build(),
1346	);
1347	} else {
1348	logger.log(
1349	&log::Record::builder()
1350	.metadata(log_meta)
1351	.module_path(meta.module_path())
1352	.file(meta.file())
1353	.line(meta.line())
1354	.args(message)
1355	.build(),
1356	);
1357	}
1358	}
1359	}
1360	}
1361	}
1362
1363	/// Invokes a function with a reference to this span's ID and subscriber.
1364	///
1365	/// if this span is enabled, the provided function is called, and the result is returned.
1366	/// If the span is disabled, the function is not called, and this method returns `None`
1367	/// instead.
1368	pub fn with_subscriber<T>(&self, f: impl FnOnce((&Id, &Dispatch)) -> T) -> Option<T> {
1369	self.inner
1370	.as_ref()
1371	.map(\|inner\| f((&inner.id, &inner.subscriber)))
1372	}
1373	}
1374
1375	impl cmp::PartialEq for Span {
1376	fn eq(&self, other: &Self) -> bool {
1377	match (&self.meta, &other.meta) {
1378	(Some(this: &&'static Metadata<'_>), Some(that: &&'static Metadata<'_>)) => {
1379	this.callsite() == that.callsite() && self.inner == other.inner
1380	}
1381	_ => `false`,
1382	}
1383	}
1384	}
1385
1386	impl Hash for Span {
1387	fn hash<H: Hasher>(&self, hasher: &mut H) {
1388	self.inner.hash(state:hasher);
1389	}
1390	}
1391
1392	impl fmt::Debug for Span {
1393	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1394	let mut span = f.debug_struct("Span");
1395	if let Some(meta) = self.meta {
1396	span.field("name", &meta.name())
1397	.field("level", &meta.level())
1398	.field("target", &meta.target());
1399
1400	if let Some(ref inner) = self.inner {
1401	span.field("id", &inner.id());
1402	} else {
1403	span.field("disabled", &`true`);
1404	}
1405
1406	if let Some(ref path) = meta.module_path() {
1407	span.field("module_path", &path);
1408	}
1409
1410	if let Some(ref line) = meta.line() {
1411	span.field("line", &line);
1412	}
1413
1414	if let Some(ref file) = meta.file() {
1415	span.field("file", &file);
1416	}
1417	} else {
1418	span.field("none", &`true`);
1419	}
1420
1421	span.finish()
1422	}
1423	}
1424
1425	impl<'a> From<&'a Span> for Option<&'a Id> {
1426	fn from(span: &'a Span) -> Self {
1427	span.inner.as_ref().map(\|inner: &Inner\| &inner.id)
1428	}
1429	}
1430
1431	impl<'a> From<&'a Span> for Option<Id> {
1432	fn from(span: &'a Span) -> Self {
1433	span.inner.as_ref().map(Inner::id)
1434	}
1435	}
1436
1437	impl From<Span> for Option<Id> {
1438	fn from(span: Span) -> Self {
1439	span.inner.as_ref().map(Inner::id)
1440	}
1441	}
1442
1443	impl<'a> From<&'a EnteredSpan> for Option<&'a Id> {
1444	fn from(span: &'a EnteredSpan) -> Self {
1445	span.inner.as_ref().map(\|inner: &Inner\| &inner.id)
1446	}
1447	}
1448
1449	impl<'a> From<&'a EnteredSpan> for Option<Id> {
1450	fn from(span: &'a EnteredSpan) -> Self {
1451	span.inner.as_ref().map(Inner::id)
1452	}
1453	}
1454
1455	impl Drop for Span {
1456	#[inline(always)]
1457	fn drop(&mut self) {
1458	if let Some(Inner {
1459	ref id: &Id,
1460	ref subscriber: &Dispatch,
1461	}) = self.inner
1462	{
1463	subscriber.try_close(id.clone());
1464	}
1465
1466	if_log_enabled! { crate::Level::TRACE, {
1467	if let Some(meta) = self.meta {
1468	self.log(
1469	LIFECYCLE_LOG_TARGET,
1470	log::Level::Trace,
1471	format_args!("-- {};", meta.name()),
1472	);
1473	}
1474	}}
1475	}
1476	}
1477
1478	// ===== impl Inner =====
1479
1480	impl Inner {
1481	/// Indicates that the span with the given ID has an indirect causal
1482	/// relationship with this span.
1483	///
1484	/// This relationship differs somewhat from the parent-child relationship: a
1485	/// span may have any number of prior spans, rather than a single one; and
1486	/// spans are not considered to be executing _inside_ of the spans they
1487	/// follow from. This means that a span may close even if subsequent spans
1488	/// that follow from it are still open, and time spent inside of a
1489	/// subsequent span should not be included in the time its precedents were
1490	/// executing. This is used to model causal relationships such as when a
1491	/// single future spawns several related background tasks, et cetera.
1492	///
1493	/// If this span is disabled, this function will do nothing. Otherwise, it
1494	/// returns `Ok(())` if the other span was added as a precedent of this
1495	/// span, or an error if this was not possible.
1496	fn follows_from(&self, from: &Id) {
1497	self.subscriber.record_follows_from(&self.id, from)
1498	}
1499
1500	/// Returns the span's ID.
1501	fn id(&self) -> Id {
1502	self.id.clone()
1503	}
1504
1505	fn record(&self, values: &Record<'_>) {
1506	self.subscriber.record(&self.id, values)
1507	}
1508
1509	fn new(id: Id, subscriber: &Dispatch) -> Self {
1510	Inner {
1511	id,
1512	subscriber: subscriber.clone(),
1513	}
1514	}
1515	}
1516
1517	impl cmp::PartialEq for Inner {
1518	fn eq(&self, other: &Self) -> bool {
1519	self.id == other.id
1520	}
1521	}
1522
1523	impl Hash for Inner {
1524	fn hash<H: Hasher>(&self, state: &mut H) {
1525	self.id.hash(state);
1526	}
1527	}
1528
1529	impl Clone for Inner {
1530	fn clone(&self) -> Self {
1531	Inner {
1532	id: self.subscriber.clone_span(&self.id),
1533	subscriber: self.subscriber.clone(),
1534	}
1535	}
1536	}
1537
1538	// ===== impl Entered =====
1539
1540	impl EnteredSpan {
1541	/// Returns this span's `Id`, if it is enabled.
1542	pub fn id(&self) -> Option<Id> {
1543	self.inner.as_ref().map(Inner::id)
1544	}
1545
1546	/// Exits this span, returning the underlying [`Span`].
1547	#[inline]
1548	pub fn exit(mut self) -> Span {
1549	// One does not simply move out of a struct with `Drop`.
1550	let span: Span = mem::replace(&mut self.span, src:Span::none());
1551	span.do_exit();
1552	span
1553	}
1554	}
1555
1556	impl Deref for EnteredSpan {
1557	type Target = Span;
1558
1559	#[inline]
1560	fn deref(&self) -> &Span {
1561	&self.span
1562	}
1563	}
1564
1565	impl<'a> Drop for Entered<'a> {
1566	#[inline(always)]
1567	fn drop(&mut self) {
1568	self.span.do_exit()
1569	}
1570	}
1571
1572	impl Drop for EnteredSpan {
1573	#[inline(always)]
1574	fn drop(&mut self) {
1575	self.span.do_exit()
1576	}
1577	}
1578
1579	/// Technically, `EnteredSpan` _can_ implement both `Send` and
1580	/// `Sync` safely. It doesn't, because it has a `PhantomNotSend` field,
1581	/// specifically added in order to make it `!Send`.
1582	///
1583	/// Sending an `EnteredSpan` guard between threads cannot cause memory unsafety.
1584	/// However, it would* result in incorrect behavior, so we add a*
1585	/// `PhantomNotSend` to prevent it from being sent between threads. This is
1586	/// because it must be dropped* on the same thread that it was created;*
1587	/// otherwise, the span will never be exited on the thread where it was entered,
1588	/// and it will attempt to exit the span on a thread that may never have entered
1589	/// it. However, we still want them to be `Sync` so that a struct holding an
1590	/// `Entered` guard can be `Sync`.
1591	///
1592	/// Thus, this is totally safe.
1593	#[derive(Debug)]
1594	struct PhantomNotSend {
1595	ghost: PhantomData<*mut ()>,
1596	}
1597
1598	#[allow(non_upper_case_globals)]
1599	const PhantomNotSend: PhantomNotSend = PhantomNotSend { ghost: PhantomData };
1600
1601	/// # Safety
1602	///
1603	/// Trivially safe, as `PhantomNotSend` doesn't have any API.
1604	unsafe impl Sync for PhantomNotSend {}
1605
1606	#[cfg(test)]
1607	mod test {
1608	use super::*;
1609
1610	trait AssertSend: Send {}
1611	impl AssertSend for Span {}
1612
1613	trait AssertSync: Sync {}
1614	impl AssertSync for Span {}
1615	impl AssertSync for Entered<'_> {}
1616	impl AssertSync for EnteredSpan {}
1617
1618	#[test]
1619	fn test_record_backwards_compat() {
1620	Span::current().record("some-key", &"some text");
1621	Span::current().record("some-key", &`false`);
1622	}
1623	}
1624