diff options
Diffstat (limited to '')
-rw-r--r-- | vendor/tracing-core/src/event.rs | 128 |
1 files changed, 128 insertions, 0 deletions
diff --git a/vendor/tracing-core/src/event.rs b/vendor/tracing-core/src/event.rs new file mode 100644 index 000000000..6e2543762 --- /dev/null +++ b/vendor/tracing-core/src/event.rs @@ -0,0 +1,128 @@ +//! Events represent single points in time during the execution of a program. +use crate::parent::Parent; +use crate::span::Id; +use crate::{field, Metadata}; + +/// `Event`s represent single points in time where something occurred during the +/// execution of a program. +/// +/// An `Event` can be compared to a log record in unstructured logging, but with +/// two key differences: +/// - `Event`s exist _within the context of a [span]_. Unlike log lines, they +/// may be located within the trace tree, allowing visibility into the +/// _temporal_ context in which the event occurred, as well as the source +/// code location. +/// - Like spans, `Event`s have structured key-value data known as _[fields]_, +/// which may include textual message. In general, a majority of the data +/// associated with an event should be in the event's fields rather than in +/// the textual message, as the fields are more structured. +/// +/// [span]: super::span +/// [fields]: super::field +#[derive(Debug)] +pub struct Event<'a> { + fields: &'a field::ValueSet<'a>, + metadata: &'static Metadata<'static>, + parent: Parent, +} + +impl<'a> Event<'a> { + /// Constructs a new `Event` with the specified metadata and set of values, + /// and observes it with the current subscriber. + pub fn dispatch(metadata: &'static Metadata<'static>, fields: &'a field::ValueSet<'_>) { + let event = Event::new(metadata, fields); + crate::dispatcher::get_default(|current| { + current.event(&event); + }); + } + + /// Returns a new `Event` in the current span, with the specified metadata + /// and set of values. + #[inline] + pub fn new(metadata: &'static Metadata<'static>, fields: &'a field::ValueSet<'a>) -> Self { + Event { + fields, + metadata, + parent: Parent::Current, + } + } + + /// Returns a new `Event` as a child of the specified span, with the + /// provided metadata and set of values. + #[inline] + pub fn new_child_of( + parent: impl Into<Option<Id>>, + metadata: &'static Metadata<'static>, + fields: &'a field::ValueSet<'a>, + ) -> Self { + let parent = match parent.into() { + Some(p) => Parent::Explicit(p), + None => Parent::Root, + }; + Event { + fields, + metadata, + parent, + } + } + + /// Constructs a new `Event` with the specified metadata and set of values, + /// and observes it with the current subscriber and an explicit parent. + pub fn child_of( + parent: impl Into<Option<Id>>, + metadata: &'static Metadata<'static>, + fields: &'a field::ValueSet<'_>, + ) { + let event = Self::new_child_of(parent, metadata, fields); + crate::dispatcher::get_default(|current| { + current.event(&event); + }); + } + + /// Visits all the fields on this `Event` with the specified [visitor]. + /// + /// [visitor]: super::field::Visit + #[inline] + pub fn record(&self, visitor: &mut dyn field::Visit) { + self.fields.record(visitor); + } + + /// Returns an iterator over the set of values on this `Event`. + pub fn fields(&self) -> field::Iter { + self.fields.field_set().iter() + } + + /// Returns [metadata] describing this `Event`. + /// + /// [metadata]: super::Metadata + pub fn metadata(&self) -> &'static Metadata<'static> { + self.metadata + } + + /// Returns true if the new event should be a root. + pub fn is_root(&self) -> bool { + matches!(self.parent, Parent::Root) + } + + /// Returns true if the new event's parent should be determined based on the + /// current context. + /// + /// If this is true and the current thread is currently inside a span, then + /// that span should be the new event's parent. Otherwise, if the current + /// thread is _not_ inside a span, then the new event will be the root of its + /// own trace tree. + pub fn is_contextual(&self) -> bool { + matches!(self.parent, Parent::Current) + } + + /// Returns the new event's explicitly-specified parent, if there is one. + /// + /// Otherwise (if the new event is a root or is a child of the current span), + /// returns `None`. + pub fn parent(&self) -> Option<&Id> { + match self.parent { + Parent::Explicit(ref p) => Some(p), + _ => None, + } + } +} |