|
| 1 | +//! Define the ancestry of an event or span. |
| 2 | +//! |
| 3 | +//! See the documentation on the [`Ancestry`] enum for further details. |
| 4 | +
|
| 5 | +use tracing_core::{ |
| 6 | + span::{self, Attributes}, |
| 7 | + Event, |
| 8 | +}; |
| 9 | + |
| 10 | +/// The ancestry of an event or span. |
| 11 | +/// |
| 12 | +/// An event or span can have an explicitly assigned parent, or be an explicit root. Otherwise, |
| 13 | +/// an event or span may have a contextually assigned parent or in the final case will be a |
| 14 | +/// contextual root. |
| 15 | +#[derive(Debug, Eq, PartialEq)] |
| 16 | +pub enum Ancestry { |
| 17 | + /// The event or span has an explicitly assigned parent (created with `parent: span_id`) with |
| 18 | + /// the specified name. |
| 19 | + HasExplicitParent(String), |
| 20 | + /// The event or span is an explicitly defined root. It was created with `parent: None` and |
| 21 | + /// has no parent. |
| 22 | + IsExplicitRoot, |
| 23 | + /// The event or span has a contextually assigned parent with the specified name. Additionally, |
| 24 | + /// it has no explicitly assigned parent. |
| 25 | + HasContextualParent(String), |
| 26 | + /// The event or span is a contextual root. It has no contextual parent and also has no |
| 27 | + /// explicitly assigned parent. |
| 28 | + IsContextualRoot, |
| 29 | +} |
| 30 | + |
| 31 | +impl Ancestry { |
| 32 | + #[track_caller] |
| 33 | + pub(crate) fn check( |
| 34 | + &self, |
| 35 | + actual_ancestry: &Ancestry, |
| 36 | + ctx: impl std::fmt::Display, |
| 37 | + collector_name: &str, |
| 38 | + ) { |
| 39 | + let expected_description = |ancestry: &Ancestry| match ancestry { |
| 40 | + Self::IsExplicitRoot => "be an explicit root".to_string(), |
| 41 | + Self::HasExplicitParent(name) => format!("have an explicit parent with name='{name}'"), |
| 42 | + Self::IsContextualRoot => "be a contextual root".to_string(), |
| 43 | + Self::HasContextualParent(name) => { |
| 44 | + format!("have a contextual parent with name='{name}'") |
| 45 | + } |
| 46 | + }; |
| 47 | + |
| 48 | + let actual_description = |ancestry: &Ancestry| match ancestry { |
| 49 | + Self::IsExplicitRoot => "was actually an explicit root".to_string(), |
| 50 | + Self::HasExplicitParent(name) => { |
| 51 | + format!("actually has an explicit parent with name='{name}'") |
| 52 | + } |
| 53 | + Self::IsContextualRoot => "was actually a contextual root".to_string(), |
| 54 | + Self::HasContextualParent(name) => { |
| 55 | + format!("actually has a contextual parent with name='{name}'") |
| 56 | + } |
| 57 | + }; |
| 58 | + |
| 59 | + assert_eq!( |
| 60 | + self, |
| 61 | + actual_ancestry, |
| 62 | + "[{collector_name}] expected {ctx} to {expected_description}, but {actual_description}", |
| 63 | + expected_description = expected_description(self), |
| 64 | + actual_description = actual_description(actual_ancestry) |
| 65 | + ); |
| 66 | + } |
| 67 | +} |
| 68 | + |
| 69 | +pub(crate) trait HasAncestry { |
| 70 | + fn is_contextual(&self) -> bool; |
| 71 | + |
| 72 | + fn is_root(&self) -> bool; |
| 73 | + |
| 74 | + fn parent(&self) -> Option<&span::Id>; |
| 75 | +} |
| 76 | + |
| 77 | +impl HasAncestry for &Event<'_> { |
| 78 | + fn is_contextual(&self) -> bool { |
| 79 | + (self as &Event<'_>).is_contextual() |
| 80 | + } |
| 81 | + |
| 82 | + fn is_root(&self) -> bool { |
| 83 | + (self as &Event<'_>).is_root() |
| 84 | + } |
| 85 | + |
| 86 | + fn parent(&self) -> Option<&span::Id> { |
| 87 | + (self as &Event<'_>).parent() |
| 88 | + } |
| 89 | +} |
| 90 | + |
| 91 | +impl HasAncestry for &Attributes<'_> { |
| 92 | + fn is_contextual(&self) -> bool { |
| 93 | + (self as &Attributes<'_>).is_contextual() |
| 94 | + } |
| 95 | + |
| 96 | + fn is_root(&self) -> bool { |
| 97 | + (self as &Attributes<'_>).is_root() |
| 98 | + } |
| 99 | + |
| 100 | + fn parent(&self) -> Option<&span::Id> { |
| 101 | + (self as &Attributes<'_>).parent() |
| 102 | + } |
| 103 | +} |
| 104 | + |
| 105 | +/// Determines the ancestry of an actual span or event. |
| 106 | +/// |
| 107 | +/// The rules for determining the ancestry are as follows: |
| 108 | +/// |
| 109 | +/// +------------+--------------+-----------------+---------------------+ |
| 110 | +/// | Contextual | Current Span | Explicit Parent | Ancestry | |
| 111 | +/// +------------+--------------+-----------------+---------------------+ |
| 112 | +/// | Yes | Yes | - | HasContextualParent | |
| 113 | +/// | Yes | No | - | IsContextualRoot | |
| 114 | +/// | No | - | Yes | HasExplicitParent | |
| 115 | +/// | No | - | No | IsExplicitRoot | |
| 116 | +/// +------------+--------------+-----------------+---------------------+ |
| 117 | +pub(crate) fn get_ancestry( |
| 118 | + item: impl HasAncestry, |
| 119 | + lookup_current: impl FnOnce() -> Option<span::Id>, |
| 120 | + span_name: impl FnOnce(&span::Id) -> Option<&str>, |
| 121 | +) -> Ancestry { |
| 122 | + if item.is_contextual() { |
| 123 | + if let Some(parent_id) = lookup_current() { |
| 124 | + let contextual_parent_name = span_name(&parent_id).expect( |
| 125 | + "tracing-mock: contextual parent cannot \ |
| 126 | + be looked up by ID. Was it recorded correctly?", |
| 127 | + ); |
| 128 | + Ancestry::HasContextualParent(contextual_parent_name.to_string()) |
| 129 | + } else { |
| 130 | + Ancestry::IsContextualRoot |
| 131 | + } |
| 132 | + } else if item.is_root() { |
| 133 | + Ancestry::IsExplicitRoot |
| 134 | + } else { |
| 135 | + let parent_id = item.parent().expect( |
| 136 | + "tracing-mock: is_contextual=false is_root=false \ |
| 137 | + but no explicit parent found. This is a bug!", |
| 138 | + ); |
| 139 | + let explicit_parent_name = span_name(parent_id).expect( |
| 140 | + "tracing-mock: explicit parent cannot be looked \ |
| 141 | + up by ID. Is the provided Span ID valid: {parent_id}", |
| 142 | + ); |
| 143 | + Ancestry::HasExplicitParent(explicit_parent_name.to_string()) |
| 144 | + } |
| 145 | +} |
0 commit comments