| //! 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]: ../span |
| /// [fields]: ../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 { metadata, fields, 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 { metadata, fields, 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]: ../field/trait.Visit.html |
| #[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]: ../struct.Metadata.html |
| 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 { |
| match self.parent { |
| Parent::Root => true, |
| _ => false, |
| } |
| } |
| |
| /// 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 { |
| match self.parent { |
| Parent::Current => true, |
| _ => false, |
| } |
| } |
| |
| /// 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 false. |
| pub fn parent(&self) -> Option<&Id> { |
| match self.parent { |
| Parent::Explicit(ref p) => Some(p), |
| _ => None, |
| } |
| } |
| } |