<!DOCTYPE html><htmllang="en"><head><metacharset="utf-8"><metaname="viewport"content="width=device-width, initial-scale=1.0"><metaname="generator"content="rustdoc"><metaname="description"content="Trait representing the functions required to collect trace data."><title>Subscriber in tracing - Rust</title><linkrel="preload"as="font"type="font/woff2"crossoriginhref="../static.files/SourceSerif4-Regular-46f98efaafac5295.ttf.woff2"><linkrel="preload"as="font"type="font/woff2"crossoriginhref="../static.files/FiraSans-Regular-018c141bf0843ffd.woff2"><linkrel="preload"as="font"type="font/woff2"crossoriginhref="../static.files/FiraSans-Medium-8f9a781e4970d388.woff2"><linkrel="preload"as="font"type="font/woff2"crossoriginhref="../static.files/SourceCodePro-Regular-562dcc5011b6de7d.ttf.woff2"><linkrel="preload"as="font"type="font/woff2"crossoriginhref="../static.files/SourceCodePro-Semibold-d899c5a5c4aeb14a.ttf.woff2"><linkrel="stylesheet"href="../static.files/normalize-76eba96aa4d2e634.css"><linkrel="stylesheet"href="../static.files/rustdoc-5bc39a1768837dd0.css"><metaname="rustdoc-vars"data-root-path="../"data-static-root-path="../static.files/"data-current-crate="tracing"data-themes=""data-resource-suffix=""data-rustdoc-version="1.77.2 (25ef9e3d8 2024-04-09)"data-channel="1.77.2"data-search-js="search-dd67cee4cfa65049.js"data-settings-js="settings-4313503d2e1961c2.js"><scriptsrc="../static.files/storage-4c98445ec4002617.js"></script><scriptdefersrc="sidebar-items.js"></script><scriptdefersrc="../static.files/main-48f368f3872407c8.js"></script><noscript><linkrel="stylesheet"href="../static.files/noscript-04d5337699b92874.css"></noscript><linkrel="alternate icon"type="image/png"href="../static.files/favicon-16x16-8b506e7a72182f1c.png"><linkrel="alternate icon"type="image/png"href="../static.files/favicon-32x32-422f7d1d52889060.png"><linkrel="icon"type="image/svg+xml"href="../static.files/favicon-2c020d218678b618.svg"></head><bodyclass="rustdoc trait"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><navclass="mobile-topbar"><buttonclass="sidebar-menu-toggle"title="show sidebar"></button><aclass="logo-container"href="../tracing/index.html"><imgsrc="https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/logo-type.png"alt=""></a></nav><navclass="sidebar"><divclass="sidebar-crate"><aclass="logo-container"href="../tracing/index.html"><imgsrc="https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/logo-type.png"alt="logo"></a><h2><ahref="../tracing/index.html">tracing</a><spanclass="version">0.1.40</span></h2></div><h2class="location"><ahref="#">Subscriber</a></h2><divclass="sidebar-elems"><section><h3><ahref="#required-methods">Required Methods</a></h3><ulclass="block"><li><ahref="#tymethod.enabled">enabled</a></li><li><ahref="#tymethod.enter">enter</a></li><li><ahref="#tymethod.event">event</a></li><li><ahref="#tymethod.exit">exit</a></li><li><ahref="#tymethod.new_span">new_span</a></li><li><ahref="#tymethod.record">record</a></li><li><ahref="#tymethod.record_follows_from">record_follows_from</a></li></ul><h3><ahref="#provided-methods">Provided Methods</a></h3><ulclass="block"><li><ahref="#method.clone_span">clone_span</a></li><li><ahref="#method.current_span">current_span</a></li><li><ahref="#method.downcast_raw">downcast_raw</a></li><li><ahref="#method.drop_span">drop_span</a></li><li><ahref="#method.event_enabled">event_enabled</a></li><li><ahref="#method.max_level_hint">max_level_hint</a></li><li><ahref="#method.on_register_dispatch">on_register_dispatch</a></li><li><ahref="#method.register_callsite">register_callsite</a></li><li><ahref="#method.try_close">try_close</a></li></ul><h3><ahref="#foreign-impls">Implementations on Foreign Types</a></h3><ulclass="block"><li><ahref="#impl-Subscriber-for-Arc%3CS%3E">Arc<S></a></li><li><ahref="#impl-Subscriber-for-Box%3CS%3E">Box<S></a></li></ul><h3><ahref="#implementatio
<main><divclass="width-limiter"><navclass="sub"><formclass="search-form"><span></span><divid="sidebar-button"tabindex="-1"><ahref="../tracing/all.html"title="show sidebar"></a></div><inputclass="search-input"name="search"aria-label="Run search in the documentation"autocomplete="off"spellcheck="false"placeholder="Click or press ‘S’ to search, ‘?’ for more options…"type="search"><divid="help-button"tabindex="-1"><ahref="../help.html"title="help">?</a></div><divid="settings-menu"tabindex="-1"><ahref="../settings.html"title="settings"><imgwidth="22"height="22"alt="Change settings"src="../static.files/wheel-7b819b6101059cd0.svg"></a></div></form></nav><sectionid="main-content"class="content"><divclass="main-heading"><h1>Trait <ahref="index.html">tracing</a>::<wbr><aclass="trait"href="#">Subscriber</a><buttonid="copy-path"title="Copy item path to clipboard"><imgsrc="../static.files/clipboard-7571035ce49a181d.svg"width="19"height="18"alt="Copy item path"></button></h1><spanclass="out-of-band"><aclass="src"href="../src/tracing_core/subscriber.rs.html#83">source</a> · <buttonid="toggle-all-docs"title="collapse all docs">[<span>−</span>]</button></span></div><preclass="rust item-decl"><code>pub trait Subscriber: 'static {
</details>}</code></pre><detailsclass="toggle top-doc"open><summaryclass="hideme"><span>Expand description</span></summary><divclass="docblock"><p>Trait representing the functions required to collect trace data.</p>
<p>Crates that provide implementations of methods for collecting or recording
trace data should implement the <code>Subscriber</code> interface. This trait is
intended to represent fundamental primitives for collecting trace events and
spans — other libraries may offer utility functions and types to make
subscriber implementations more modular or improve the ergonomics of writing
subscribers.</p>
<p>A subscriber is responsible for the following:</p>
<ul>
<li>Registering new spans as they are created, and providing them with span
IDs. Implicitly, this means the subscriber may determine the strategy for
determining span equality.</li>
<li>Recording the attachment of field values and follows-from annotations to
spans.</li>
<li>Filtering spans and events, and determining when those filters must be
invalidated.</li>
<li>Observing spans as they are entered, exited, and closed, and events as
they occur.</li>
</ul>
<p>When a span is entered or exited, the subscriber is provided only with the
<ahref="span/struct.Id.html"title="struct tracing::span::Id">ID</a> with which it tagged that span when it was created. This means
that it is up to the subscriber to determine whether and how span <em>data</em> —
the fields and metadata describing the span — should be stored. The
<ahref="trait.Subscriber.html#tymethod.new_span"title="method tracing::Subscriber::new_span"><code>new_span</code></a> function is called when a new span is created, and at that
point, the subscriber <em>may</em> choose to store the associated data if it will
be referenced again. However, if the data has already been recorded and will
not be needed by the implementations of <code>enter</code> and <code>exit</code>, the subscriber
may freely discard that data without allocating space to store it.</p>
<p>Some trait methods on <code>Subscriber</code> have default implementations, either in
order to reduce the surface area of implementing <code>Subscriber</code>, or for
backward-compatibility reasons. However, many subscribers will likely want
to override these default implementations.</p>
<p>The following methods are likely of interest:</p>
<ul>
<li>
<p><ahref="trait.Subscriber.html#method.register_callsite"title="method tracing::Subscriber::register_callsite"><code>register_callsite</code></a> is called once for each callsite from which a span
event may originate, and returns an <ahref="subscriber/struct.Interest.html"title="struct tracing::subscriber::Interest"><code>Interest</code></a> value describing whether or
not the subscriber wishes to see events or spans from that callsite. By
default, it calls <ahref="trait.Subscriber.html#tymethod.enabled"title="method tracing::Subscriber::enabled"><code>enabled</code></a>, and returns <code>Interest::always()</code> if
<code>enabled</code> returns true, or <code>Interest::never()</code> if enabled returns false.
However, if the subscriber’s interest can change dynamically at runtime,
it may want to override this function to return <code>Interest::sometimes()</code>.
Additionally, subscribers which wish to perform a behaviour once for each
callsite, such as allocating storage for data related to that callsite,
can perform it in <code>register_callsite</code>.</p>
<p>See also the <ahref="../tracing_core/callsite/index.html#registering-callsites"title="mod tracing_core::callsite">documentation on the callsite registry</a> for details
on <ahref="trait.Subscriber.html#method.register_callsite"title="method tracing::Subscriber::register_callsite"><code>register_callsite</code></a>.</p>
</li>
<li>
<p><ahref="trait.Subscriber.html#method.event_enabled"title="method tracing::Subscriber::event_enabled"><code>event_enabled</code></a> is called once before every call to the <ahref="trait.Subscriber.html#tymethod.event"title="method tracing::Subscriber::event"><code>event</code></a>
method. This can be used to implement filtering on events once their field
values are known, but before any processing is done in the <code>event</code> method.</p>
</li>
<li>
<p><ahref="trait.Subscriber.html#method.clone_span"title="method tracing::Subscriber::clone_span"><code>clone_span</code></a> is called every time a span ID is cloned, and <ahref="trait.Subscriber.html#method.try_close"title="method tracing::Subscriber::try_close"><code>try_close</code></a>
is called when a span ID is dropped. By default, these functions do
nothing. However, they can be used to implement reference counting for
spans, allowing subscribers to free storage for span data and to determine
when a span has <em>closed</em> permanently (rather than being exited).
Subscribers which store per-span data or which need to track span closures
</div></details><h2id="required-methods"class="section-header">Required Methods<ahref="#required-methods"class="anchor">§</a></h2><divclass="methods"><detailsclass="toggle method-toggle"open><summary><sectionid="tymethod.enabled"class="method"><aclass="src rightside"href="../src/tracing_core/subscriber.rs.html#206">source</a><h4class="code-header">fn <ahref="#tymethod.enabled"class="fn">enabled</a>(&self, metadata: &<aclass="struct"href="struct.Metadata.html"title="struct tracing::Metadata">Metadata</a><'_>) -><aclass="primitive"href="https://doc.rust-lang.org/1.77.2/std/primitive.bool.html">bool</a></h4></section></summary><divclass="docblock"><p>Returns true if a span or event with the specified <ahref="struct.Metadata.html"title="struct tracing::Metadata">metadata</a> would be
<p>By default, it is assumed that this filter needs only be evaluated once
for each callsite, so it is called by <ahref="trait.Subscriber.html#method.register_callsite"title="method tracing::Subscriber::register_callsite"><code>register_callsite</code></a> when each
callsite is registered. The result is used to determine if the subscriber
is always <ahref="subscriber/struct.Interest.html"title="struct tracing::subscriber::Interest">interested</a> or never interested in that callsite. This is intended
primarily as an optimization, so that expensive filters (such as those
involving string search, et cetera) need not be re-evaluated.</p>
<p>However, if the subscriber’s interest in a particular span or event may
change, or depends on contexts only determined dynamically at runtime,
then the <code>register_callsite</code> method should be overridden to return
<ahref="subscriber/struct.Interest.html#method.sometimes"title="associated function tracing::subscriber::Interest::sometimes"><code>Interest::sometimes</code></a>. In that case, this function will be called every
time that span or event occurs.</p>
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="tymethod.new_span"class="method"><aclass="src rightside"href="../src/tracing_core/subscriber.rs.html#258">source</a><h4class="code-header">fn <ahref="#tymethod.new_span"class="fn">new_span</a>(&self, span: &<aclass="struct"href="span/struct.Attributes.html"title="struct tracing::span::Attributes">Attributes</a><'_>) -><aclass="struct"href="span/struct.Id.html"title="struct tracing::span::Id">Id</a></h4></section></summary><divclass="docblock"><p>Visit the construction of a new span, returning a new <ahref="span/struct.Id.html"title="struct tracing::span::Id">span ID</a> for the
span being constructed.</p>
<p>The provided <ahref="span/struct.Attributes.html"title="struct tracing::span::Attributes"><code>Attributes</code></a> contains any field values that were provided
when the span was created. The subscriber may pass a <ahref="field/trait.Visit.html"title="trait tracing::field::Visit">visitor</a> to the
<code>Attributes</code>’<ahref="span/struct.Attributes.html#method.record"title="method tracing::span::Attributes::record"><code>record</code> method</a> to record these values.</p>
<p>IDs are used to uniquely identify spans and events within the context of a
subscriber, so span equality will be based on the returned ID. Thus, if
the subscriber wishes for all spans with the same metadata to be
considered equal, it should return the same ID every time it is given a
particular set of metadata. Similarly, if it wishes for two separate
instances of a span with the same metadata to <em>not</em> be equal, it should
return a distinct ID every time this function is called, regardless of
the metadata.</p>
<p>Note that the subscriber is free to assign span IDs based on whatever
scheme it sees fit. Any guarantees about uniqueness, ordering, or ID
reuse are left up to the subscriber implementation to determine.</p>
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="tymethod.record"class="method"><aclass="src rightside"href="../src/tracing_core/subscriber.rs.html#298">source</a><h4class="code-header">fn <ahref="#tymethod.record"class="fn">record</a>(&self, span: &<aclass="struct"href="span/struct.Id.html"title="struct tracing::span::Id">Id</a>, values: &<aclass="struct"href="span/struct.Record.html"title="struct tracing::span::Record">Record</a><'_>)</h4></section></summary><divclass="docblock"><p>Record a set of values on a span.</p>
<p>This method will be invoked when value is recorded on a span.
Recording multiple values for the same field is possible,
but the actual behaviour is defined by the subscriber implementation.</p>
<p>Keep in mind that a span might not provide a value
for each field it declares.</p>
<p>The subscriber is expected to provide a <ahref="field/trait.Visit.html"title="trait tracing::field::Visit">visitor</a> to the <code>Record</code>’s
<ahref="span/struct.Record.html#method.record"title="method tracing::span::Record::record"><code>record</code> method</a> in order to record the added values.</p>
<p>“foo = 3” will be recorded when <ahref="span/struct.Attributes.html#method.record"title="method tracing::span::Attributes::record"><code>record</code></a> is called on the
<code>Attributes</code> passed to <code>new_span</code>.
Since values are not provided for the <code>bar</code> and <code>baz</code> fields,
the span’s <code>Metadata</code> will indicate that it <em>has</em> those fields,
but values for them won’t be recorded at this time.</p>
<divclass="example-wrap ignore"><ahref="#"class="tooltip"title="This example is not tested">ⓘ</a><preclass="rust rust-example-rendered"><code>
<spanclass="kw">let </span><spanclass="kw-2">mut </span>span = <spanclass="macro">span!</span>(<spanclass="string">"my_span"</span>, foo = <spanclass="number">3</span>, bar, baz);
<spanclass="comment">// `Subscriber::record` will be called with a `Record`
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="tymethod.record_follows_from"class="method"><aclass="src rightside"href="../src/tracing_core/subscriber.rs.html#318">source</a><h4class="code-header">fn <ahref="#tymethod.record_follows_from"class="fn">record_follows_from</a>(&self, span: &<aclass="struct"href="span/struct.Id.html"title="struct tracing::span::Id">Id</a>, follows: &<aclass="struct"href="span/struct.Id.html"title="struct tracing::span::Id">Id</a>)</h4></section></summary><divclass="docblock"><p>Adds an indication that <code>span</code> follows from the span with the id
<code>follows</code>.</p>
<p>This relationship differs somewhat from the parent-child relationship: a
span may have any number of prior spans, rather than a single one; and
spans are not considered to be executing <em>inside</em> of the spans they
follow from. This means that a span may close even if subsequent spans
that follow from it are still open, and time spent inside of a
subsequent span should not be included in the time its precedents were
executing. This is used to model causal relationships such as when a
single future spawns several related background tasks, et cetera.</p>
<p>If the subscriber has spans corresponding to the given IDs, it should
record this relationship in whatever way it deems necessary. Otherwise,
if one or both of the given span IDs do not correspond to spans that the
subscriber knows about, or if a cyclical relationship would be created
(i.e., some span <em>a</em> which proceeds some other span <em>b</em> may not also
follow from <em>b</em>), it may silently do nothing.</p>
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="tymethod.event"class="method"><aclass="src rightside"href="../src/tracing_core/subscriber.rs.html#349">source</a><h4class="code-header">fn <ahref="#tymethod.event"class="fn">event</a>(&self, event: &<aclass="struct"href="event/struct.Event.html"title="struct tracing::event::Event">Event</a><'_>)</h4></section></summary><divclass="docblock"><p>Records that an <ahref="event/struct.Event.html"title="struct tracing::event::Event"><code>Event</code></a> has occurred.</p>
<p>This method will be invoked when an Event is constructed by
the <code>Event</code>’s <ahref="event/struct.Event.html#method.dispatch"title="associated function tracing::event::Event::dispatch"><code>dispatch</code> method</a>. For example, this happens internally
when an event macro from <code>tracing</code> is called.</p>
<p>The key difference between this method and <code>record</code> is that <code>record</code> is
called when a value is recorded for a field defined by a span,
while <code>event</code> is called when a new event occurs.</p>
<p>The provided <code>Event</code> struct contains any field values attached to the
event. The subscriber may pass a <ahref="field/trait.Visit.html"title="trait tracing::field::Visit">visitor</a> to the <code>Event</code>’s
<ahref="event/struct.Event.html#method.record"title="method tracing::event::Event::record"><code>record</code> method</a> to record these values.</p>
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="tymethod.enter"class="method"><aclass="src rightside"href="../src/tracing_core/subscriber.rs.html#359">source</a><h4class="code-header">fn <ahref="#tymethod.enter"class="fn">enter</a>(&self, span: &<aclass="struct"href="span/struct.Id.html"title="struct tracing::span::Id">Id</a>)</h4></section></summary><divclass="docblock"><p>Records that a span has been entered.</p>
<p>When entering a span, this method is called to notify the subscriber
that the span has been entered. The subscriber is provided with the
<ahref="span/struct.Id.html"title="struct tracing::span::Id">span ID</a> of the entered span, and should update any internal state
tracking the current span accordingly.</p>
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="tymethod.exit"class="method"><aclass="src rightside"href="../src/tracing_core/subscriber.rs.html#371">source</a><h4class="code-header">fn <ahref="#tymethod.exit"class="fn">exit</a>(&self, span: &<aclass="struct"href="span/struct.Id.html"title="struct tracing::span::Id">Id</a>)</h4></section></summary><divclass="docblock"><p>Records that a span has been exited.</p>
<p>When exiting a span, this method is called to notify the subscriber
that the span has been exited. The subscriber is provided with the
<ahref="span/struct.Id.html"title="struct tracing::span::Id">span ID</a> of the exited span, and should update any internal state
tracking the current span accordingly.</p>
<p>Exiting a span does not imply that the span will not be re-entered.</p>
</div></details></div><h2id="provided-methods"class="section-header">Provided Methods<ahref="#provided-methods"class="anchor">§</a></h2><divclass="methods"><detailsclass="toggle method-toggle"open><summary><sectionid="method.on_register_dispatch"class="method"><aclass="src rightside"href="../src/tracing_core/subscriber.rs.html#103">source</a><h4class="code-header">fn <ahref="#method.on_register_dispatch"class="fn">on_register_dispatch</a>(&self, subscriber: &<aclass="struct"href="struct.Dispatch.html"title="struct tracing::Dispatch">Dispatch</a>)</h4></section></summary><divclass="docblock"><p>Invoked when this subscriber becomes a <ahref="struct.Dispatch.html"title="struct tracing::Dispatch"><code>Dispatch</code></a>.</p>
<p><code>Subscriber</code>s should not store their own <ahref="struct.Dispatch.html"title="struct tracing::Dispatch"><code>Dispatch</code></a>. Because the
<code>Dispatch</code> owns the <code>Subscriber</code>, storing the <code>Dispatch</code> within the
<code>Subscriber</code> will create a reference count cycle, preventing the <code>Dispatch</code>
from ever being dropped.</p>
<p>Instead, when it is necessary to store a cyclical reference to the
<code>Dispatch</code> within a <code>Subscriber</code>, use <ahref="struct.Dispatch.html#method.downgrade"title="method tracing::Dispatch::downgrade"><code>Dispatch::downgrade</code></a> to convert a
<code>Dispatch</code> into a <ahref="dispatcher/struct.WeakDispatch.html"title="struct tracing::dispatcher::WeakDispatch"><code>WeakDispatch</code></a>. This type is analogous to
<ahref="https://doc.rust-lang.org/1.77.2/alloc/sync/struct.Weak.html"title="struct alloc::sync::Weak"><code>std::sync::Weak</code></a>, and does not create a reference count cycle. A
<ahref="dispatcher/struct.WeakDispatch.html"title="struct tracing::dispatcher::WeakDispatch"><code>WeakDispatch</code></a> can be stored within a <code>Subscriber</code> without causing a
memory leak, and can be <ahref="dispatcher/struct.WeakDispatch.html#method.upgrade"title="method tracing::dispatcher::WeakDispatch::upgrade">upgraded</a> into a <code>Dispatch</code> temporarily when
the <code>Dispatch</code> must be accessed by the <code>Subscriber</code>.</p>
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="method.register_callsite"class="method"><aclass="src rightside"href="../src/tracing_core/subscriber.rs.html#178">source</a><h4class="code-header">fn <ahref="#method.register_callsite"class="fn">register_callsite</a>(&self, metadata: &'static <aclass="struct"href="struct.Metadata.html"title="struct tracing::Metadata">Metadata</a><'static>) -><aclass="struct"href="subscriber/struct.Interest.html"title="struct tracing::subscriber::Interest">Interest</a></h4></section></summary><divclass="docblock"><p>Registers a new <ahref="../tracing_core/callsite/index.html"title="mod tracing_core::callsite">callsite</a> with this subscriber, returning whether or not
the subscriber is interested in being notified about the callsite.</p>
<p>By default, this function assumes that the subscriber’s <ahref="trait.Subscriber.html#tymethod.enabled"title="method tracing_core::subscriber::Subscriber::enabled::enabled">filter</a>
represents an unchanging view of its interest in the callsite. However,
if this is not the case, subscribers may override this function to
indicate different interests, or to implement behaviour that should run
once for every callsite.</p>
<p>This function is guaranteed to be called at least once per callsite on
every active subscriber. The subscriber may store the keys to fields it
cares about in order to reduce the cost of accessing fields by name,
preallocate storage for that callsite, or perform any other actions it
wishes to perform once for each callsite.</p>
<p>The subscriber should then return an <ahref="subscriber/struct.Interest.html"title="struct tracing::subscriber::Interest"><code>Interest</code></a>, indicating
whether it is interested in being notified about that callsite in the
future. This may be <code>Always</code> indicating that the subscriber always
wishes to be notified about the callsite, and its filter need not be
re-evaluated; <code>Sometimes</code>, indicating that the subscriber may sometimes
care about the callsite but not always (such as when sampling), or
<code>Never</code>, indicating that the subscriber never wishes to be notified about
that callsite. If all active subscribers return <code>Never</code>, a callsite will
never be enabled unless a new subscriber expresses interest in it.</p>
<p><code>Subscriber</code>s which require their filters to be run every time an event
occurs or a span is entered/exited should return <code>Interest::sometimes</code>.
If a subscriber returns <code>Interest::sometimes</code>, then its <ahref="trait.Subscriber.html#tymethod.enabled"title="method tracing::Subscriber::enabled"><code>enabled</code></a> method
will be called every time an event or span is created from that callsite.</p>
<p>For example, suppose a sampling subscriber is implemented by
incrementing a counter every time <code>enabled</code> is called and only returning
<code>true</code> when the counter is divisible by a specified sampling rate. If
that subscriber returns <code>Interest::always</code> from <code>register_callsite</code>, then
the filter will not be re-evaluated once it has been applied to a given
set of metadata. Thus, the counter will not be incremented, and the span
or event that corresponds to the metadata will never be <code>enabled</code>.</p>
<p><code>Subscriber</code>s that need to change their filters occasionally should call
<ahref="../tracing_core/callsite/fn.rebuild_interest_cache.html"title="fn tracing_core::callsite::rebuild_interest_cache"><code>rebuild_interest_cache</code></a> to re-evaluate <code>register_callsite</code> for all
callsites.</p>
<p>Similarly, if a <code>Subscriber</code> has a filtering strategy that can be
changed dynamically at runtime, it would need to re-evaluate that filter
if the cached results have changed.</p>
<p>A subscriber which manages fanout to multiple other subscribers
should proxy this decision to all of its child subscribers,
returning <code>Interest::never</code> only if <em>all</em> such children return
<code>Interest::never</code>. If the set of subscribers to which spans are
broadcast may change dynamically, the subscriber should also never
return <code>Interest::Never</code>, as a new subscriber may be added that <em>is</em>
interested.</p>
<p>See the <ahref="../tracing_core/callsite/index.html#registering-callsites"title="mod tracing_core::callsite">documentation on the callsite registry</a> for more
details on how and when the <code>register_callsite</code> method is called.</p>
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="method.max_level_hint"class="method"><aclass="src rightside"href="../src/tracing_core/subscriber.rs.html#230">source</a><h4class="code-header">fn <ahref="#method.max_level_hint"class="fn">max_level_hint</a>(&self) -><aclass="enum"href="https://doc.rust-lang.org/1.77.2/core/option/enum.Option.html"title="enum core::option::Option">Option</a><<aclass="struct"href="level_filters/struct.LevelFilter.html"title="struct tracing::level_filters::LevelFilter">LevelFilter</a>></h4></section></summary><divclass="docblock"><p>Returns the highest <ahref="struct.Level.html"title="struct tracing::Level">verbosity level</a> that this <code>Subscriber</code> will
enable, or <code>None</code>, if the subscriber does not implement level-based
filtering or chooses not to implement this method.</p>
<p>If this method returns a <ahref="struct.Level.html"title="struct tracing::Level"><code>Level</code></a>, it will be used as a hint to
determine the most verbose level that will be enabled. This will allow
spans and events which are more verbose than that level to be skipped
more efficiently. Subscribers which perform filtering are strongly
encouraged to provide an implementation of this method.</p>
<p>If the maximum level the subscriber will enable can change over the
course of its lifetime, it is free to return a different value from
multiple invocations of this method. However, note that changes in the
maximum level will <strong>only</strong> be reflected after the callsite <ahref="subscriber/struct.Interest.html"title="struct tracing::subscriber::Interest"><code>Interest</code></a>
cache is rebuilt, by calling the <ahref="../tracing_core/callsite/fn.rebuild_interest_cache.html"title="fn tracing_core::callsite::rebuild_interest_cache"><code>callsite::rebuild_interest_cache</code></a>
function. Therefore, if the subscriber will change the value returned by
this method, it is responsible for ensuring that
<ahref="../tracing_core/callsite/fn.rebuild_interest_cache.html"title="fn tracing_core::callsite::rebuild_interest_cache"><code>rebuild_interest_cache</code></a> is called after the value of the max
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="method.event_enabled"class="method"><aclass="src rightside"href="../src/tracing_core/subscriber.rs.html#326">source</a><h4class="code-header">fn <ahref="#method.event_enabled"class="fn">event_enabled</a>(&self, event: &<aclass="struct"href="event/struct.Event.html"title="struct tracing::event::Event">Event</a><'_>) -><aclass="primitive"href="https://doc.rust-lang.org/1.77.2/std/primitive.bool.html">bool</a></h4></section></summary><divclass="docblock"><p>Determine if an <ahref="event/struct.Event.html"title="struct tracing::event::Event"><code>Event</code></a> should be recorded.</p>
<p>By default, this returns <code>true</code> and <code>Subscriber</code>s can filter events in
<ahref="trait.Subscriber.html#tymethod.event"title="method tracing_core::subscriber::Subscriber::event::event"><code>event</code></a> without any penalty. However, when <code>event</code> is
more complicated, this can be used to determine if <code>event</code> should be
called at all, separating out the decision from the processing.</p>
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="method.clone_span"class="method"><aclass="src rightside"href="../src/tracing_core/subscriber.rs.html#393">source</a><h4class="code-header">fn <ahref="#method.clone_span"class="fn">clone_span</a>(&self, id: &<aclass="struct"href="span/struct.Id.html"title="struct tracing::span::Id">Id</a>) -><aclass="struct"href="span/struct.Id.html"title="struct tracing::span::Id">Id</a></h4></section></summary><divclass="docblock"><p>Notifies the subscriber that a <ahref="span/struct.Id.html"title="struct tracing::span::Id">span ID</a> has been cloned.</p>
<p>This function is guaranteed to only be called with span IDs that were
returned by this subscriber’s <code>new_span</code> function.</p>
<p>Note that the default implementation of this function this is just the
identity function, passing through the identifier. However, it can be
used in conjunction with <ahref="trait.Subscriber.html#method.try_close"title="method tracing::Subscriber::try_close"><code>try_close</code></a> to track the number of handles
capable of <code>enter</code>ing a span. When all the handles have been dropped
(i.e., <code>try_close</code> has been called one more time than <code>clone_span</code> for a
given ID), the subscriber may assume that the span will not be entered
again. It is then free to deallocate storage for data associated with
that span, write data from that span to IO, and so on.</p>
<p>For more unsafe situations, however, if <code>id</code> is itself a pointer of some
kind this can be used as a hook to “clone” the pointer, depending on
what that means for the specified pointer.</p>
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="method.drop_span"class="method"><aclass="src rightside"href="../src/tracing_core/subscriber.rs.html#407">source</a><h4class="code-header">fn <ahref="#method.drop_span"class="fn">drop_span</a>(&self, _id: <aclass="struct"href="span/struct.Id.html"title="struct tracing::span::Id">Id</a>)</h4></section></summary><spanclass="item-info"><divclass="stab deprecated"><spanclass="emoji">👎</span><span>Deprecated since 0.1.2: use <code>Subscriber::try_close</code> instead</span></div></span><divclass="docblock"><p><strong>This method is deprecated.</strong></p>
<p>Using <code>drop_span</code> may result in subscribers composed using
<code>tracing-subscriber</code> crate’s <code>Layer</code> trait from observing close events.
Use <ahref="trait.Subscriber.html#method.try_close"title="method tracing::Subscriber::try_close"><code>try_close</code></a> instead.</p>
<p>The default implementation of this function does nothing.</p>
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="method.try_close"class="method"><aclass="src rightside"href="../src/tracing_core/subscriber.rs.html#445">source</a><h4class="code-header">fn <ahref="#method.try_close"class="fn">try_close</a>(&self, id: <aclass="struct"href="span/struct.Id.html"title="struct tracing::span::Id">Id</a>) -><aclass="primitive"href="https://doc.rust-lang.org/1.77.2/std/primitive.bool.html">bool</a></h4></section></summary><divclass="docblock"><p>Notifies the subscriber that a <ahref="span/struct.Id.html"title="struct tracing::span::Id">span ID</a> has been dropped, and returns
<code>true</code> if there are now 0 IDs that refer to that span.</p>
<p>Higher-level libraries providing functionality for composing multiple
subscriber implementations may use this return value to notify any
“layered” subscribers that this subscriber considers the span closed.</p>
<p>The default implementation of this method calls the subscriber’s
<ahref="trait.Subscriber.html#method.drop_span"title="method tracing::Subscriber::drop_span"><code>drop_span</code></a> method and returns <code>false</code>. This means that, unless the
subscriber overrides the default implementation, close notifications
will never be sent to any layered subscribers. In general, if the
subscriber tracks reference counts, this method should be implemented,
rather than <code>drop_span</code>.</p>
<p>This function is guaranteed to only be called with span IDs that were
returned by this subscriber’s <code>new_span</code> function.</p>
<p>It’s guaranteed that if this function has been called once more than the
number of times <code>clone_span</code> was called with the same <code>id</code>, then no more
handles that can enter the span with that <code>id</code> exist. This means that it
can be used in conjunction with <ahref="trait.Subscriber.html#method.clone_span"title="method tracing::Subscriber::clone_span"><code>clone_span</code></a> to track the number of
handles capable of <code>enter</code>ing a span. When all the handles have been
dropped (i.e., <code>try_close</code> has been called one more time than
<code>clone_span</code> for a given ID), the subscriber may assume that the span
will not be entered again, and should return <code>true</code>. It is then free to
deallocate storage for data associated with that span, write data from
that span to IO, and so on.</p>
<p><strong>Note</strong>: since this function is called when spans are dropped,
implementations should ensure that they are unwind-safe. Panicking from
inside of a <code>try_close</code> function may cause a double panic, if the span
was dropped due to a thread unwinding.</p>
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="method.current_span"class="method"><aclass="src rightside"href="../src/tracing_core/subscriber.rs.html#464">source</a><h4class="code-header">fn <ahref="#method.current_span"class="fn">current_span</a>(&self) -><aclass="struct"href="../tracing_core/span/struct.Current.html"title="struct tracing_core::span::Current">Current</a></h4></section></summary><divclass="docblock"><p>Returns a type representing this subscriber’s view of the current span.</p>
<p>If subscribers track a current span, they should override this function
to return <ahref="../tracing_core/span/struct.Current.html#tymethod.new"title="struct tracing_core::span::Current"><code>Current::new</code></a> if the thread from which this method is
called is inside a span, or <ahref="../tracing_core/span/struct.Current.html#tymethod.none"title="struct tracing_core::span::Current"><code>Current::none</code></a> if the thread is not
inside a span.</p>
<p>By default, this returns a value indicating that the subscriber
does <strong>not</strong> track what span is current. If the subscriber does not
implement a current span, it should not override this method.</p>
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="method.downcast_raw"class="method"><aclass="src rightside"href="../src/tracing_core/subscriber.rs.html#495">source</a><h4class="code-header">unsafe fn <ahref="#method.downcast_raw"class="fn">downcast_raw</a>(&self, id: <aclass="struct"href="https://doc.rust-lang.org/1.77.2/core/any/struct.TypeId.html"title="struct core::any::TypeId">TypeId</a>) -><aclass="enum"href="https://doc.rust-lang.org/1.77.2/core/option/enum.Option.html"title="enum core::option::Option">Option</a><<aclass="primitive"href="https://doc.rust-lang.org/1.77.2/std/primitive.pointer.html">*const </a><aclass="primitive"href="https://doc.rust-lang.org/1.77.2/std/primitive.unit.html">()</a>></h4></section></summary><divclass="docblock"><p>If <code>self</code> is the same type as the provided <code>TypeId</code>, returns an untyped
T: <aclass="trait"href="https://doc.rust-lang.org/1.77.2/core/any/trait.Any.html"title="trait core::any::Any">Any</a>,</div></h4></section></summary><divclass="docblock"><p>Returns <code>true</code> if this <code>Subscriber</code> is the same type as <code>T</code>.</p>
T: <aclass="trait"href="https://doc.rust-lang.org/1.77.2/core/any/trait.Any.html"title="trait core::any::Any">Any</a>,</div></h4></section></summary><divclass="docblock"><p>Returns some reference to this <code>Subscriber</code> value if it is of type <code>T</code>,
T: <aclass="trait"href="https://doc.rust-lang.org/1.77.2/core/any/trait.Any.html"title="trait core::any::Any">Any</a>,</div></h4></section></summary><divclass="docblock"><p>Returns <code>true</code> if this <ahref="trait.Subscriber.html"title="trait tracing::Subscriber"><code>Subscriber</code></a> is the same type as <code>T</code>.</p>
T: <aclass="trait"href="https://doc.rust-lang.org/1.77.2/core/any/trait.Any.html"title="trait core::any::Any">Any</a>,</div></h4></section></summary><divclass="docblock"><p>Returns some reference to this <ahref="trait.Subscriber.html"title="trait tracing::Subscriber"><code>Subscriber</code></a> value if it is of type <code>T</code>,
T: <aclass="trait"href="https://doc.rust-lang.org/1.77.2/core/any/trait.Any.html"title="trait core::any::Any">Any</a>,</div></h4></section></summary><divclass="docblock"><p>Returns <code>true</code> if this <ahref="trait.Subscriber.html"title="trait tracing::Subscriber"><code>Subscriber</code></a> is the same type as <code>T</code>.</p>
T: <aclass="trait"href="https://doc.rust-lang.org/1.77.2/core/any/trait.Any.html"title="trait core::any::Any">Any</a>,</div></h4></section></summary><divclass="docblock"><p>Returns some reference to this <code>[</code>Subscriber<code>] value if it is of type </code>T<code>, or </code>None` if it isn’t.</p>
T: <aclass="trait"href="https://doc.rust-lang.org/1.77.2/core/any/trait.Any.html"title="trait core::any::Any">Any</a>,</div></h4></section></summary><divclass="docblock"><p>Returns <code>true</code> if this <ahref="trait.Subscriber.html"title="trait tracing::Subscriber"><code>Subscriber</code></a> is the same type as <code>T</code>.</p>
T: <aclass="trait"href="https://doc.rust-lang.org/1.77.2/core/any/trait.Any.html"title="trait core::any::Any">Any</a>,</div></h4></section></summary><divclass="docblock"><p>Returns some reference to this <ahref="trait.Subscriber.html"title="trait tracing::Subscriber"><code>Subscriber</code></a> value if it is of type <code>T</code>,
</div></details></div></details></div><h2id="foreign-impls"class="section-header">Implementations on Foreign Types<ahref="#foreign-impls"class="anchor">§</a></h2><detailsclass="toggle implementors-toggle"><summary><sectionid="impl-Subscriber-for-Box%3CS%3E"class="impl"><aclass="src rightside"href="../src/tracing_core/subscriber.rs.html#710-712">source</a><ahref="#impl-Subscriber-for-Box%3CS%3E"class="anchor">§</a><h3class="code-header">impl<S><aclass="trait"href="trait.Subscriber.html"title="trait tracing::Subscriber">Subscriber</a> for <aclass="struct"href="https://doc.rust-lang.org/1.77.2/alloc/boxed/struct.Box.html"title="struct alloc::boxed::Box">Box</a><S><divclass="where">where
