Module tracing_core::callsite
source · Expand description
Callsites represent the source locations from which spans or events originate.
§What Are Callsites?
Every span or event in tracing
is associated with a Callsite
. A
callsite is a small static
value that is responsible for the following:
- Storing the span or event’s
Metadata
, - Uniquely identifying the span or event definition,
- Caching the subscriber’s [
Interest
]1 in that span or event, to avoid re-evaluating filters.
§Registering Callsites
When a span or event is recorded for the first time, its callsite
register
s itself with the global callsite registry. Registering a
callsite calls the Subscriber::register_callsite
method with that callsite’s Metadata
on every currently active
subscriber. This serves two primary purposes: informing subscribers of the
callsite’s existence, and performing static filtering.
§Callsite Existence
If a Subscriber
implementation wishes to allocate storage for each
unique span/event location in the program, or pre-compute some value
that will be used to record that span or event in the future, it can
do so in its register_callsite
method.
§Performing Static Filtering
The register_callsite
method returns an Interest
value,
which indicates that the subscriber either always wishes to record
that span or event, sometimes wishes to record it based on a
dynamic filter evaluation, or never wishes to record it.
When registering a new callsite, the Interest
s returned by every
currently active subscriber are combined, and the result is stored at
each callsite. This way, when the span or event occurs in the
future, the cached Interest
value can be checked efficiently
to determine if the span or event should be recorded, without
needing to perform expensive filtering (i.e. calling the
Subscriber::enabled
method every time a span or event occurs).
§Rebuilding Cached Interest
When a new Dispatch
is created (i.e. a new subscriber becomes
active), any previously cached Interest
values are re-evaluated
for all callsites in the program. This way, if the new subscriber
will enable a callsite that was not previously enabled, the
Interest
in that callsite is updated. Similarly, when a
subscriber is dropped, the interest cache is also re-evaluated, so
that any callsites enabled only by that subscriber are disabled.
In addition, the rebuild_interest_cache
function in this module can be
used to manually invalidate all cached interest and re-register those
callsites. This function is useful in situations where a subscriber’s
interest can change, but it does so relatively infrequently. The subscriber
may wish for its interest to be cached most of the time, and return
Interest::always
or Interest::never
in its
register_callsite
method, so that its Subscriber::enabled
method
doesn’t need to be evaluated every time a span or event is recorded.
However, when the configuration changes, the subscriber can call
rebuild_interest_cache
to re-evaluate the entire interest cache with its
new configuration. This is a relatively costly operation, but if the
configuration changes infrequently, it may be more efficient than calling
Subscriber::enabled
frequently.
§Implementing Callsites
In most cases, instrumenting code using tracing
should not require
implementing the Callsite
trait directly. When using the tracing
crate’s macros or the #[instrument]
attribute, a
Callsite
is automatically generated.
However, code which provides alternative forms of tracing
instrumentation
may need to interact with the callsite system directly. If
instrumentation-side code needs to produce a Callsite
to emit spans or
events, the DefaultCallsite
struct provided in this module is a
ready-made Callsite
implementation that is suitable for most uses. When
possible, the use of DefaultCallsite
should be preferred over implementing
Callsite
for user types, as DefaultCallsite
may benefit from
additional performance optimizations.
Returned by the
Subscriber::register_callsite
method. ↩
Structs§
Traits§
- Trait implemented by callsites.