pub struct EnteredSpan { }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.
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.
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");
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. Since in_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(|| {
});
some_other_async_function(some_value).await;
}For instrumenting asynchronous code, tracing provides the Future::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 {
some_other_async_function().await;
}
.instrument(span)
.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() {
some_other_async_function().await;
}let span = span!(Level::INFO, "my_span");
let guard = span.enter();
drop(guard);
Guards need not be explicitly dropped:
fn my_function() -> String {
let span = trace_span!("my_function");
let _enter = span.enter();
my_other_function();
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();
info!("i'm in the span!");
}
info!("i'm outside the span!")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.
let my_span = span!(Level::TRACE, "my_span");
my_span.in_scope(|| {
trace!("i'm in 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");
let a_string = span.in_scope(hello_world);Returns a Field for the field with the given name, if one exists,
Returns true if this Span has a field for the given Field or field name.
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};
let span = trace_span!("my_span", greeting = "hello world", parting = field::Empty);
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;
let span = info_span!("doing_something", is_okay = true);
let _e = span.enter();
match do_something() {
Ok(something) => {
}
Err(_) => {
span.record("is_okay", false);
}
} Note: The fields associated with a span are part
of its Metadata.
The Metadata
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};
let span = trace_span!("my_span", greeting = "hello world", parting = field::Empty);
span.record("new_field", "interesting_value_you_really_need");
span.record("parting", "you will be remembered");Records all the fields in the provided ValueSet.
Returns true if this span was disabled by the subscriber and does not exist.
See also is_none.
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.
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.
§ExamplesSetting 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);Returns this span’s Id, if it is enabled.
Returns this span’s Metadata, if it is enabled.
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.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4