🛈 Note: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem.

For the release documentation, please see docs.rs, instead.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
//! Spans represent periods of time in the execution of a program.
use core::num::NonZeroU64;

use crate::field::FieldSet;
use crate::parent::Parent;
use crate::{field, Metadata};

/// Identifies a span within the context of a collector.
///
/// They are generated by [collector]s for each span as it is created, by
/// the [`new_span`] trait method. See the documentation for that method for
/// more information on span ID generation.
///
/// [collector]: super::collect::Collect
/// [`new_span`]: super::collect::Collect::new_span
#[derive(Clone, Debug, PartialEq, Eq, Hash)]
pub struct Id(NonZeroU64);

/// Attributes provided to a collector describing a new span when it is
/// created.
#[derive(Debug)]
pub struct Attributes<'a> {
    metadata: &'static Metadata<'static>,
    values: &'a field::ValueSet<'a>,
    parent: Parent,
}

/// A set of fields recorded by a span.
#[derive(Debug)]
pub struct Record<'a> {
    values: &'a field::ValueSet<'a>,
}

/// Indicates what [the collector considers] the "current" span.
///
/// As collectors may not track a notion of a current span, this has three
/// possible states:
/// - "unknown", indicating that the collector does not track a current span,
/// - "none", indicating that the current context is known to not be in a span,
/// - "some", with the current span's [`Id`] and [`Metadata`].
///
/// [the collector considers]: super::collect::Collect::current_span
/// [`Metadata`]: super::metadata::Metadata
#[derive(Debug)]
pub struct Current {
    inner: CurrentInner,
}

#[derive(Debug)]
enum CurrentInner {
    Current {
        id: Id,
        metadata: &'static Metadata<'static>,
    },
    None,
    Unknown,
}

// ===== impl Span =====

impl Id {
    /// Constructs a new span ID from the given `u64`.
    ///
    /// <div class="example-wrap" style="display:inline-block">
    /// <pre class="ignore" style="white-space:normal;font:inherit;">
    /// <strong>Note</strong>: Span IDs must be greater than zero.</pre></div>
    ///
    /// # Panics
    /// - If the provided `u64` is 0.
    pub fn from_u64(u: u64) -> Self {
        Id(NonZeroU64::new(u).expect("span IDs must be > 0"))
    }

    /// Constructs a new span ID from the given `NonZeroU64`.
    ///
    /// Unlike [`Id::from_u64`](Self::from_u64), this will never panic.
    #[inline]
    pub const fn from_non_zero_u64(id: NonZeroU64) -> Self {
        Id(id)
    }

    // Allow `into` by-ref since we don't want to impl Copy for Id
    #[allow(clippy::wrong_self_convention)]
    /// Returns the span's ID as a `u64`.
    pub fn into_u64(&self) -> u64 {
        self.0.get()
    }

    // Allow `into` by-ref since we don't want to impl Copy for Id
    #[allow(clippy::wrong_self_convention)]
    /// Returns the span's ID as a `NonZeroU64`.
    #[inline]
    pub const fn into_non_zero_u64(&self) -> NonZeroU64 {
        self.0
    }
}

impl<'a> From<&'a Id> for Option<Id> {
    fn from(id: &'a Id) -> Self {
        Some(id.clone())
    }
}

// ===== impl Attributes =====

impl<'a> Attributes<'a> {
    /// Returns `Attributes` describing a new child span of the current span,
    /// with the provided metadata and values.
    pub fn new(metadata: &'static Metadata<'static>, values: &'a field::ValueSet<'a>) -> Self {
        Attributes {
            metadata,
            values,
            parent: Parent::Current,
        }
    }

    /// Returns `Attributes` describing a new span at the root of its own trace
    /// tree, with the provided metadata and values.
    pub fn new_root(metadata: &'static Metadata<'static>, values: &'a field::ValueSet<'a>) -> Self {
        Attributes {
            metadata,
            values,
            parent: Parent::Root,
        }
    }

    /// Returns `Attributes` describing a new child span of the specified
    /// parent span, with the provided metadata and values.
    pub fn child_of(
        parent: Id,
        metadata: &'static Metadata<'static>,
        values: &'a field::ValueSet<'a>,
    ) -> Self {
        Attributes {
            metadata,
            values,
            parent: Parent::Explicit(parent),
        }
    }

    /// Returns a reference to the new span's metadata.
    pub fn metadata(&self) -> &'static Metadata<'static> {
        self.metadata
    }

    /// Returns a reference to a `ValueSet` containing any values the new span
    /// was created with.
    pub fn values(&self) -> &field::ValueSet<'a> {
        self.values
    }

    /// Returns true if the new span should be a root.
    pub fn is_root(&self) -> bool {
        matches!(self.parent, Parent::Root)
    }

    /// Returns true if the new span'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 span's parent. Otherwise, if the current
    /// thread is _not_ inside a span, then the new span will be the root of its
    /// own trace tree.
    pub fn is_contextual(&self) -> bool {
        matches!(self.parent, Parent::Current)
    }

    /// Returns the new span's explicitly-specified parent, if there is one.
    ///
    /// Otherwise (if the new span 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,
        }
    }

    /// Records all the fields in this set of `Attributes` with the provided
    /// [Visitor].
    ///
    /// [visitor]: super::field::Visit
    pub fn record(&self, visitor: &mut dyn field::Visit) {
        self.values.record(visitor)
    }

    /// Returns `true` if this set of `Attributes` contains a value for the
    /// given `Field`.
    pub fn contains(&self, field: &field::Field) -> bool {
        self.values.contains(field)
    }

    /// Returns true if this set of `Attributes` contains _no_ values.
    pub fn is_empty(&self) -> bool {
        self.values.is_empty()
    }

    /// Returns the set of all [fields] defined by this span's [`Metadata`].
    ///
    /// Note that the [`FieldSet`] returned by this method includes *all* the
    /// fields declared by this span, not just those with values that are recorded
    /// as part of this set of `Attributes`. Other fields with values not present in
    /// this `Attributes`' value set may [record] values later.
    ///
    /// [fields]: crate::field
    /// [record]: Attributes::record()
    /// [`Metadata`]: crate::metadata::Metadata
    /// [`FieldSet`]: crate::field::FieldSet
    pub fn fields(&self) -> &FieldSet {
        self.values.field_set()
    }
}

// ===== impl Record =====

impl<'a> Record<'a> {
    /// Constructs a new `Record` from a `ValueSet`.
    pub fn new(values: &'a field::ValueSet<'a>) -> Self {
        Self { values }
    }

    /// Records all the fields in this `Record` with the provided [Visitor].
    ///
    /// [visitor]: super::field::Visit
    pub fn record(&self, visitor: &mut dyn field::Visit) {
        self.values.record(visitor)
    }

    /// Returns the number of fields that would be visited from this `Record`
    /// when [`Record::record()`] is called
    ///
    /// [`Record::record()`]: Record::record()
    pub fn len(&self) -> usize {
        self.values.len()
    }

    /// Returns `true` if this `Record` contains a value for the given `Field`.
    pub fn contains(&self, field: &field::Field) -> bool {
        self.values.contains(field)
    }

    /// Returns true if this `Record` contains _no_ values.
    pub fn is_empty(&self) -> bool {
        self.values.is_empty()
    }
}

// ===== impl Current =====

impl Current {
    /// Constructs a new `Current` that indicates the current context is a span
    /// with the given `id` and `metadata`.
    pub fn new(id: Id, metadata: &'static Metadata<'static>) -> Self {
        Self {
            inner: CurrentInner::Current { id, metadata },
        }
    }

    /// Constructs a new `Current` that indicates the current context is *not*
    /// in a span.
    pub fn none() -> Self {
        Self {
            inner: CurrentInner::None,
        }
    }

    /// Constructs a new `Current` that indicates the collector does not
    /// track a current span.
    pub fn unknown() -> Self {
        Self {
            inner: CurrentInner::Unknown,
        }
    }

    /// Returns `true` if the collector that constructed this `Current` tracks a
    /// current span.
    ///
    /// If this returns `true` and [`id`], [`metadata`], or [`into_inner`]
    /// return `None`, that indicates that we are currently known to *not* be
    /// inside a span. If this returns `false`, those methods will also return
    /// `None`, but in this case, that is because the collector does not keep
    /// track of the currently-entered span.
    ///
    /// [`id`]: Self::id
    /// [`metadata`]: Self::metadata
    /// [`into_inner`]: Self::into_inner
    pub fn is_known(&self) -> bool {
        !matches!(self.inner, CurrentInner::Unknown)
    }

    /// Consumes `self` and returns the span `Id` and `Metadata` of the current
    /// span, if one exists and is known.
    pub fn into_inner(self) -> Option<(Id, &'static Metadata<'static>)> {
        match self.inner {
            CurrentInner::Current { id, metadata } => Some((id, metadata)),
            _ => None,
        }
    }

    /// Borrows the `Id` of the current span, if one exists and is known.
    pub fn id(&self) -> Option<&Id> {
        match self.inner {
            CurrentInner::Current { ref id, .. } => Some(id),
            _ => None,
        }
    }

    /// Borrows the `Metadata` of the current span, if one exists and is known.
    pub fn metadata(&self) -> Option<&'static Metadata<'static>> {
        match self.inner {
            CurrentInner::Current { metadata, .. } => Some(metadata),
            _ => None,
        }
    }
}

impl<'a> From<&'a Current> for Option<&'a Id> {
    fn from(cur: &'a Current) -> Self {
        cur.id()
    }
}

impl<'a> From<&'a Current> for Option<Id> {
    fn from(cur: &'a Current) -> Self {
        cur.id().cloned()
    }
}

impl From<Current> for Option<Id> {
    fn from(cur: Current) -> Self {
        match cur.inner {
            CurrentInner::Current { id, .. } => Some(id),
            _ => None,
        }
    }
}

impl<'a> From<&'a Current> for Option<&'static Metadata<'static>> {
    fn from(cur: &'a Current) -> Self {
        cur.metadata()
    }
}