/// Constructs a span at the trace level. /// /// [Fields] and [attributes] are set using the same syntax as the [`span!`] /// macro. /// /// See [the top-level documentation][lib] for details on the syntax accepted by /// this macro. /// /// [lib]: crate#using-the-macros /// [attributes]: crate#configuring-attributes /// [Fields]: crate#recording-fields /// [`span!`]: crate::span! /// /// # Examples /// /// ```rust /// # use tracing::{trace_span, span, Level}; /// # fn main() { /// trace_span!("my_span"); /// // is equivalent to: /// span!(Level::TRACE, "my_span"); /// # } /// ``` /// /// ```rust /// # use tracing::{trace_span, span, Level}; /// # fn main() { /// let span = trace_span!("my span"); /// span.in_scope(|| { /// // do work inside the span... /// }); /// # } /// ``` #[macro_export]
macro_rules! trace_span {
(target: $target:expr, parent: $parent:expr, $name:expr, $($field:tt)*) => {
$crate::span!(
target: $target,
parent: $parent,
$crate::Level::TRACE,
$name,
$($field)*
)
};
(target: $target:expr, parent: $parent:expr, $name:expr) => {
$crate::trace_span!(target: $target, parent: $parent, $name,)
};
(parent: $parent:expr, $name:expr, $($field:tt)*) => {
$crate::span!(
target: module_path!(),
parent: $parent,
$crate::Level::TRACE,
$name,
$($field)*
)
};
(parent: $parent:expr, $name:expr) => {
$crate::trace_span!(parent: $parent, $name,)
};
(target: $target:expr, $name:expr, $($field:tt)*) => {
$crate::span!(
target: $target,
$crate::Level::TRACE,
$name,
$($field)*
)
};
(target: $target:expr, $name:expr) => {
$crate::trace_span!(target: $target, $name,)
};
($name:expr, $($field:tt)*) => {
$crate::span!(
target: module_path!(),
$crate::Level::TRACE,
$name,
$($field)*
)
};
($name:expr) => { $crate::trace_span!($name,) };
}
/// Constructs a span at the debug level. /// /// [Fields] and [attributes] are set using the same syntax as the [`span!`] /// macro. /// /// See [the top-level documentation][lib] for details on the syntax accepted by /// this macro. /// /// [lib]: crate#using-the-macros /// [attributes]: crate#configuring-attributes /// [Fields]: crate#recording-fields /// [`span!`]: crate::span! /// /// # Examples /// /// ```rust /// # use tracing::{debug_span, span, Level}; /// # fn main() { /// debug_span!("my_span"); /// // is equivalent to: /// span!(Level::DEBUG, "my_span"); /// # } /// ``` /// /// ```rust /// # use tracing::debug_span; /// # fn main() { /// let span = debug_span!("my span"); /// span.in_scope(|| { /// // do work inside the span... /// }); /// # } /// ``` #[macro_export]
macro_rules! debug_span {
(target: $target:expr, parent: $parent:expr, $name:expr, $($field:tt)*) => {
$crate::span!(
target: $target,
parent: $parent,
$crate::Level::DEBUG,
$name,
$($field)*
)
};
(target: $target:expr, parent: $parent:expr, $name:expr) => {
$crate::debug_span!(target: $target, parent: $parent, $name,)
};
(parent: $parent:expr, $name:expr, $($field:tt)*) => {
$crate::span!(
target: module_path!(),
parent: $parent,
$crate::Level::DEBUG,
$name,
$($field)*
)
};
(parent: $parent:expr, $name:expr) => {
$crate::debug_span!(parent: $parent, $name,)
};
(target: $target:expr, $name:expr, $($field:tt)*) => {
$crate::span!(
target: $target,
$crate::Level::DEBUG,
$name,
$($field)*
)
};
(target: $target:expr, $name:expr) => {
$crate::debug_span!(target: $target, $name,)
};
($name:expr, $($field:tt)*) => {
$crate::span!(
target: module_path!(),
$crate::Level::DEBUG,
$name,
$($field)*
)
};
($name:expr) => {$crate::debug_span!($name,)};
}
/// Constructs a span at the info level. /// /// [Fields] and [attributes] are set using the same syntax as the [`span!`] /// macro. /// /// See [the top-level documentation][lib] for details on the syntax accepted by /// this macro. /// /// [lib]: crate#using-the-macros /// [attributes]: crate#configuring-attributes /// [Fields]: crate#recording-fields /// [`span!`]: crate::span! /// /// # Examples /// /// ```rust /// # use tracing::{span, info_span, Level}; /// # fn main() { /// info_span!("my_span"); /// // is equivalent to: /// span!(Level::INFO, "my_span"); /// # } /// ``` /// /// ```rust /// # use tracing::info_span; /// # fn main() { /// let span = info_span!("my span"); /// span.in_scope(|| { /// // do work inside the span... /// }); /// # } /// ``` #[macro_export]
macro_rules! info_span {
(target: $target:expr, parent: $parent:expr, $name:expr, $($field:tt)*) => {
$crate::span!(
target: $target,
parent: $parent,
$crate::Level::INFO,
$name,
$($field)*
)
};
(target: $target:expr, parent: $parent:expr, $name:expr) => {
$crate::info_span!(target: $target, parent: $parent, $name,)
};
(parent: $parent:expr, $name:expr, $($field:tt)*) => {
$crate::span!(
target: module_path!(),
parent: $parent,
$crate::Level::INFO,
$name,
$($field)*
)
};
(parent: $parent:expr, $name:expr) => {
$crate::info_span!(parent: $parent, $name,)
};
(target: $target:expr, $name:expr, $($field:tt)*) => {
$crate::span!(
target: $target,
$crate::Level::INFO,
$name,
$($field)*
)
};
(target: $target:expr, $name:expr) => {
$crate::info_span!(target: $target, $name,)
};
($name:expr, $($field:tt)*) => {
$crate::span!(
target: module_path!(),
$crate::Level::INFO,
$name,
$($field)*
)
};
($name:expr) => {$crate::info_span!($name,)};
}
/// Constructs a span at the warn level. /// /// [Fields] and [attributes] are set using the same syntax as the [`span!`] /// macro. /// /// See [the top-level documentation][lib] for details on the syntax accepted by /// this macro. /// /// [lib]: crate#using-the-macros /// [attributes]: crate#configuring-attributes /// [Fields]: crate#recording-fields /// [`span!`]: crate::span! /// /// # Examples /// /// ```rust /// # use tracing::{warn_span, span, Level}; /// # fn main() { /// warn_span!("my_span"); /// // is equivalent to: /// span!(Level::WARN, "my_span"); /// # } /// ``` /// /// ```rust /// use tracing::warn_span; /// # fn main() { /// let span = warn_span!("my span"); /// span.in_scope(|| { /// // do work inside the span... /// }); /// # } /// ``` #[macro_export]
macro_rules! warn_span {
(target: $target:expr, parent: $parent:expr, $name:expr, $($field:tt)*) => {
$crate::span!(
target: $target,
parent: $parent,
$crate::Level::WARN,
$name,
$($field)*
)
};
(target: $target:expr, parent: $parent:expr, $name:expr) => {
$crate::warn_span!(target: $target, parent: $parent, $name,)
};
(parent: $parent:expr, $name:expr, $($field:tt)*) => {
$crate::span!(
target: module_path!(),
parent: $parent,
$crate::Level::WARN,
$name,
$($field)*
)
};
(parent: $parent:expr, $name:expr) => {
$crate::warn_span!(parent: $parent, $name,)
};
(target: $target:expr, $name:expr, $($field:tt)*) => {
$crate::span!(
target: $target,
$crate::Level::WARN,
$name,
$($field)*
)
};
(target: $target:expr, $name:expr) => {
$crate::warn_span!(target: $target, $name,)
};
($name:expr, $($field:tt)*) => {
$crate::span!(
target: module_path!(),
$crate::Level::WARN,
$name,
$($field)*
)
};
($name:expr) => {$crate::warn_span!($name,)};
} /// Constructs a span at the error level. /// /// [Fields] and [attributes] are set using the same syntax as the [`span!`] /// macro. /// /// See [the top-level documentation][lib] for details on the syntax accepted by /// this macro. /// /// [lib]: crate#using-the-macros /// [attributes]: crate#configuring-attributes /// [Fields]: crate#recording-fields /// [`span!`]: crate::span! /// /// # Examples /// /// ```rust /// # use tracing::{span, error_span, Level}; /// # fn main() { /// error_span!("my_span"); /// // is equivalent to: /// span!(Level::ERROR, "my_span"); /// # } /// ``` /// /// ```rust /// # use tracing::error_span; /// # fn main() { /// let span = error_span!("my span"); /// span.in_scope(|| { /// // do work inside the span... /// }); /// # } /// ``` #[macro_export]
macro_rules! error_span {
(target: $target:expr, parent: $parent:expr, $name:expr, $($field:tt)*) => {
$crate::span!(
target: $target,
parent: $parent,
$crate::Level::ERROR,
$name,
$($field)*
)
};
(target: $target:expr, parent: $parent:expr, $name:expr) => {
$crate::error_span!(target: $target, parent: $parent, $name,)
};
(parent: $parent:expr, $name:expr, $($field:tt)*) => {
$crate::span!(
target: module_path!(),
parent: $parent,
$crate::Level::ERROR,
$name,
$($field)*
)
};
(parent: $parent:expr, $name:expr) => {
$crate::error_span!(parent: $parent, $name,)
};
(target: $target:expr, $name:expr, $($field:tt)*) => {
$crate::span!(
target: $target,
$crate::Level::ERROR,
$name,
$($field)*
)
};
(target: $target:expr, $name:expr) => {
$crate::error_span!(target: $target, $name,)
};
($name:expr, $($field:tt)*) => {
$crate::span!(
target: module_path!(),
$crate::Level::ERROR,
$name,
$($field)*
)
};
($name:expr) => {$crate::error_span!($name,)};
}
/// Constructs a new `Event`. /// /// The event macro is invoked with a `Level` and up to 32 key-value fields. /// Optionally, a format string and arguments may follow the fields; this will /// be used to construct an implicit field named "message". /// /// See [the top-level documentation][lib] for details on the syntax accepted by /// this macro. /// /// [lib]: crate#using-the-macros /// /// # Examples /// /// ```rust /// use tracing::{event, Level}; /// /// # fn main() { /// let data = (42, "forty-two"); /// let private_data = "private"; /// let error = "a bad error"; /// /// event!(Level::ERROR, %error, "Received error"); /// event!( /// target: "app_events", /// Level::WARN, /// private_data, /// ?data, /// "App warning: {}", /// error /// ); /// event!(Level::INFO, the_answer = data.0); /// # } /// ``` /// // /// Note that *unlike `span!`*, `event!` requires a value for all fields. As // /// events are recorded immediately when the macro is invoked, there is no // /// opportunity for fields to be recorded later. A trailing comma on the final // /// field is valid. // /// // /// For example, the following does not compile: // /// ```rust,compile_fail // /// # use tracing::{Level, event}; // /// # fn main() { // /// event!(Level::INFO, foo = 5, bad_field, bar = "hello") // /// #} // /// ``` #[macro_export]
macro_rules! event {
(target: $target:expr, parent: $parent:expr, $lvl:expr, { $($fields:tt)* } )=> ({ use $crate::__macro_support::Callsite as _; static CALLSITE: $crate::callsite::DefaultCallsite = $crate::callsite2! {
name: $crate::__macro_support::concat!( "event ",
file!(), ":",
line!()
),
kind: $crate::metadata::Kind::EVENT,
target: $target,
level: $lvl,
fields: $($fields)*
};
let enabled = $crate::level_enabled!($lvl) && { let interest = CALLSITE.interest();
!interest.is_never() && $crate::__macro_support::__is_enabled(CALLSITE.metadata(), interest)
}; if enabled {
(|value_set: $crate::field::ValueSet| {
$crate::__tracing_log!(
$lvl,
CALLSITE,
&value_set
); let meta = CALLSITE.metadata(); // event with explicit parent
$crate::Event::child_of(
$parent,
meta,
&value_set
);
})($crate::valueset!(CALLSITE.metadata().fields(), $($fields)*));
} else {
$crate::__tracing_log!(
$lvl,
CALLSITE,
&$crate::valueset!(CALLSITE.metadata().fields(), $($fields)*)
);
}
});
/// Tests whether an event with the specified level and target would be enabled. /// /// This is similar to [`enabled!`], but queries the current subscriber specifically for /// an event, whereas [`enabled!`] queries for an event _or_ span. /// /// See the documentation for [`enabled!]` for more details on using this macro. /// See also [`span_enabled!`]. /// /// # Examples /// /// ```rust /// # use tracing::{event_enabled, Level}; /// if event_enabled!(target: "my_crate", Level::DEBUG) { /// // some expensive work... /// } /// // simpler /// if event_enabled!(Level::DEBUG) { /// // some expensive work... /// } /// // with fields /// if event_enabled!(Level::DEBUG, foo_field) { /// // some expensive work... /// } /// ``` /// /// [`enabled!`]: crate::enabled /// [`span_enabled!`]: crate::span_enabled #[macro_export]
macro_rules! event_enabled {
($($rest:tt)*)=> (
$crate::enabled!(kind: $crate::metadata::Kind::EVENT, $($rest)*)
)
}
/// Tests whether a span with the specified level and target would be enabled. /// /// This is similar to [`enabled!`], but queries the current subscriber specifically for /// an event, whereas [`enabled!`] queries for an event _or_ span. /// /// See the documentation for [`enabled!]` for more details on using this macro. /// See also [`span_enabled!`]. /// /// # Examples /// /// ```rust /// # use tracing::{span_enabled, Level}; /// if span_enabled!(target: "my_crate", Level::DEBUG) { /// // some expensive work... /// } /// // simpler /// if span_enabled!(Level::DEBUG) { /// // some expensive work... /// } /// // with fields /// if span_enabled!(Level::DEBUG, foo_field) { /// // some expensive work... /// } /// ``` /// /// [`enabled!`]: crate::enabled /// [`span_enabled!`]: crate::span_enabled #[macro_export]
macro_rules! span_enabled {
($($rest:tt)*)=> (
$crate::enabled!(kind: $crate::metadata::Kind::SPAN, $($rest)*)
)
}
/// Checks whether a span or event is [enabled] based on the provided [metadata]. /// /// [enabled]: crate::Subscriber::enabled /// [metadata]: crate::Metadata /// /// This macro is a specialized tool: it is intended to be used prior /// to an expensive computation required *just* for that event, but /// *cannot* be done as part of an argument to that event, such as /// when multiple events are emitted (e.g., iterating over a collection /// and emitting an event for each item). /// /// # Usage /// /// [Subscribers] can make filtering decisions based all the data included in a /// span or event's [`Metadata`]. This means that it is possible for `enabled!` /// to return a _false positive_ (indicating that something would be enabled /// when it actually would not be) or a _false negative_ (indicating that /// something would be disabled when it would actually be enabled). /// /// [Subscribers]: crate::subscriber::Subscriber /// [`Metadata`]: crate::metadata::Metadata /// /// This occurs when a subscriber is using a _more specific_ filter than the /// metadata provided to the `enabled!` macro. Some situations that can result /// in false positives or false negatives include: /// /// - If a subscriber is using a filter which may enable a span or event based /// on field names, but `enabled!` is invoked without listing field names, /// `enabled!` may return a false negative if a specific field name would /// cause the subscriber to enable something that would otherwise be disabled. /// - If a subscriber is using a filter which enables or disables specific events by /// file path and line number, a particular event may be enabled/disabled /// even if an `enabled!` invocation with the same level, target, and fields /// indicated otherwise. /// - The subscriber can choose to enable _only_ spans or _only_ events, which `enabled` /// will not reflect. /// /// `enabled!()` requires a [level](crate::Level) argument, an optional `target:` /// argument, and an optional set of field names. If the fields are not provided, /// they are considered to be unknown. `enabled!` attempts to match the /// syntax of `event!()` as closely as possible, which can be seen in the /// examples below. /// /// # Examples /// /// If the current subscriber is interested in recording `DEBUG`-level spans and /// events in the current file and module path, this will evaluate to true: /// ```rust /// use tracing::{enabled, Level}; /// /// if enabled!(Level::DEBUG) { /// // some expensive work... /// } /// ``` /// /// If the current subscriber is interested in recording spans and events /// in the current file and module path, with the target "my_crate", and at the /// level `DEBUG`, this will evaluate to true: /// ```rust /// # use tracing::{enabled, Level}; /// if enabled!(target: "my_crate", Level::DEBUG) { /// // some expensive work... /// } /// ``` /// /// If the current subscriber is interested in recording spans and events /// in the current file and module path, with the target "my_crate", at /// the level `DEBUG`, and with a field named "hello", this will evaluate /// to true: /// /// ```rust /// # use tracing::{enabled, Level}; /// if enabled!(target: "my_crate", Level::DEBUG, hello) { /// // some expensive work... /// } /// ``` /// /// # Alternatives /// /// `enabled!` queries subscribers with [`Metadata`] where /// [`is_event`] and [`is_span`] both return `false`. Alternatively, /// use [`event_enabled!`] or [`span_enabled!`] to ensure one of these /// returns true. /// /// /// [`Metadata`]: crate::Metadata /// [`is_event`]: crate::Metadata::is_event /// [`is_span`]: crate::Metadata::is_span /// [`enabled!`]: crate::enabled /// [`span_enabled!`]: crate::span_enabled #[macro_export]
macro_rules! enabled {
(kind: $kind:expr, target: $target:expr, $lvl:expr, { $($fields:tt)* } )=> ({ if $crate::level_enabled!($lvl) { use $crate::__macro_support::Callsite as _; static CALLSITE: $crate::callsite::DefaultCallsite = $crate::callsite2! {
name: $crate::__macro_support::concat!( "enabled ",
file!(), ":",
line!()
),
kind: $kind.hint(),
target: $target,
level: $lvl,
fields: $($fields)*
}; let interest = CALLSITE.interest(); if !interest.is_never() && $crate::__macro_support::__is_enabled(CALLSITE.metadata(), interest) { let meta = CALLSITE.metadata();
$crate::dispatcher::get_default(|current| current.enabled(meta))
} else { false
}
} else { false
}
}); // Just target and level
(kind: $kind:expr, target: $target:expr, $lvl:expr ) => (
$crate::enabled!(kind: $kind, target: $target, $lvl, { })
);
(target: $target:expr, $lvl:expr ) => (
$crate::enabled!(kind: $crate::metadata::Kind::HINT, target: $target, $lvl, { })
);
// Remainder is unparseable, but exists --- must be format args!
(@ { $(,)* $($out:expr),* } $($rest:tt)+) => {
$crate::fieldset!(@ { "message", $($out),*, })
};
Die Informationen auf dieser Webseite wurden
nach bestem Wissen sorgfältig zusammengestellt. Es wird jedoch weder Vollständigkeit, noch Richtigkeit,
noch Qualität der bereit gestellten Informationen zugesichert.
Bemerkung:
Die farbliche Syntaxdarstellung und die Messung sind noch experimentell.