Callsites represent the source locations from which spans or events originate.
Every span or event in
tracing is associated with a
callsite is a small
static value that is responsible for the following:
- Storing the span or event’s
- Uniquely identifying the span or event definition,
- Caching the collector’s
Interest1 in that span or event, to avoid re-evaluating filters,
- Storing a
Registrationthat allows the callsite to be part of a global list of all callsites in the program.
When a span or event is recorded for the first time, its callsite
registers itself with the global callsite registry. Registering a
callsite calls the
method with that callsite’s
Metadata on every currently active
collector. This serves two primary purposes: informing collectors of the
callsite’s existence, and performing static filtering.
Collect 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 returns an
which indicates that the collector 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
Interests returned by every
currently active collector 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
Collect::enabled method every time a span or event occurs).
When a new
Dispatch is created (i.e. a new collector becomes
active), any previously cached
Interest values are re-evaluated
for all callsites in the program. This way, if the new collector
will enable a callsite that was not previously enabled, the
Interest in that callsite is updated. Similarly, when a
collector is dropped, the interest cache is also re-evaluated, so
that any callsites enabled only by that collector 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 collector’s
interest can change, but it does so relatively infrequently. The collector
may wish for its interest to be cached most of the time, and return
Interest::never in its
register_callsite method, so that its
doesn’t need to be evaluated every time a span or event is recorded.
However, when the configuration changes, the collector 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