[−][src]Struct tracing::span::Span
A handle representing a span, with the capability to enter the span if it exists.
If the span was rejected by the current Subscriber
's filter, entering the
span will silently do nothing. Thus, the handle can be used in the same
manner regardless of whether or not the trace is currently being collected.
Methods
impl Span
[src]
pub fn new(meta: &'static Metadata<'static>, values: &ValueSet) -> Span
[src]
Constructs a new Span
with the given metadata and set of
field values.
The new span will be constructed by the currently-active Subscriber
,
with the current span as its parent (if one exists).
After the span is constructed, field values and/or follows_from
annotations may be added to it.
pub fn new_root(meta: &'static Metadata<'static>, values: &ValueSet) -> Span
[src]
Constructs a new Span
as the root of its own trace tree, with the
given metadata and set of field values.
After the span is constructed, field values and/or follows_from
annotations may be added to it.
pub fn child_of(
parent: impl Into<Option<Id>>,
meta: &'static Metadata<'static>,
values: &ValueSet
) -> Span
[src]
parent: impl Into<Option<Id>>,
meta: &'static Metadata<'static>,
values: &ValueSet
) -> Span
Constructs a new Span
as child of the given parent span, with the
given metadata and set of field values.
After the span is constructed, field values and/or follows_from
annotations may be added to it.
pub fn new_disabled(meta: &'static Metadata<'static>) -> Span
[src]
Constructs a new disabled span with the given Metadata
.
This should be used when a span is constructed from a known callsite, but the subscriber indicates that it is disabled.
Entering, exiting, and recording values on this span will not notify the
Subscriber
but may record log messages if the log
feature flag is
enabled.
pub const fn none() -> Span
[src]
Constructs a new span that is completely disabled.
This can be used rather than Option<Span>
to represent cases where a
span is not present.
Entering, exiting, and recording values on this span will do nothing.
pub fn current() -> Span
[src]
Returns a handle to the span considered by the Subscriber
to be the
current span.
If the subscriber indicates that it does not track the current span, or that the thread from which this function is called is not currently inside a span, the returned span will be disabled.
pub fn enter(&self) -> Entered
[src]
Enters this span, returning a guard that will exit the span when dropped.
If this span is enabled by the current subscriber, then this function will
call Subscriber::enter
with the span's Id
, and dropping the guard
will call Subscriber::exit
. If the span is disabled, this does nothing.
Examples
#[macro_use] extern crate tracing; let span = span!(Level::INFO, "my_span"); let guard = span.enter(); // code here is within the span drop(guard); // code here is no longer within the span
Guards need not be explicitly dropped:
#[macro_use] extern crate tracing; fn my_function() -> String { // enter a span for the duration of this function. let span = trace_span!("my_function"); let _enter = span.enter(); // anything happening in functions we call is still inside the span... my_other_function(); // returning from the function drops the guard, exiting the span. return "Hello world".to_owned(); } fn my_other_function() { // ... }
Sub-scopes may be created to limit the duration for which the span is entered:
#[macro_use] extern crate tracing; let span = info_span!("my_great_span"); { let _enter = span.enter(); // this event occurs inside the span. info!("i'm in the span!"); // exiting the scope drops the guard, exiting the span. } // this event is not inside the span. info!("i'm outside the span!")
pub fn in_scope<F: FnOnce() -> T, T>(&self, f: F) -> T
[src]
Executes the given function in the context of this span.
If this span is enabled, then this function enters the span, invokes f
and then exits the span. If the span is disabled, f
will still be
invoked, but in the context of the currently-executing span (if there is
one).
Returns the result of evaluating f
.
Examples
let my_span = span!(Level::TRACE, "my_span"); my_span.in_scope(|| { // this event occurs within the span. trace!("i'm in the span!"); }); // this event occurs outside the span. trace!("i'm not in the span!");
Calling a function and returning the result:
fn hello_world() -> String { "Hello world!".to_owned() } let span = info_span!("hello_world"); // the span will be entered for the duration of the call to // `hello_world`. let a_string = span.in_scope(hello_world);
pub fn field<Q: ?Sized>(&self, field: &Q) -> Option<Field> where
Q: AsField,
[src]
Q: AsField,
Returns a Field
for the field with the
given name
, if one exists,
pub fn has_field<Q: ?Sized>(&self, field: &Q) -> bool where
Q: AsField,
[src]
Q: AsField,
Returns true if this Span
has a field for the given
Field
or field name.
pub fn record<Q: ?Sized, V>(&self, field: &Q, value: &V) -> &Self where
Q: AsField,
V: Value,
[src]
Q: AsField,
V: Value,
Records that the field described by field
has the value value
.
This may be used with field::Empty
to declare fields whose values
are not known when the span is created, and record them later:
use tracing::{trace_span, field}; // Create a span with two fields: `greeting`, with the value "hello world", and // `parting`, without a value. let span = trace_span!("my_span", greeting = "hello world", parting = field::Empty); // ... // Now, record a value for parting as well. // (note that the field name is passed as a string slice) span.record("parting", &"goodbye world!");
However, it may also be used to record a new value for a field whose value was already recorded:
use tracing::info_span; // Initially, let's assume that our attempt to do something is going okay... let span = info_span!("doing_something", is_okay = true); let _e = span.enter(); match do_something() { Ok(something) => { // ... } Err(_) => { // Things are no longer okay! span.record("is_okay", &false); } }
pub fn record_all(&self, values: &ValueSet) -> &Self
[src]
Records all the fields in the provided ValueSet
.
pub fn is_disabled(&self) -> bool
[src]
Returns true
if this span was disabled by the subscriber and does not
exist.
See also is_none
.
pub fn is_none(&self) -> bool
[src]
Returns true
if this span was constructed by Span::none
and is
empty.
If is_none
returns true
for a given span, then is_disabled
will
also return true
. However, when a span is disabled by the subscriber
rather than constructed by Span::none
, this method will return
false
, while is_disabled
will return true
.
pub fn follows_from(&self, from: impl Into<Option<Id>>) -> &Self
[src]
Indicates that the span with the given ID has an indirect causal relationship with this span.
This relationship differs somewhat from the parent-child relationship: a span may have any number of prior spans, rather than a single one; and spans are not considered to be executing inside of the spans they follow from. This means that a span may close even if subsequent spans that follow from it are still open, and time spent inside of a subsequent span should not be included in the time its precedents were executing. This is used to model causal relationships such as when a single future spawns several related background tasks, et cetera.
If this span is disabled, or the resulting follows-from relationship would be invalid, this function will do nothing.
Examples
Setting a follows_from
relationship with a Span
:
let span1 = span!(Level::INFO, "span_1"); let span2 = span!(Level::DEBUG, "span_2"); span2.follows_from(span1);
Setting a follows_from
relationship with the current span:
let span = span!(Level::INFO, "hello!"); span.follows_from(Span::current());
Setting a follows_from
relationship with a Span
reference:
let span = span!(Level::INFO, "hello!"); let curr = Span::current(); span.follows_from(&curr);
Setting a follows_from
relationship with an Id
:
let span = span!(Level::INFO, "hello!"); let id = span.id(); span.follows_from(id);
pub fn id(&self) -> Option<Id>
[src]
Returns this span's Id
, if it is enabled.
pub fn metadata(&self) -> Option<&'static Metadata<'static>>
[src]
Returns this span's Metadata
, if it is enabled.
pub fn with_subscriber<T>(
&self,
f: impl FnOnce((&Id, &Dispatch)) -> T
) -> Option<T>
[src]
&self,
f: impl FnOnce((&Id, &Dispatch)) -> T
) -> Option<T>
Invokes a function with a reference to this span's ID and subscriber.
if this span is enabled, the provided function is called, and the result is returned.
If the span is disabled, the function is not called, and this method returns None
instead.
Trait Implementations
impl Clone for Span
[src]
impl Debug for Span
[src]
impl Drop for Span
[src]
impl Hash for Span
[src]
fn hash<H: Hasher>(&self, hasher: &mut H)
[src]
fn hash_slice<H>(data: &[Self], state: &mut H) where
H: Hasher,
1.3.0[src]
H: Hasher,
impl<'a> Into<Option<&'a Id>> for &'a Span
[src]
impl<'a> Into<Option<Id>> for &'a Span
[src]
impl Into<Option<Id>> for Span
[src]
impl PartialEq<Span> for Span
[src]
Auto Trait Implementations
impl !RefUnwindSafe for Span
impl Send for Span
impl Sync for Span
impl Unpin for Span
impl !UnwindSafe for Span
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T> ToOwned for T where
T: Clone,
[src]
T: Clone,
type Owned = T
The resulting type after obtaining ownership.
fn to_owned(&self) -> T
[src]
fn clone_into(&self, target: &mut T)
[src]
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,