1 //! Subscribers collect and record trace data.
2 use crate::{span, Event, LevelFilter, Metadata};
3 
4 use crate::stdlib::{
5     any::{Any, TypeId},
6     boxed::Box,
7     sync::Arc,
8 };
9 
10 /// Trait representing the functions required to collect trace data.
11 ///
12 /// Crates that provide implementations of methods for collecting or recording
13 /// trace data should implement the `Subscriber` interface. This trait is
14 /// intended to represent fundamental primitives for collecting trace events and
15 /// spans — other libraries may offer utility functions and types to make
16 /// subscriber implementations more modular or improve the ergonomics of writing
17 /// subscribers.
18 ///
19 /// A subscriber is responsible for the following:
20 /// - Registering new spans as they are created, and providing them with span
21 ///   IDs. Implicitly, this means the subscriber may determine the strategy for
22 ///   determining span equality.
23 /// - Recording the attachment of field values and follows-from annotations to
24 ///   spans.
25 /// - Filtering spans and events, and determining when those filters must be
26 ///   invalidated.
27 /// - Observing spans as they are entered, exited, and closed, and events as
28 ///   they occur.
29 ///
30 /// When a span is entered or exited, the subscriber is provided only with the
31 /// [ID] with which it tagged that span when it was created. This means
32 /// that it is up to the subscriber to determine whether and how span _data_ —
33 /// the fields and metadata describing the span — should be stored. The
34 /// [`new_span`] function is called when a new span is created, and at that
35 /// point, the subscriber _may_ choose to store the associated data if it will
36 /// be referenced again. However, if the data has already been recorded and will
37 /// not be needed by the implementations of `enter` and `exit`, the subscriber
38 /// may freely discard that data without allocating space to store it.
39 ///
40 /// ## Overriding default impls
41 ///
42 /// Some trait methods on `Subscriber` have default implementations, either in
43 /// order to reduce the surface area of implementing `Subscriber`, or for
44 /// backward-compatibility reasons. However, many subscribers will likely want
45 /// to override these default implementations.
46 ///
47 /// The following methods are likely of interest:
48 ///
49 /// - [`register_callsite`] is called once for each callsite from which a span
50 ///   event may originate, and returns an [`Interest`] value describing whether or
51 ///   not the subscriber wishes to see events or spans from that callsite. By
52 ///   default, it calls [`enabled`], and returns `Interest::always()` if
53 ///   `enabled` returns true, or `Interest::never()` if enabled returns false.
54 ///   However, if the subscriber's interest can change dynamically at runtime,
55 ///   it may want to override this function to return `Interest::sometimes()`.
56 ///   Additionally, subscribers which wish to perform a behaviour once for each
57 ///   callsite, such as allocating storage for data related to that callsite,
58 ///   can perform it in `register_callsite`.
59 /// - [`clone_span`] is called every time a span ID is cloned, and [`try_close`]
60 ///   is called when a span ID is dropped. By default, these functions do
61 ///   nothing. However, they can be used to implement reference counting for
62 ///   spans, allowing subscribers to free storage for span data and to determine
63 ///   when a span has _closed_ permanently (rather than being exited).
64 ///   Subscribers which store per-span data or which need to track span closures
65 ///   should override these functions together.
66 ///
67 /// [ID]: ../span/struct.Id.html
68 /// [`new_span`]: trait.Subscriber.html#method.new_span
69 /// [`register_callsite`]: trait.Subscriber.html#method.register_callsite
70 /// [`Interest`]: struct.Interest.html
71 /// [`enabled`]: trait.Subscriber.html#method.enabled
72 /// [`clone_span`]: trait.Subscriber.html#method.clone_span
73 /// [`try_close`]: trait.Subscriber.html#method.try_close
74 pub trait Subscriber: 'static {
75     // === Span registry methods ==============================================
76 
77     /// Registers a new callsite with this subscriber, returning whether or not
78     /// the subscriber is interested in being notified about the callsite.
79     ///
80     /// By default, this function assumes that the subscriber's [filter]
81     /// represents an unchanging view of its interest in the callsite. However,
82     /// if this is not the case, subscribers may override this function to
83     /// indicate different interests, or to implement behaviour that should run
84     /// once for every callsite.
85     ///
86     /// This function is guaranteed to be called at least once per callsite on
87     /// every active subscriber. The subscriber may store the keys to fields it
88     /// cares about in order to reduce the cost of accessing fields by name,
89     /// preallocate storage for that callsite, or perform any other actions it
90     /// wishes to perform once for each callsite.
91     ///
92     /// The subscriber should then return an [`Interest`], indicating
93     /// whether it is interested in being notified about that callsite in the
94     /// future. This may be `Always` indicating that the subscriber always
95     /// wishes to be notified about the callsite, and its filter need not be
96     /// re-evaluated; `Sometimes`, indicating that the subscriber may sometimes
97     /// care about the callsite but not always (such as when sampling), or
98     /// `Never`, indicating that the subscriber never wishes to be notified about
99     /// that callsite. If all active subscribers return `Never`, a callsite will
100     /// never be enabled unless a new subscriber expresses interest in it.
101     ///
102     /// `Subscriber`s which require their filters to be run every time an event
103     /// occurs or a span is entered/exited should return `Interest::sometimes`.
104     /// If a subscriber returns `Interest::sometimes`, then its [`enabled`] method
105     /// will be called every time an event or span is created from that callsite.
106     ///
107     /// For example, suppose a sampling subscriber is implemented by
108     /// incrementing a counter every time `enabled` is called and only returning
109     /// `true` when the counter is divisible by a specified sampling rate. If
110     /// that subscriber returns `Interest::always` from `register_callsite`, then
111     /// the filter will not be re-evaluated once it has been applied to a given
112     /// set of metadata. Thus, the counter will not be incremented, and the span
113     /// or event that corresponds to the metadata will never be `enabled`.
114     ///
115     /// `Subscriber`s that need to change their filters occasionally should call
116     /// [`rebuild_interest_cache`] to re-evaluate `register_callsite` for all
117     /// callsites.
118     ///
119     /// Similarly, if a `Subscriber` has a filtering strategy that can be
120     /// changed dynamically at runtime, it would need to re-evaluate that filter
121     /// if the cached results have changed.
122     ///
123     /// A subscriber which manages fanout to multiple other subscribers
124     /// should proxy this decision to all of its child subscribers,
125     /// returning `Interest::never` only if _all_ such children return
126     /// `Interest::never`. If the set of subscribers to which spans are
127     /// broadcast may change dynamically, the subscriber should also never
128     /// return `Interest::Never`, as a new subscriber may be added that _is_
129     /// interested.
130     ///
131     /// # Notes
132     /// This function may be called again when a new subscriber is created or
133     /// when the registry is invalidated.
134     ///
135     /// If a subscriber returns `Interest::never` for a particular callsite, it
136     /// _may_ still see spans and events originating from that callsite, if
137     /// another subscriber expressed interest in it.
138     ///
139     /// [filter]: #method.enabled
140     /// [metadata]: ../metadata/struct.Metadata.html
141     /// [`Interest`]: struct.Interest.html
142     /// [`enabled`]: #method.enabled
143     /// [`rebuild_interest_cache`]: ../callsite/fn.rebuild_interest_cache.html
register_callsite(&self, metadata: &'static Metadata<'static>) -> Interest144     fn register_callsite(&self, metadata: &'static Metadata<'static>) -> Interest {
145         if self.enabled(metadata) {
146             Interest::always()
147         } else {
148             Interest::never()
149         }
150     }
151 
152     /// Returns true if a span or event with the specified [metadata] would be
153     /// recorded.
154     ///
155     /// By default, it is assumed that this filter needs only be evaluated once
156     /// for each callsite, so it is called by [`register_callsite`] when each
157     /// callsite is registered. The result is used to determine if the subscriber
158     /// is always [interested] or never interested in that callsite. This is intended
159     /// primarily as an optimization, so that expensive filters (such as those
160     /// involving string search, et cetera) need not be re-evaluated.
161     ///
162     /// However, if the subscriber's interest in a particular span or event may
163     /// change, or depends on contexts only determined dynamically at runtime,
164     /// then the `register_callsite` method should be overridden to return
165     /// [`Interest::sometimes`]. In that case, this function will be called every
166     /// time that span or event occurs.
167     ///
168     /// [metadata]: ../metadata/struct.Metadata.html
169     /// [interested]: struct.Interest.html
170     /// [`Interest::sometimes`]: struct.Interest.html#method.sometimes
171     /// [`register_callsite`]: #method.register_callsite
enabled(&self, metadata: &Metadata<'_>) -> bool172     fn enabled(&self, metadata: &Metadata<'_>) -> bool;
173 
174     /// Returns the highest [verbosity level][level] that this `Subscriber` will
175     /// enable, or `None`, if the subscriber does not implement level-based
176     /// filtering or chooses not to implement this method.
177     ///
178     /// If this method returns a [`Level`][level], it will be used as a hint to
179     /// determine the most verbose level that will be enabled. This will allow
180     /// spans and events which are more verbose than that level to be skipped
181     /// more efficiently. Subscribers which perform filtering are strongly
182     /// encouraged to provide an implementation of this method.
183     ///
184     /// If the maximum level the subscriber will enable can change over the
185     /// course of its lifetime, it is free to return a different value from
186     /// multiple invocations of this method. However, note that changes in the
187     /// maximum level will **only** be reflected after the callsite [`Interest`]
188     /// cache is rebuilt, by calling the [`callsite::rebuild_interest_cache`][rebuild]
189     /// function. Therefore, if the subscriber will change the value returned by
190     /// this method, it is responsible for ensuring that
191     /// [`rebuild_interest_cache`][rebuild] is called after the value of the max
192     /// level changes.
193     ///
194     /// [level]: ../struct.Level.html
195     /// [`Interest`]: struct.Interest.html
196     /// [rebuild]: ../callsite/fn.rebuild_interest_cache.html
max_level_hint(&self) -> Option<LevelFilter>197     fn max_level_hint(&self) -> Option<LevelFilter> {
198         None
199     }
200 
201     /// Visit the construction of a new span, returning a new [span ID] for the
202     /// span being constructed.
203     ///
204     /// The provided [`Attributes`] contains any field values that were provided
205     /// when the span was created. The subscriber may pass a [visitor] to the
206     /// `Attributes`' [`record` method] to record these values.
207     ///
208     /// IDs are used to uniquely identify spans and events within the context of a
209     /// subscriber, so span equality will be based on the returned ID. Thus, if
210     /// the subscriber wishes for all spans with the same metadata to be
211     /// considered equal, it should return the same ID every time it is given a
212     /// particular set of metadata. Similarly, if it wishes for two separate
213     /// instances of a span with the same metadata to *not* be equal, it should
214     /// return a distinct ID every time this function is called, regardless of
215     /// the metadata.
216     ///
217     /// Note that the subscriber is free to assign span IDs based on whatever
218     /// scheme it sees fit. Any guarantees about uniqueness, ordering, or ID
219     /// reuse are left up to the subscriber implementation to determine.
220     ///
221     /// [span ID]: ../span/struct.Id.html
222     /// [`Attributes`]: ../span/struct.Attributes.html
223     /// [visitor]: ../field/trait.Visit.html
224     /// [`record` method]: ../span/struct.Attributes.html#method.record
new_span(&self, span: &span::Attributes<'_>) -> span::Id225     fn new_span(&self, span: &span::Attributes<'_>) -> span::Id;
226 
227     // === Notification methods ===============================================
228 
229     /// Record a set of values on a span.
230     ///
231     /// This method will be invoked when value is recorded on a span.
232     /// Recording multiple values for the same field is possible,
233     /// but the actual behaviour is defined by the subscriber implementation.
234     ///
235     /// Keep in mind that a span might not provide a value
236     /// for each field it declares.
237     ///
238     /// The subscriber is expected to provide a [visitor] to the `Record`'s
239     /// [`record` method] in order to record the added values.
240     ///
241     /// # Example
242     ///  "foo = 3" will be recorded when [`record`] is called on the
243     /// `Attributes` passed to `new_span`.
244     /// Since values are not provided for the `bar` and `baz` fields,
245     /// the span's `Metadata` will indicate that it _has_ those fields,
246     /// but values for them won't be recorded at this time.
247     ///
248     /// ```rust,ignore
249     /// #[macro_use]
250     /// extern crate tracing;
251     ///
252     /// let mut span = span!("my_span", foo = 3, bar, baz);
253     ///
254     /// // `Subscriber::record` will be called with a `Record`
255     /// // containing "bar = false"
256     /// span.record("bar", &false);
257     ///
258     /// // `Subscriber::record` will be called with a `Record`
259     /// // containing "baz = "a string""
260     /// span.record("baz", &"a string");
261     /// ```
262     ///
263     /// [visitor]: ../field/trait.Visit.html
264     /// [`record`]: ../span/struct.Attributes.html#method.record
265     /// [`record` method]: ../span/struct.Record.html#method.record
record(&self, span: &span::Id, values: &span::Record<'_>)266     fn record(&self, span: &span::Id, values: &span::Record<'_>);
267 
268     /// Adds an indication that `span` follows from the span with the id
269     /// `follows`.
270     ///
271     /// This relationship differs somewhat from the parent-child relationship: a
272     /// span may have any number of prior spans, rather than a single one; and
273     /// spans are not considered to be executing _inside_ of the spans they
274     /// follow from. This means that a span may close even if subsequent spans
275     /// that follow from it are still open, and time spent inside of a
276     /// subsequent span should not be included in the time its precedents were
277     /// executing. This is used to model causal relationships such as when a
278     /// single future spawns several related background tasks, et cetera.
279     ///
280     /// If the subscriber has spans corresponding to the given IDs, it should
281     /// record this relationship in whatever way it deems necessary. Otherwise,
282     /// if one or both of the given span IDs do not correspond to spans that the
283     /// subscriber knows about, or if a cyclical relationship would be created
284     /// (i.e., some span _a_ which proceeds some other span _b_ may not also
285     /// follow from _b_), it may silently do nothing.
record_follows_from(&self, span: &span::Id, follows: &span::Id)286     fn record_follows_from(&self, span: &span::Id, follows: &span::Id);
287 
288     /// Records that an [`Event`] has occurred.
289     ///
290     /// This method will be invoked when an Event is constructed by
291     /// the `Event`'s [`dispatch` method]. For example, this happens internally
292     /// when an event macro from `tracing` is called.
293     ///
294     /// The key difference between this method and `record` is that `record` is
295     /// called when a value is recorded for a field defined by a span,
296     /// while `event` is called when a new event occurs.
297     ///
298     /// The provided `Event` struct contains any field values attached to the
299     /// event. The subscriber may pass a [visitor] to the `Event`'s
300     /// [`record` method] to record these values.
301     ///
302     /// [`Event`]: ../event/struct.Event.html
303     /// [visitor]: ../field/trait.Visit.html
304     /// [`record` method]: ../event/struct.Event.html#method.record
305     /// [`dispatch` method]: ../event/struct.Event.html#method.dispatch
event(&self, event: &Event<'_>)306     fn event(&self, event: &Event<'_>);
307 
308     /// Records that a span has been entered.
309     ///
310     /// When entering a span, this method is called to notify the subscriber
311     /// that the span has been entered. The subscriber is provided with the
312     /// [span ID] of the entered span, and should update any internal state
313     /// tracking the current span accordingly.
314     ///
315     /// [span ID]: ../span/struct.Id.html
enter(&self, span: &span::Id)316     fn enter(&self, span: &span::Id);
317 
318     /// Records that a span has been exited.
319     ///
320     /// When exiting a span, this method is called to notify the subscriber
321     /// that the span has been exited. The subscriber is provided with the
322     /// [span ID] of the exited span, and should update any internal state
323     /// tracking the current span accordingly.
324     ///
325     /// Exiting a span does not imply that the span will not be re-entered.
326     ///
327     /// [span ID]: ../span/struct.Id.html
exit(&self, span: &span::Id)328     fn exit(&self, span: &span::Id);
329 
330     /// Notifies the subscriber that a [span ID] has been cloned.
331     ///
332     /// This function is guaranteed to only be called with span IDs that were
333     /// returned by this subscriber's `new_span` function.
334     ///
335     /// Note that the default implementation of this function this is just the
336     /// identity function, passing through the identifier. However, it can be
337     /// used in conjunction with [`try_close`] to track the number of handles
338     /// capable of `enter`ing a span. When all the handles have been dropped
339     /// (i.e., `try_close` has been called one more time than `clone_span` for a
340     /// given ID), the subscriber may assume that the span will not be entered
341     /// again. It is then free to deallocate storage for data associated with
342     /// that span, write data from that span to IO, and so on.
343     ///
344     /// For more unsafe situations, however, if `id` is itself a pointer of some
345     /// kind this can be used as a hook to "clone" the pointer, depending on
346     /// what that means for the specified pointer.
347     ///
348     /// [span ID]: ../span/struct.Id.html
349     /// [`try_close`]: trait.Subscriber.html#method.try_close
clone_span(&self, id: &span::Id) -> span::Id350     fn clone_span(&self, id: &span::Id) -> span::Id {
351         id.clone()
352     }
353 
354     /// **This method is deprecated.**
355     ///
356     /// Using `drop_span` may result in subscribers composed using
357     /// `tracing-subscriber` crate's `Layer` trait from observing close events.
358     /// Use [`try_close`] instead.
359     ///
360     /// The default implementation of this function does nothing.
361     ///
362     /// [`try_close`]: trait.Subscriber.html#method.try_close
363     #[deprecated(since = "0.1.2", note = "use `Subscriber::try_close` instead")]
drop_span(&self, _id: span::Id)364     fn drop_span(&self, _id: span::Id) {}
365 
366     /// Notifies the subscriber that a [span ID] has been dropped, and returns
367     /// `true` if there are now 0 IDs that refer to that span.
368     ///
369     /// Higher-level libraries providing functionality for composing multiple
370     /// subscriber implementations may use this return value to notify any
371     /// "layered" subscribers that this subscriber considers the span closed.
372     ///
373     /// The default implementation of this method calls the subscriber's
374     /// [`drop_span`] method and returns `false`. This means that, unless the
375     /// subscriber overrides the default implementation, close notifications
376     /// will never be sent to any layered subscribers. In general, if the
377     /// subscriber tracks reference counts, this method should be implemented,
378     /// rather than `drop_span`.
379     ///
380     /// This function is guaranteed to only be called with span IDs that were
381     /// returned by this subscriber's `new_span` function.
382     ///
383     /// It's guaranteed that if this function has been called once more than the
384     /// number of times `clone_span` was called with the same `id`, then no more
385     /// handles that can enter the span with that `id` exist. This means that it
386     /// can be used in conjunction with [`clone_span`] to track the number of
387     /// handles capable of `enter`ing a span. When all the handles have been
388     /// dropped (i.e., `try_close` has been called one more time than
389     /// `clone_span` for a given ID), the subscriber may assume that the span
390     /// will not be entered again, and should return `true`. It is then free to
391     /// deallocate storage for data associated with that span, write data from
392     /// that span to IO, and so on.
393     ///
394     /// **Note**: since this function is called when spans are dropped,
395     /// implementations should ensure that they are unwind-safe. Panicking from
396     /// inside of a `try_close` function may cause a double panic, if the span
397     /// was dropped due to a thread unwinding.
398     ///
399     /// [span ID]: ../span/struct.Id.html
400     /// [`clone_span`]: trait.Subscriber.html#method.clone_span
401     /// [`drop_span`]: trait.Subscriber.html#method.drop_span
try_close(&self, id: span::Id) -> bool402     fn try_close(&self, id: span::Id) -> bool {
403         #[allow(deprecated)]
404         self.drop_span(id);
405         false
406     }
407 
408     /// Returns a type representing this subscriber's view of the current span.
409     ///
410     /// If subscribers track a current span, they should override this function
411     /// to return [`Current::new`] if the thread from which this method is
412     /// called is inside a span, or [`Current::none`] if the thread is not
413     /// inside a span.
414     ///
415     /// By default, this returns a value indicating that the subscriber
416     /// does **not** track what span is current. If the subscriber does not
417     /// implement a current span, it should not override this method.
418     ///
419     /// [`Current::new`]: ../span/struct.Current.html#tymethod.new
420     /// [`Current::none`]: ../span/struct.Current.html#tymethod.none
current_span(&self) -> span::Current421     fn current_span(&self) -> span::Current {
422         span::Current::unknown()
423     }
424 
425     // === Downcasting methods ================================================
426 
427     /// If `self` is the same type as the provided `TypeId`, returns an untyped
428     /// `*const` pointer to that type. Otherwise, returns `None`.
429     ///
430     /// If you wish to downcast a `Subscriber`, it is strongly advised to use
431     /// the safe API provided by [`downcast_ref`] instead.
432     ///
433     /// This API is required for `downcast_raw` to be a trait method; a method
434     /// signature like [`downcast_ref`] (with a generic type parameter) is not
435     /// object-safe, and thus cannot be a trait method for `Subscriber`. This
436     /// means that if we only exposed `downcast_ref`, `Subscriber`
437     /// implementations could not override the downcasting behavior
438     ///
439     /// This method may be overridden by "fan out" or "chained" subscriber
440     /// implementations which consist of multiple composed types. Such
441     /// subscribers might allow `downcast_raw` by returning references to those
442     /// component if they contain components with the given `TypeId`.
443     ///
444     /// # Safety
445     ///
446     /// The [`downcast_ref`] method expects that the pointer returned by
447     /// `downcast_raw` is non-null and points to a valid instance of the type
448     /// with the provided `TypeId`. Failure to ensure this will result in
449     /// undefined behaviour, so implementing `downcast_raw` is unsafe.
450     ///
451     /// [`downcast_ref`]: #method.downcast_ref
downcast_raw(&self, id: TypeId) -> Option<*const ()>452     unsafe fn downcast_raw(&self, id: TypeId) -> Option<*const ()> {
453         if id == TypeId::of::<Self>() {
454             Some(self as *const Self as *const ())
455         } else {
456             None
457         }
458     }
459 }
460 
461 impl dyn Subscriber {
462     /// Returns `true` if this `Subscriber` is the same type as `T`.
is<T: Any>(&self) -> bool463     pub fn is<T: Any>(&self) -> bool {
464         self.downcast_ref::<T>().is_some()
465     }
466 
467     /// Returns some reference to this `Subscriber` value if it is of type `T`,
468     /// or `None` if it isn't.
downcast_ref<T: Any>(&self) -> Option<&T>469     pub fn downcast_ref<T: Any>(&self) -> Option<&T> {
470         unsafe {
471             let raw = self.downcast_raw(TypeId::of::<T>())?;
472             if raw.is_null() {
473                 None
474             } else {
475                 Some(&*(raw as *const _))
476             }
477         }
478     }
479 }
480 
481 /// Indicates a [`Subscriber`]'s interest in a particular callsite.
482 ///
483 /// `Subscriber`s return an `Interest` from their [`register_callsite`] methods
484 /// in order to determine whether that span should be enabled or disabled.
485 ///
486 /// [`Subscriber`]: ../trait.Subscriber.html
487 /// [`register_callsite`]: ../trait.Subscriber.html#method.register_callsite
488 #[derive(Clone, Debug)]
489 pub struct Interest(InterestKind);
490 
491 #[derive(Copy, Clone, Debug, Eq, PartialEq, Ord, PartialOrd)]
492 enum InterestKind {
493     Never = 0,
494     Sometimes = 1,
495     Always = 2,
496 }
497 
498 impl Interest {
499     /// Returns an `Interest` indicating that the subscriber is never interested
500     /// in being notified about a callsite.
501     ///
502     /// If all active subscribers are `never()` interested in a callsite, it will
503     /// be completely disabled unless a new subscriber becomes active.
504     #[inline]
never() -> Self505     pub fn never() -> Self {
506         Interest(InterestKind::Never)
507     }
508 
509     /// Returns an `Interest` indicating the subscriber is sometimes interested
510     /// in being notified about a callsite.
511     ///
512     /// If all active subscribers are `sometimes` or `never` interested in a
513     /// callsite, the currently active subscriber will be asked to filter that
514     /// callsite every time it creates a span. This will be the case until a new
515     /// subscriber expresses that it is `always` interested in the callsite.
516     #[inline]
sometimes() -> Self517     pub fn sometimes() -> Self {
518         Interest(InterestKind::Sometimes)
519     }
520 
521     /// Returns an `Interest` indicating the subscriber is always interested in
522     /// being notified about a callsite.
523     ///
524     /// If any subscriber expresses that it is `always()` interested in a given
525     /// callsite, then the callsite will always be enabled.
526     #[inline]
always() -> Self527     pub fn always() -> Self {
528         Interest(InterestKind::Always)
529     }
530 
531     /// Returns `true` if the subscriber is never interested in being notified
532     /// about this callsite.
533     #[inline]
is_never(&self) -> bool534     pub fn is_never(&self) -> bool {
535         matches!(self.0, InterestKind::Never)
536     }
537 
538     /// Returns `true` if the subscriber is sometimes interested in being notified
539     /// about this callsite.
540     #[inline]
is_sometimes(&self) -> bool541     pub fn is_sometimes(&self) -> bool {
542         matches!(self.0, InterestKind::Sometimes)
543     }
544 
545     /// Returns `true` if the subscriber is always interested in being notified
546     /// about this callsite.
547     #[inline]
is_always(&self) -> bool548     pub fn is_always(&self) -> bool {
549         matches!(self.0, InterestKind::Always)
550     }
551 
552     /// Returns the common interest between these two Interests.
553     ///
554     /// If both interests are the same, this propagates that interest.
555     /// Otherwise, if they differ, the result must always be
556     /// `Interest::sometimes` --- if the two subscribers differ in opinion, we
557     /// will have to ask the current subscriber what it thinks, no matter what.
and(self, rhs: Interest) -> Self558     pub(crate) fn and(self, rhs: Interest) -> Self {
559         if self.0 == rhs.0 {
560             self
561         } else {
562             Interest::sometimes()
563         }
564     }
565 }
566 
567 /// A no-op [`Subscriber`].
568 ///
569 /// [`NoSubscriber`] implements the [`Subscriber`] trait by never being enabled,
570 /// never being interested in any callsite, and dropping all spans and events.
571 #[derive(Debug, Copy, Clone)]
572 pub struct NoSubscriber(());
573 
574 impl Default for NoSubscriber {
default() -> Self575     fn default() -> Self {
576         NoSubscriber(())
577     }
578 }
579 
580 impl Subscriber for NoSubscriber {
581     #[inline]
register_callsite(&self, _: &'static Metadata<'static>) -> Interest582     fn register_callsite(&self, _: &'static Metadata<'static>) -> Interest {
583         Interest::never()
584     }
585 
new_span(&self, _: &span::Attributes<'_>) -> span::Id586     fn new_span(&self, _: &span::Attributes<'_>) -> span::Id {
587         span::Id::from_u64(0xDEAD)
588     }
589 
event(&self, _event: &Event<'_>)590     fn event(&self, _event: &Event<'_>) {}
591 
record(&self, _span: &span::Id, _values: &span::Record<'_>)592     fn record(&self, _span: &span::Id, _values: &span::Record<'_>) {}
593 
record_follows_from(&self, _span: &span::Id, _follows: &span::Id)594     fn record_follows_from(&self, _span: &span::Id, _follows: &span::Id) {}
595 
596     #[inline]
enabled(&self, _metadata: &Metadata<'_>) -> bool597     fn enabled(&self, _metadata: &Metadata<'_>) -> bool {
598         false
599     }
600 
enter(&self, _span: &span::Id)601     fn enter(&self, _span: &span::Id) {}
exit(&self, _span: &span::Id)602     fn exit(&self, _span: &span::Id) {}
603 }
604 
605 impl Subscriber for Box<dyn Subscriber + Send + Sync + 'static> {
606     #[inline]
register_callsite(&self, metadata: &'static Metadata<'static>) -> Interest607     fn register_callsite(&self, metadata: &'static Metadata<'static>) -> Interest {
608         self.as_ref().register_callsite(metadata)
609     }
610 
611     #[inline]
enabled(&self, metadata: &Metadata<'_>) -> bool612     fn enabled(&self, metadata: &Metadata<'_>) -> bool {
613         self.as_ref().enabled(metadata)
614     }
615 
616     #[inline]
max_level_hint(&self) -> Option<LevelFilter>617     fn max_level_hint(&self) -> Option<LevelFilter> {
618         self.as_ref().max_level_hint()
619     }
620 
621     #[inline]
new_span(&self, span: &span::Attributes<'_>) -> span::Id622     fn new_span(&self, span: &span::Attributes<'_>) -> span::Id {
623         self.as_ref().new_span(span)
624     }
625 
626     #[inline]
record(&self, span: &span::Id, values: &span::Record<'_>)627     fn record(&self, span: &span::Id, values: &span::Record<'_>) {
628         self.as_ref().record(span, values)
629     }
630 
631     #[inline]
record_follows_from(&self, span: &span::Id, follows: &span::Id)632     fn record_follows_from(&self, span: &span::Id, follows: &span::Id) {
633         self.as_ref().record_follows_from(span, follows)
634     }
635 
636     #[inline]
event(&self, event: &Event<'_>)637     fn event(&self, event: &Event<'_>) {
638         self.as_ref().event(event)
639     }
640 
641     #[inline]
enter(&self, span: &span::Id)642     fn enter(&self, span: &span::Id) {
643         self.as_ref().enter(span)
644     }
645 
646     #[inline]
exit(&self, span: &span::Id)647     fn exit(&self, span: &span::Id) {
648         self.as_ref().exit(span)
649     }
650 
651     #[inline]
clone_span(&self, id: &span::Id) -> span::Id652     fn clone_span(&self, id: &span::Id) -> span::Id {
653         self.as_ref().clone_span(id)
654     }
655 
656     #[inline]
try_close(&self, id: span::Id) -> bool657     fn try_close(&self, id: span::Id) -> bool {
658         self.as_ref().try_close(id)
659     }
660 
661     #[inline]
662     #[allow(deprecated)]
drop_span(&self, id: span::Id)663     fn drop_span(&self, id: span::Id) {
664         self.as_ref().try_close(id);
665     }
666 
667     #[inline]
current_span(&self) -> span::Current668     fn current_span(&self) -> span::Current {
669         self.as_ref().current_span()
670     }
671 
672     #[inline]
downcast_raw(&self, id: TypeId) -> Option<*const ()>673     unsafe fn downcast_raw(&self, id: TypeId) -> Option<*const ()> {
674         if id == TypeId::of::<Self>() {
675             return Some(self as *const Self as *const _);
676         }
677 
678         self.as_ref().downcast_raw(id)
679     }
680 }
681 
682 impl Subscriber for Arc<dyn Subscriber + Send + Sync + 'static> {
683     #[inline]
register_callsite(&self, metadata: &'static Metadata<'static>) -> Interest684     fn register_callsite(&self, metadata: &'static Metadata<'static>) -> Interest {
685         self.as_ref().register_callsite(metadata)
686     }
687 
688     #[inline]
enabled(&self, metadata: &Metadata<'_>) -> bool689     fn enabled(&self, metadata: &Metadata<'_>) -> bool {
690         self.as_ref().enabled(metadata)
691     }
692 
693     #[inline]
max_level_hint(&self) -> Option<LevelFilter>694     fn max_level_hint(&self) -> Option<LevelFilter> {
695         self.as_ref().max_level_hint()
696     }
697 
698     #[inline]
new_span(&self, span: &span::Attributes<'_>) -> span::Id699     fn new_span(&self, span: &span::Attributes<'_>) -> span::Id {
700         self.as_ref().new_span(span)
701     }
702 
703     #[inline]
record(&self, span: &span::Id, values: &span::Record<'_>)704     fn record(&self, span: &span::Id, values: &span::Record<'_>) {
705         self.as_ref().record(span, values)
706     }
707 
708     #[inline]
record_follows_from(&self, span: &span::Id, follows: &span::Id)709     fn record_follows_from(&self, span: &span::Id, follows: &span::Id) {
710         self.as_ref().record_follows_from(span, follows)
711     }
712 
713     #[inline]
event(&self, event: &Event<'_>)714     fn event(&self, event: &Event<'_>) {
715         self.as_ref().event(event)
716     }
717 
718     #[inline]
enter(&self, span: &span::Id)719     fn enter(&self, span: &span::Id) {
720         self.as_ref().enter(span)
721     }
722 
723     #[inline]
exit(&self, span: &span::Id)724     fn exit(&self, span: &span::Id) {
725         self.as_ref().exit(span)
726     }
727 
728     #[inline]
clone_span(&self, id: &span::Id) -> span::Id729     fn clone_span(&self, id: &span::Id) -> span::Id {
730         self.as_ref().clone_span(id)
731     }
732 
733     #[inline]
try_close(&self, id: span::Id) -> bool734     fn try_close(&self, id: span::Id) -> bool {
735         self.as_ref().try_close(id)
736     }
737 
738     #[inline]
739     #[allow(deprecated)]
drop_span(&self, id: span::Id)740     fn drop_span(&self, id: span::Id) {
741         self.as_ref().try_close(id);
742     }
743 
744     #[inline]
current_span(&self) -> span::Current745     fn current_span(&self) -> span::Current {
746         self.as_ref().current_span()
747     }
748 
749     #[inline]
downcast_raw(&self, id: TypeId) -> Option<*const ()>750     unsafe fn downcast_raw(&self, id: TypeId) -> Option<*const ()> {
751         if id == TypeId::of::<Self>() {
752             return Some(self as *const Self as *const _);
753         }
754 
755         self.as_ref().downcast_raw(id)
756     }
757 }
758