1use tracing_core::{metadata::Metadata, span, Dispatch, Event, Interest, LevelFilter, Subscriber};
2
3use crate::{
4 filter,
5 layer::{Context, Layer},
6 registry::LookupSpan,
7};
8#[cfg(all(feature = "registry", feature = "std"))]
9use crate::{filter::FilterId, registry::Registry};
10use core::{
11 any::{Any, TypeId},
12 cmp, fmt,
13 marker::PhantomData,
14};
15
16/// A [`Subscriber`] composed of a `Subscriber` wrapped by one or more
17/// [`Layer`]s.
18///
19/// [`Layer`]: crate::Layer
20/// [`Subscriber`]: tracing_core::Subscriber
21#[derive(Clone)]
22pub struct Layered<L, I, S = I> {
23 /// The layer.
24 layer: L,
25
26 /// The inner value that `self.layer` was layered onto.
27 ///
28 /// If this is also a `Layer`, then this `Layered` will implement `Layer`.
29 /// If this is a `Subscriber`, then this `Layered` will implement
30 /// `Subscriber` instead.
31 inner: I,
32
33 // These booleans are used to determine how to combine `Interest`s and max
34 // level hints when per-layer filters are in use.
35 /// Is `self.inner` a `Registry`?
36 ///
37 /// If so, when combining `Interest`s, we want to "bubble up" its
38 /// `Interest`.
39 inner_is_registry: bool,
40
41 /// Does `self.layer` have per-layer filters?
42 ///
43 /// This will be true if:
44 /// - `self.inner` is a `Filtered`.
45 /// - `self.inner` is a tree of `Layered`s where _all_ arms of those
46 /// `Layered`s have per-layer filters.
47 ///
48 /// Otherwise, if it's a `Layered` with one per-layer filter in one branch,
49 /// but a non-per-layer-filtered layer in the other branch, this will be
50 /// _false_, because the `Layered` is already handling the combining of
51 /// per-layer filter `Interest`s and max level hints with its non-filtered
52 /// `Layer`.
53 has_layer_filter: bool,
54
55 /// Does `self.inner` have per-layer filters?
56 ///
57 /// This is determined according to the same rules as
58 /// `has_layer_filter` above.
59 inner_has_layer_filter: bool,
60 _s: PhantomData<fn(S)>,
61}
62
63// === impl Layered ===
64
65impl<L, S> Layered<L, S>
66where
67 L: Layer<S>,
68 S: Subscriber,
69{
70 /// Returns `true` if this [`Subscriber`] is the same type as `T`.
71 pub fn is<T: Any>(&self) -> bool {
72 self.downcast_ref::<T>().is_some()
73 }
74
75 /// Returns some reference to this [`Subscriber`] value if it is of type `T`,
76 /// or `None` if it isn't.
77 pub fn downcast_ref<T: Any>(&self) -> Option<&T> {
78 unsafe {
79 let raw: *const () = self.downcast_raw(id:TypeId::of::<T>())?;
80 if raw.is_null() {
81 None
82 } else {
83 Some(&*(raw as *const T))
84 }
85 }
86 }
87}
88
89impl<L, S> Subscriber for Layered<L, S>
90where
91 L: Layer<S>,
92 S: Subscriber,
93{
94 fn register_callsite(&self, metadata: &'static Metadata<'static>) -> Interest {
95 self.pick_interest(self.layer.register_callsite(metadata), || {
96 self.inner.register_callsite(metadata)
97 })
98 }
99
100 fn enabled(&self, metadata: &Metadata<'_>) -> bool {
101 if self.layer.enabled(metadata, self.ctx()) {
102 // if the outer layer enables the callsite metadata, ask the subscriber.
103 self.inner.enabled(metadata)
104 } else {
105 // otherwise, the callsite is disabled by the layer
106
107 // If per-layer filters are in use, and we are short-circuiting
108 // (rather than calling into the inner type), clear the current
109 // per-layer filter `enabled` state.
110 #[cfg(feature = "registry")]
111 filter::FilterState::clear_enabled();
112
113 false
114 }
115 }
116
117 fn max_level_hint(&self) -> Option<LevelFilter> {
118 self.pick_level_hint(
119 self.layer.max_level_hint(),
120 self.inner.max_level_hint(),
121 super::subscriber_is_none(&self.inner),
122 )
123 }
124
125 fn new_span(&self, span: &span::Attributes<'_>) -> span::Id {
126 let id = self.inner.new_span(span);
127 self.layer.on_new_span(span, &id, self.ctx());
128 id
129 }
130
131 fn record(&self, span: &span::Id, values: &span::Record<'_>) {
132 self.inner.record(span, values);
133 self.layer.on_record(span, values, self.ctx());
134 }
135
136 fn record_follows_from(&self, span: &span::Id, follows: &span::Id) {
137 self.inner.record_follows_from(span, follows);
138 self.layer.on_follows_from(span, follows, self.ctx());
139 }
140
141 fn event_enabled(&self, event: &Event<'_>) -> bool {
142 if self.layer.event_enabled(event, self.ctx()) {
143 // if the outer layer enables the event, ask the inner subscriber.
144 self.inner.event_enabled(event)
145 } else {
146 // otherwise, the event is disabled by this layer
147 false
148 }
149 }
150
151 fn event(&self, event: &Event<'_>) {
152 self.inner.event(event);
153 self.layer.on_event(event, self.ctx());
154 }
155
156 fn enter(&self, span: &span::Id) {
157 self.inner.enter(span);
158 self.layer.on_enter(span, self.ctx());
159 }
160
161 fn exit(&self, span: &span::Id) {
162 self.inner.exit(span);
163 self.layer.on_exit(span, self.ctx());
164 }
165
166 fn clone_span(&self, old: &span::Id) -> span::Id {
167 let new = self.inner.clone_span(old);
168 if &new != old {
169 self.layer.on_id_change(old, &new, self.ctx())
170 };
171 new
172 }
173
174 #[inline]
175 fn drop_span(&self, id: span::Id) {
176 self.try_close(id);
177 }
178
179 fn try_close(&self, id: span::Id) -> bool {
180 #[cfg(all(feature = "registry", feature = "std"))]
181 let subscriber = &self.inner as &dyn Subscriber;
182 #[cfg(all(feature = "registry", feature = "std"))]
183 let mut guard = subscriber
184 .downcast_ref::<Registry>()
185 .map(|registry| registry.start_close(id.clone()));
186 if self.inner.try_close(id.clone()) {
187 // If we have a registry's close guard, indicate that the span is
188 // closing.
189 #[cfg(all(feature = "registry", feature = "std"))]
190 {
191 if let Some(g) = guard.as_mut() {
192 g.set_closing()
193 };
194 }
195
196 self.layer.on_close(id, self.ctx());
197 true
198 } else {
199 false
200 }
201 }
202
203 #[inline]
204 fn current_span(&self) -> span::Current {
205 self.inner.current_span()
206 }
207
208 #[doc(hidden)]
209 unsafe fn downcast_raw(&self, id: TypeId) -> Option<*const ()> {
210 // Unlike the implementation of `Layer` for `Layered`, we don't have to
211 // handle the "magic PLF downcast marker" here. If a `Layered`
212 // implements `Subscriber`, we already know that the `inner` branch is
213 // going to contain something that doesn't have per-layer filters (the
214 // actual root `Subscriber`). Thus, a `Layered` that implements
215 // `Subscriber` will always be propagating the root subscriber's
216 // `Interest`/level hint, even if it includes a `Layer` that has
217 // per-layer filters, because it will only ever contain layers where
218 // _one_ child has per-layer filters.
219 //
220 // The complex per-layer filter detection logic is only relevant to
221 // *trees* of layers, which involve the `Layer` implementation for
222 // `Layered`, not *lists* of layers, where every `Layered` implements
223 // `Subscriber`. Of course, a linked list can be thought of as a
224 // degenerate tree...but luckily, we are able to make a type-level
225 // distinction between individual `Layered`s that are definitely
226 // list-shaped (their inner child implements `Subscriber`), and
227 // `Layered`s that might be tree-shaped (the inner child is also a
228 // `Layer`).
229
230 // If downcasting to `Self`, return a pointer to `self`.
231 if id == TypeId::of::<Self>() {
232 return Some(self as *const _ as *const ());
233 }
234
235 self.layer
236 .downcast_raw(id)
237 .or_else(|| self.inner.downcast_raw(id))
238 }
239}
240
241impl<S, A, B> Layer<S> for Layered<A, B, S>
242where
243 A: Layer<S>,
244 B: Layer<S>,
245 S: Subscriber,
246{
247 fn on_register_dispatch(&self, subscriber: &Dispatch) {
248 self.layer.on_register_dispatch(subscriber);
249 self.inner.on_register_dispatch(subscriber);
250 }
251
252 fn on_layer(&mut self, subscriber: &mut S) {
253 self.layer.on_layer(subscriber);
254 self.inner.on_layer(subscriber);
255 }
256
257 fn register_callsite(&self, metadata: &'static Metadata<'static>) -> Interest {
258 self.pick_interest(self.layer.register_callsite(metadata), || {
259 self.inner.register_callsite(metadata)
260 })
261 }
262
263 fn enabled(&self, metadata: &Metadata<'_>, ctx: Context<'_, S>) -> bool {
264 if self.layer.enabled(metadata, ctx.clone()) {
265 // if the outer subscriber enables the callsite metadata, ask the inner layer.
266 self.inner.enabled(metadata, ctx)
267 } else {
268 // otherwise, the callsite is disabled by this layer
269 false
270 }
271 }
272
273 fn max_level_hint(&self) -> Option<LevelFilter> {
274 self.pick_level_hint(
275 self.layer.max_level_hint(),
276 self.inner.max_level_hint(),
277 super::layer_is_none(&self.inner),
278 )
279 }
280
281 #[inline]
282 fn on_new_span(&self, attrs: &span::Attributes<'_>, id: &span::Id, ctx: Context<'_, S>) {
283 self.inner.on_new_span(attrs, id, ctx.clone());
284 self.layer.on_new_span(attrs, id, ctx);
285 }
286
287 #[inline]
288 fn on_record(&self, span: &span::Id, values: &span::Record<'_>, ctx: Context<'_, S>) {
289 self.inner.on_record(span, values, ctx.clone());
290 self.layer.on_record(span, values, ctx);
291 }
292
293 #[inline]
294 fn on_follows_from(&self, span: &span::Id, follows: &span::Id, ctx: Context<'_, S>) {
295 self.inner.on_follows_from(span, follows, ctx.clone());
296 self.layer.on_follows_from(span, follows, ctx);
297 }
298
299 #[inline]
300 fn event_enabled(&self, event: &Event<'_>, ctx: Context<'_, S>) -> bool {
301 if self.layer.event_enabled(event, ctx.clone()) {
302 // if the outer layer enables the event, ask the inner subscriber.
303 self.inner.event_enabled(event, ctx)
304 } else {
305 // otherwise, the event is disabled by this layer
306 false
307 }
308 }
309
310 #[inline]
311 fn on_event(&self, event: &Event<'_>, ctx: Context<'_, S>) {
312 self.inner.on_event(event, ctx.clone());
313 self.layer.on_event(event, ctx);
314 }
315
316 #[inline]
317 fn on_enter(&self, id: &span::Id, ctx: Context<'_, S>) {
318 self.inner.on_enter(id, ctx.clone());
319 self.layer.on_enter(id, ctx);
320 }
321
322 #[inline]
323 fn on_exit(&self, id: &span::Id, ctx: Context<'_, S>) {
324 self.inner.on_exit(id, ctx.clone());
325 self.layer.on_exit(id, ctx);
326 }
327
328 #[inline]
329 fn on_close(&self, id: span::Id, ctx: Context<'_, S>) {
330 self.inner.on_close(id.clone(), ctx.clone());
331 self.layer.on_close(id, ctx);
332 }
333
334 #[inline]
335 fn on_id_change(&self, old: &span::Id, new: &span::Id, ctx: Context<'_, S>) {
336 self.inner.on_id_change(old, new, ctx.clone());
337 self.layer.on_id_change(old, new, ctx);
338 }
339
340 #[doc(hidden)]
341 unsafe fn downcast_raw(&self, id: TypeId) -> Option<*const ()> {
342 match id {
343 // If downcasting to `Self`, return a pointer to `self`.
344 id if id == TypeId::of::<Self>() => Some(self as *const _ as *const ()),
345
346 // Oh, we're looking for per-layer filters!
347 //
348 // This should only happen if we are inside of another `Layered`,
349 // and it's trying to determine how it should combine `Interest`s
350 // and max level hints.
351 //
352 // In that case, this `Layered` should be considered to be
353 // "per-layer filtered" if *both* the outer layer and the inner
354 // layer/subscriber have per-layer filters. Otherwise, this `Layered
355 // should *not* be considered per-layer filtered (even if one or the
356 // other has per layer filters). If only one `Layer` is per-layer
357 // filtered, *this* `Layered` will handle aggregating the `Interest`
358 // and level hints on behalf of its children, returning the
359 // aggregate (which is the value from the &non-per-layer-filtered*
360 // child).
361 //
362 // Yes, this rule *is* slightly counter-intuitive, but it's
363 // necessary due to a weird edge case that can occur when two
364 // `Layered`s where one side is per-layer filtered and the other
365 // isn't are `Layered` together to form a tree. If we didn't have
366 // this rule, we would actually end up *ignoring* `Interest`s from
367 // the non-per-layer-filtered layers, since both branches would
368 // claim to have PLF.
369 //
370 // If you don't understand this...that's fine, just don't mess with
371 // it. :)
372 id if filter::is_plf_downcast_marker(id) => {
373 self.layer.downcast_raw(id).and(self.inner.downcast_raw(id))
374 }
375
376 // Otherwise, try to downcast both branches normally...
377 _ => self
378 .layer
379 .downcast_raw(id)
380 .or_else(|| self.inner.downcast_raw(id)),
381 }
382 }
383}
384
385impl<'a, L, S> LookupSpan<'a> for Layered<L, S>
386where
387 S: Subscriber + LookupSpan<'a>,
388{
389 type Data = S::Data;
390
391 fn span_data(&'a self, id: &span::Id) -> Option<Self::Data> {
392 self.inner.span_data(id)
393 }
394
395 #[cfg(all(feature = "registry", feature = "std"))]
396 fn register_filter(&mut self) -> FilterId {
397 self.inner.register_filter()
398 }
399}
400
401impl<L, S> Layered<L, S>
402where
403 S: Subscriber,
404{
405 fn ctx(&self) -> Context<'_, S> {
406 Context::new(&self.inner)
407 }
408}
409
410impl<A, B, S> Layered<A, B, S>
411where
412 A: Layer<S>,
413 S: Subscriber,
414{
415 pub(super) fn new(layer: A, inner: B, inner_has_layer_filter: bool) -> Self {
416 #[cfg(all(feature = "registry", feature = "std"))]
417 let inner_is_registry = TypeId::of::<S>() == TypeId::of::<crate::registry::Registry>();
418
419 #[cfg(not(all(feature = "registry", feature = "std")))]
420 let inner_is_registry = false;
421
422 let inner_has_layer_filter = inner_has_layer_filter || inner_is_registry;
423 let has_layer_filter = filter::layer_has_plf(&layer);
424 Self {
425 layer,
426 inner,
427 has_layer_filter,
428 inner_has_layer_filter,
429 inner_is_registry,
430 _s: PhantomData,
431 }
432 }
433
434 fn pick_interest(&self, outer: Interest, inner: impl FnOnce() -> Interest) -> Interest {
435 if self.has_layer_filter {
436 return inner();
437 }
438
439 // If the outer layer has disabled the callsite, return now so that
440 // the inner layer/subscriber doesn't get its hopes up.
441 if outer.is_never() {
442 // If per-layer filters are in use, and we are short-circuiting
443 // (rather than calling into the inner type), clear the current
444 // per-layer filter interest state.
445 #[cfg(feature = "registry")]
446 filter::FilterState::take_interest();
447
448 return outer;
449 }
450
451 // The `inner` closure will call `inner.register_callsite()`. We do this
452 // before the `if` statement to ensure that the inner subscriber is
453 // informed that the callsite exists regardless of the outer layer's
454 // filtering decision.
455 let inner = inner();
456 if outer.is_sometimes() {
457 // if this interest is "sometimes", return "sometimes" to ensure that
458 // filters are reevaluated.
459 return outer;
460 }
461
462 // If there is a per-layer filter in the `inner` stack, and it returns
463 // `never`, change the interest to `sometimes`, because the `outer`
464 // layer didn't return `never`. This means that _some_ layer still wants
465 // to see that callsite, even though the inner stack's per-layer filter
466 // didn't want it. Therefore, returning `sometimes` will ensure
467 // `enabled` is called so that the per-layer filter can skip that
468 // span/event, while the `outer` layer still gets to see it.
469 if inner.is_never() && self.inner_has_layer_filter {
470 return Interest::sometimes();
471 }
472
473 // otherwise, allow the inner subscriber or subscriber to weigh in.
474 inner
475 }
476
477 fn pick_level_hint(
478 &self,
479 outer_hint: Option<LevelFilter>,
480 inner_hint: Option<LevelFilter>,
481 inner_is_none: bool,
482 ) -> Option<LevelFilter> {
483 if self.inner_is_registry {
484 return outer_hint;
485 }
486
487 if self.has_layer_filter && self.inner_has_layer_filter {
488 return Some(cmp::max(outer_hint?, inner_hint?));
489 }
490
491 if self.has_layer_filter && inner_hint.is_none() {
492 return None;
493 }
494
495 if self.inner_has_layer_filter && outer_hint.is_none() {
496 return None;
497 }
498
499 // If the layer is `Option::None`, then we
500 // want to short-circuit the layer underneath, if it
501 // returns `None`, to override the `None` layer returning
502 // `Some(OFF)`, which should ONLY apply when there are
503 // no other layers that return `None`. Note this
504 // `None` does not == `Some(TRACE)`, it means
505 // something more like: "whatever all the other
506 // layers agree on, default to `TRACE` if none
507 // have an opinion". We also choose do this AFTER
508 // we check for per-layer filters, which
509 // have their own logic.
510 //
511 // Also note that this does come at some perf cost, but
512 // this function is only called on initialization and
513 // subscriber reloading.
514 if super::layer_is_none(&self.layer) {
515 return cmp::max(outer_hint, Some(inner_hint?));
516 }
517
518 // Similarly, if the layer on the inside is `None` and it returned an
519 // `Off` hint, we want to override that with the outer hint.
520 if inner_is_none && inner_hint == Some(LevelFilter::OFF) {
521 return outer_hint;
522 }
523
524 cmp::max(outer_hint, inner_hint)
525 }
526}
527
528impl<A, B, S> fmt::Debug for Layered<A, B, S>
529where
530 A: fmt::Debug,
531 B: fmt::Debug,
532{
533 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
534 #[cfg(all(feature = "registry", feature = "std"))]
535 let alt: bool = f.alternate();
536 let mut s: DebugStruct<'_, '_> = f.debug_struct(name:"Layered");
537 // These additional fields are more verbose and usually only necessary
538 // for internal debugging purposes, so only print them if alternate mode
539 // is enabled.
540
541 #[cfg(all(feature = "registry", feature = "std"))]
542 {
543 if alt {
544 s.field("inner_is_registry", &self.inner_is_registry)
545 .field("has_layer_filter", &self.has_layer_filter)
546 .field(name:"inner_has_layer_filter", &self.inner_has_layer_filter);
547 }
548 }
549
550 s&mut DebugStruct<'_, '_>.field("layer", &self.layer)
551 .field(name:"inner", &self.inner)
552 .finish()
553 }
554}
555