Struct abscissa_core::prelude::span::EnteredSpan
source · [−]pub struct EnteredSpan { /* private fields */ }
Expand description
An owned version of Entered
, a guard representing a span which has been
entered and is currently executing.
When the guard is dropped, the span will be exited.
This is returned by the Span::entered
function.
Implementations
sourceimpl EnteredSpan
impl EnteredSpan
Methods from Deref<Target = Span>
sourcepub fn enter(&self) -> Entered<'_>
pub fn enter(&self) -> Entered<'_>
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.
In Asynchronous Code
Warning: in asynchronous code that uses async/await syntax,
Span::enter
should be used very carefully or avoided entirely. Holding
the drop guard returned by Span::enter
across .await
points will
result in incorrect traces. For example,
async fn my_async_function() {
let span = info_span!("my_async_function");
// THIS WILL RESULT IN INCORRECT TRACES
let _enter = span.enter();
some_other_async_function().await;
// ...
}
The drop guard returned by Span::enter
exits the span when it is
dropped. When an async function or async block yields at an .await
point, the current scope is exited, but values in that scope are
not dropped (because the async block will eventually resume
execution from that await point). This means that another task will
begin executing while remaining in the entered span. This results in
an incorrect trace.
Instead of using Span::enter
in asynchronous code, prefer the
following:
-
To enter a span for a synchronous section of code within an async block or function, prefer
Span::in_scope
. Sincein_scope
takes a synchronous closure and exits the span when the closure returns, the span will always be exited before the next await point. For example:async fn my_async_function() { let span = info_span!("my_async_function"); let some_value = span.in_scope(|| { // run some synchronous code inside the span... }); // This is okay! The span has already been exited before we reach // the await point. some_other_async_function(some_value).await; // ... }
-
For instrumenting asynchronous code,
tracing
provides theFuture::instrument
combinator for attaching a span to a future (async function or block). This will enter the span every time the future is polled, and exit it whenever the future yields.Instrument
can be used with an async block inside an async function:ⓘuse tracing::Instrument; async fn my_async_function() { let span = info_span!("my_async_function"); async move { // This is correct! If we yield here, the span will be exited, // and re-entered when we resume. some_other_async_function().await; //more asynchronous code inside the span... } // instrument the async block with the span... .instrument(span) // ...and await it. .await }
It can also be used to instrument calls to async functions at the callsite:
ⓘuse tracing::Instrument; async fn my_async_function() { let some_value = some_other_async_function() .instrument(debug_span!("some_other_async_function")) .await; // ... }
-
The
#[instrument]
attribute macro can automatically generate correct code when used on an async function:ⓘ#[tracing::instrument(level = "info")] async fn my_async_function() { // This is correct! If we yield here, the span will be exited, // and re-entered when we resume. some_other_async_function().await; // ... }
Examples
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:
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:
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!")
sourcepub fn in_scope<F, T>(&self, f: F) -> T where
F: FnOnce() -> T,
pub fn in_scope<F, T>(&self, f: F) -> T where
F: FnOnce() -> T,
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);
sourcepub fn field<Q>(&self, field: &Q) -> Option<Field> where
Q: AsField + ?Sized,
pub fn field<Q>(&self, field: &Q) -> Option<Field> where
Q: AsField + ?Sized,
Returns a Field
for the field with the
given name
, if one exists,
sourcepub fn has_field<Q>(&self, field: &Q) -> bool where
Q: AsField + ?Sized,
pub fn has_field<Q>(&self, field: &Q) -> bool where
Q: AsField + ?Sized,
Returns true if this Span
has a field for the given
Field
or field name.
sourcepub fn record<Q, V>(&self, field: &Q, value: &V) -> &Span where
Q: AsField + ?Sized,
V: Value,
pub fn record<Q, V>(&self, field: &Q, value: &V) -> &Span where
Q: AsField + ?Sized,
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);
}
}
Note: The fields associated with a span are part of itsMetadata
. TheMetadata
describing a particular span is constructed statically when the span is created and cannot be extended later to add new fields. Therefore, you cannot record a value for a field that was not specified when the span was created:
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, you try to record a value for a new field, `new_field`, which was not
// declared as `Empty` or populated when you created `span`.
// You won't get any error, but the assignment will have no effect!
span.record("new_field", &"interesting_value_you_really_need");
// Instead, all fields that may be recorded after span creation should be declared up front,
// using field::Empty when a value is not known, as we did for `parting`.
// This `record` call will indeed replace field::Empty with "you will be remembered".
span.record("parting", &"you will be remembered");
sourcepub fn record_all(&self, values: &ValueSet<'_>) -> &Span
pub fn record_all(&self, values: &ValueSet<'_>) -> &Span
Records all the fields in the provided ValueSet
.
sourcepub fn is_disabled(&self) -> bool
pub fn is_disabled(&self) -> bool
Returns true
if this span was disabled by the subscriber and does not
exist.
See also is_none
.
sourcepub fn is_none(&self) -> bool
pub fn is_none(&self) -> bool
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
.
sourcepub fn follows_from(&self, from: impl Into<Option<Id>>) -> &Span
pub fn follows_from(&self, from: impl Into<Option<Id>>) -> &Span
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);
sourcepub fn metadata(&self) -> Option<&'static Metadata<'static>>
pub fn metadata(&self) -> Option<&'static Metadata<'static>>
Returns this span’s Metadata
, if it is enabled.
sourcepub fn with_subscriber<T>(
&self,
f: impl FnOnce((&Id, &Dispatch)) -> T
) -> Option<T>
pub fn with_subscriber<T>(
&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
sourceimpl Debug for EnteredSpan
impl Debug for EnteredSpan
sourceimpl Deref for EnteredSpan
impl Deref for EnteredSpan
Auto Trait Implementations
impl !RefUnwindSafe for EnteredSpan
impl !Send for EnteredSpan
impl Sync for EnteredSpan
impl Unpin for EnteredSpan
impl !UnwindSafe for EnteredSpan
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcepub fn borrow_mut(&mut self) -> &mut T
pub fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
sourceimpl<T> Instrument for T
impl<T> Instrument for T
sourcefn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
sourcefn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
impl<D> OwoColorize for D
impl<D> OwoColorize for D
fn fg<C>(&self) -> FgColorDisplay<'_, C, Self> where
C: Color,
fn fg<C>(&self) -> FgColorDisplay<'_, C, Self> where
C: Color,
Set the foreground color generically Read more
fn bg<C>(&self) -> BgColorDisplay<'_, C, Self> where
C: Color,
fn bg<C>(&self) -> BgColorDisplay<'_, C, Self> where
C: Color,
Set the background color generically. Read more
fn black(&'a self) -> FgColorDisplay<'a, Black, Self>
fn black(&'a self) -> FgColorDisplay<'a, Black, Self>
Change the foreground color to black
fn on_black(&'a self) -> BgColorDisplay<'a, Black, Self>
fn on_black(&'a self) -> BgColorDisplay<'a, Black, Self>
Change the background color to black
fn red(&'a self) -> FgColorDisplay<'a, Red, Self>
fn red(&'a self) -> FgColorDisplay<'a, Red, Self>
Change the foreground color to red
fn on_red(&'a self) -> BgColorDisplay<'a, Red, Self>
fn on_red(&'a self) -> BgColorDisplay<'a, Red, Self>
Change the background color to red
fn green(&'a self) -> FgColorDisplay<'a, Green, Self>
fn green(&'a self) -> FgColorDisplay<'a, Green, Self>
Change the foreground color to green
fn on_green(&'a self) -> BgColorDisplay<'a, Green, Self>
fn on_green(&'a self) -> BgColorDisplay<'a, Green, Self>
Change the background color to green
fn yellow(&'a self) -> FgColorDisplay<'a, Yellow, Self>
fn yellow(&'a self) -> FgColorDisplay<'a, Yellow, Self>
Change the foreground color to yellow
fn on_yellow(&'a self) -> BgColorDisplay<'a, Yellow, Self>
fn on_yellow(&'a self) -> BgColorDisplay<'a, Yellow, Self>
Change the background color to yellow
fn blue(&'a self) -> FgColorDisplay<'a, Blue, Self>
fn blue(&'a self) -> FgColorDisplay<'a, Blue, Self>
Change the foreground color to blue
fn on_blue(&'a self) -> BgColorDisplay<'a, Blue, Self>
fn on_blue(&'a self) -> BgColorDisplay<'a, Blue, Self>
Change the background color to blue
fn magenta(&'a self) -> FgColorDisplay<'a, Magenta, Self>
fn magenta(&'a self) -> FgColorDisplay<'a, Magenta, Self>
Change the foreground color to magenta
fn on_magenta(&'a self) -> BgColorDisplay<'a, Magenta, Self>
fn on_magenta(&'a self) -> BgColorDisplay<'a, Magenta, Self>
Change the background color to magenta
fn purple(&'a self) -> FgColorDisplay<'a, Magenta, Self>
fn purple(&'a self) -> FgColorDisplay<'a, Magenta, Self>
Change the foreground color to purple
fn on_purple(&'a self) -> BgColorDisplay<'a, Magenta, Self>
fn on_purple(&'a self) -> BgColorDisplay<'a, Magenta, Self>
Change the background color to purple
fn cyan(&'a self) -> FgColorDisplay<'a, Cyan, Self>
fn cyan(&'a self) -> FgColorDisplay<'a, Cyan, Self>
Change the foreground color to cyan
fn on_cyan(&'a self) -> BgColorDisplay<'a, Cyan, Self>
fn on_cyan(&'a self) -> BgColorDisplay<'a, Cyan, Self>
Change the background color to cyan
fn white(&'a self) -> FgColorDisplay<'a, White, Self>
fn white(&'a self) -> FgColorDisplay<'a, White, Self>
Change the foreground color to white
fn on_white(&'a self) -> BgColorDisplay<'a, White, Self>
fn on_white(&'a self) -> BgColorDisplay<'a, White, Self>
Change the background color to white
fn default_color(&'a self) -> FgColorDisplay<'a, Default, Self>
fn default_color(&'a self) -> FgColorDisplay<'a, Default, Self>
Change the foreground color to the terminal default
fn on_default_color(&'a self) -> BgColorDisplay<'a, Default, Self>
fn on_default_color(&'a self) -> BgColorDisplay<'a, Default, Self>
Change the background color to the terminal default
fn bright_black(&'a self) -> FgColorDisplay<'a, BrightBlack, Self>
fn bright_black(&'a self) -> FgColorDisplay<'a, BrightBlack, Self>
Change the foreground color to bright black
fn on_bright_black(&'a self) -> BgColorDisplay<'a, BrightBlack, Self>
fn on_bright_black(&'a self) -> BgColorDisplay<'a, BrightBlack, Self>
Change the background color to bright black
fn bright_red(&'a self) -> FgColorDisplay<'a, BrightRed, Self>
fn bright_red(&'a self) -> FgColorDisplay<'a, BrightRed, Self>
Change the foreground color to bright red
fn on_bright_red(&'a self) -> BgColorDisplay<'a, BrightRed, Self>
fn on_bright_red(&'a self) -> BgColorDisplay<'a, BrightRed, Self>
Change the background color to bright red
fn bright_green(&'a self) -> FgColorDisplay<'a, BrightGreen, Self>
fn bright_green(&'a self) -> FgColorDisplay<'a, BrightGreen, Self>
Change the foreground color to bright green
fn on_bright_green(&'a self) -> BgColorDisplay<'a, BrightGreen, Self>
fn on_bright_green(&'a self) -> BgColorDisplay<'a, BrightGreen, Self>
Change the background color to bright green
fn bright_yellow(&'a self) -> FgColorDisplay<'a, BrightYellow, Self>
fn bright_yellow(&'a self) -> FgColorDisplay<'a, BrightYellow, Self>
Change the foreground color to bright yellow
fn on_bright_yellow(&'a self) -> BgColorDisplay<'a, BrightYellow, Self>
fn on_bright_yellow(&'a self) -> BgColorDisplay<'a, BrightYellow, Self>
Change the background color to bright yellow
fn bright_blue(&'a self) -> FgColorDisplay<'a, BrightBlue, Self>
fn bright_blue(&'a self) -> FgColorDisplay<'a, BrightBlue, Self>
Change the foreground color to bright blue
fn on_bright_blue(&'a self) -> BgColorDisplay<'a, BrightBlue, Self>
fn on_bright_blue(&'a self) -> BgColorDisplay<'a, BrightBlue, Self>
Change the background color to bright blue
fn bright_magenta(&'a self) -> FgColorDisplay<'a, BrightMagenta, Self>
fn bright_magenta(&'a self) -> FgColorDisplay<'a, BrightMagenta, Self>
Change the foreground color to bright magenta
fn on_bright_magenta(&'a self) -> BgColorDisplay<'a, BrightMagenta, Self>
fn on_bright_magenta(&'a self) -> BgColorDisplay<'a, BrightMagenta, Self>
Change the background color to bright magenta
fn bright_purple(&'a self) -> FgColorDisplay<'a, BrightMagenta, Self>
fn bright_purple(&'a self) -> FgColorDisplay<'a, BrightMagenta, Self>
Change the foreground color to bright purple
fn on_bright_purple(&'a self) -> BgColorDisplay<'a, BrightMagenta, Self>
fn on_bright_purple(&'a self) -> BgColorDisplay<'a, BrightMagenta, Self>
Change the background color to bright purple
fn bright_cyan(&'a self) -> FgColorDisplay<'a, BrightCyan, Self>
fn bright_cyan(&'a self) -> FgColorDisplay<'a, BrightCyan, Self>
Change the foreground color to bright cyan
fn on_bright_cyan(&'a self) -> BgColorDisplay<'a, BrightCyan, Self>
fn on_bright_cyan(&'a self) -> BgColorDisplay<'a, BrightCyan, Self>
Change the background color to bright cyan
fn bright_white(&'a self) -> FgColorDisplay<'a, BrightWhite, Self>
fn bright_white(&'a self) -> FgColorDisplay<'a, BrightWhite, Self>
Change the foreground color to bright white
fn on_bright_white(&'a self) -> BgColorDisplay<'a, BrightWhite, Self>
fn on_bright_white(&'a self) -> BgColorDisplay<'a, BrightWhite, Self>
Change the background color to bright white
fn bold(&'a self) -> BoldDisplay<'a, Self>
fn bold(&'a self) -> BoldDisplay<'a, Self>
Make the text bold
fn dimmed(&'a self) -> DimDisplay<'a, Self>
fn dimmed(&'a self) -> DimDisplay<'a, Self>
Make the text dim
fn italic(&'a self) -> ItalicDisplay<'a, Self>
fn italic(&'a self) -> ItalicDisplay<'a, Self>
Make the text italicized
fn underline(&'a self) -> UnderlineDisplay<'a, Self>
fn underline(&'a self) -> UnderlineDisplay<'a, Self>
Make the text italicized
fn blink(&'a self) -> BlinkDisplay<'a, Self>
fn blink(&'a self) -> BlinkDisplay<'a, Self>
Make the text blink
fn blink_fast(&'a self) -> BlinkFastDisplay<'a, Self>
fn blink_fast(&'a self) -> BlinkFastDisplay<'a, Self>
Make the text blink (but fast!)
fn reversed(&'a self) -> ReversedDisplay<'a, Self>
fn reversed(&'a self) -> ReversedDisplay<'a, Self>
Swap the foreground and background colors
Hide the text
fn strikethrough(&'a self) -> StrikeThroughDisplay<'a, Self>
fn strikethrough(&'a self) -> StrikeThroughDisplay<'a, Self>
Cross out the text
fn color<Color>(&self, color: Color) -> FgDynColorDisplay<'_, Color, Self> where
Color: DynColor,
fn color<Color>(&self, color: Color) -> FgDynColorDisplay<'_, Color, Self> where
Color: DynColor,
Set the foreground color at runtime. Only use if you do not know which color will be used at
compile-time. If the color is constant, use either OwoColorize::fg
or
a color-specific method, such as OwoColorize::green
, Read more
fn on_color<Color>(&self, color: Color) -> BgDynColorDisplay<'_, Color, Self> where
Color: DynColor,
fn on_color<Color>(&self, color: Color) -> BgDynColorDisplay<'_, Color, Self> where
Color: DynColor,
Set the background color at runtime. Only use if you do not know what color to use at
compile-time. If the color is constant, use either OwoColorize::bg
or
a color-specific method, such as OwoColorize::on_yellow
, Read more
fn fg_rgb<const R: u8, const G: u8, const B: u8>(
&self
) -> FgColorDisplay<'_, CustomColor<R, G, B>, Self>
fn fg_rgb<const R: u8, const G: u8, const B: u8>(
&self
) -> FgColorDisplay<'_, CustomColor<R, G, B>, Self>
Set the foreground color to a specific RGB value.
fn bg_rgb<const R: u8, const G: u8, const B: u8>(
&self
) -> BgColorDisplay<'_, CustomColor<R, G, B>, Self>
fn bg_rgb<const R: u8, const G: u8, const B: u8>(
&self
) -> BgColorDisplay<'_, CustomColor<R, G, B>, Self>
Set the background color to a specific RGB value.
fn truecolor(&self, r: u8, g: u8, b: u8) -> FgDynColorDisplay<'_, Rgb, Self>
fn truecolor(&self, r: u8, g: u8, b: u8) -> FgDynColorDisplay<'_, Rgb, Self>
Sets the foreground color to an RGB value.
fn on_truecolor(&self, r: u8, g: u8, b: u8) -> BgDynColorDisplay<'_, Rgb, Self>
fn on_truecolor(&self, r: u8, g: u8, b: u8) -> BgDynColorDisplay<'_, Rgb, Self>
Sets the background color to an RGB value.
sourceimpl<T> WithSubscriber for T
impl<T> WithSubscriber for T
sourcefn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> where
S: Into<Dispatch>,
fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> where
S: Into<Dispatch>,
Attaches the provided Subscriber
to this type, returning a
WithDispatch
wrapper. Read more
sourcefn with_current_subscriber(self) -> WithDispatch<Self>
fn with_current_subscriber(self) -> WithDispatch<Self>
Attaches the current default Subscriber
to this type, returning a
WithDispatch
wrapper. Read more