Trait Collect
pub trait Collect: 'static {
Show 16 methods
// Required methods
fn enabled(&self, metadata: &Metadata<'_>) -> bool;
fn new_span(&self, span: &Attributes<'_>) -> Id;
fn record(&self, span: &Id, values: &Record<'_>);
fn record_follows_from(&self, span: &Id, follows: &Id);
fn event(&self, event: &Event<'_>);
fn enter(&self, span: &Id);
fn exit(&self, span: &Id);
fn current_span(&self) -> Current;
// Provided methods
fn on_register_dispatch(&self, collector: &Dispatch) { ... }
fn register_callsite(
&self,
metadata: &'static Metadata<'static>,
) -> Interest { ... }
fn max_level_hint(&self) -> Option<LevelFilter> { ... }
fn event_enabled(&self, event: &Event<'_>) -> bool { ... }
fn clone_span(&self, id: &Id) -> Id { ... }
fn drop_span(&self, _id: Id) { ... }
fn try_close(&self, id: Id) -> bool { ... }
unsafe fn downcast_raw(&self, id: TypeId) -> Option<NonNull<()>> { ... }
}
Expand description
Trait representing the functions required to collect trace data.
Crates that provide implementations of methods for collecting or recording
trace data should implement the Collect
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
collector implementations more modular or improve the ergonomics of writing
collectors.
A collector is responsible for the following:
- Registering new spans as they are created, and providing them with span IDs. Implicitly, this means the collector may determine the strategy for determining span equality.
- Recording the attachment of field values and follows-from annotations to spans.
- Filtering spans and events, and determining when those filters must be invalidated.
- Observing spans as they are entered, exited, and closed, and events as they occur.
When a span is entered or exited, the collector is provided only with the
ID with which it tagged that span when it was created. This means
that it is up to the collector to determine whether and how span data —
the fields and metadata describing the span — should be stored. The
new_span
function is called when a new span is created, and at that
point, the collector may 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 enter
and exit
, the collector
may freely discard that data without allocating space to store it.
§Overriding default impls
Some trait methods on Collect
have default implementations, either in
order to reduce the surface area of implementing Collect
, or for
backward-compatibility reasons. However, many collectors will likely want
to override these default implementations.
The following methods are likely of interest:
-
register_callsite
is called once for each callsite from which a span event may originate, and returns anInterest
value describing whether or not the collector wishes to see events or spans from that callsite. By default, it callsenabled
, and returnsInterest::always()
ifenabled
returns true, orInterest::never()
if enabled returns false. However, if the collector’s interest can change dynamically at runtime, it may want to override this function to returnInterest::sometimes()
. Additionally, collectors which wish to perform a behaviour once for each callsite, such as allocating storage for data related to that callsite, can perform it inregister_callsite
.See also the documentation on the callsite registry for details on
register_callsite
. -
event_enabled
is called once before every call to theevent
method. This can be used to implement filtering on events once their field values are known, but before any processing is done in theevent
method. -
clone_span
is called every time a span ID is cloned, andtry_close
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 collectors to free storage for span data and to determine when a span has closed permanently (rather than being exited). Collectors which store per-span data or which need to track span closures should override these functions together.
Required Methods§
fn enabled(&self, metadata: &Metadata<'_>) -> bool
fn enabled(&self, metadata: &Metadata<'_>) -> bool
Returns true if a span or event with the specified metadata would be recorded.
By default, it is assumed that this filter needs only be evaluated once
for each callsite, so it is called by register_callsite
when each
callsite is registered. The result is used to determine if the collector
is always interested 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.
However, if the collector’s interest in a particular span or event may
change, or depends on contexts only determined dynamically at runtime,
then the register_callsite
method should be overridden to return
Interest::sometimes
. In that case, this function will be called every
time that span or event occurs.
fn new_span(&self, span: &Attributes<'_>) -> Id
fn new_span(&self, span: &Attributes<'_>) -> Id
Visit the construction of a new span, returning a new span ID for the span being constructed.
The provided Attributes
contains any field values that were provided
when the span was created. The collector may pass a visitor to the
Attributes
’ record
method to record these values.
IDs are used to uniquely identify spans and events within the context of a collector, so span equality will be based on the returned ID. Thus, if the collector 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 not be equal, it should return a distinct ID every time this function is called, regardless of the metadata.
Note that the collector 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 collector implementation to determine.
fn record(&self, span: &Id, values: &Record<'_>)
fn record(&self, span: &Id, values: &Record<'_>)
Record a set of values on a span.
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 collector implementation.
Keep in mind that a span might not provide a value for each field it declares.
The collector is expected to provide a visitor to the Record
’s
record
method in order to record the added values.
§Example
“foo = 3” will be recorded when record
is called on the
Attributes
passed to new_span
.
Since values are not provided for the bar
and baz
fields,
the span’s Metadata
will indicate that it has those fields,
but values for them won’t be recorded at this time.
let mut span = span!("my_span", foo = 3, bar, baz);
// `Collector::record` will be called with a `Record`
// containing "bar = false"
span.record("bar", &false);
// `Collector::record` will be called with a `Record`
// containing "baz = "a string""
span.record("baz", &"a string");
fn record_follows_from(&self, span: &Id, follows: &Id)
fn record_follows_from(&self, span: &Id, follows: &Id)
Adds an indication that span
follows from the span with the id
follows
.
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 inside 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.
If the collector 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 collector knows about, or if a cyclical relationship would be created (i.e., some span a which proceeds some other span b may not also follow from b), it may silently do nothing.
fn event(&self, event: &Event<'_>)
fn event(&self, event: &Event<'_>)
Records that an Event
has occurred.
This method will be invoked when an Event is constructed by
the Event
’s dispatch
method. For example, this happens internally
when an event macro from tracing
is called.
The key difference between this method and record
is that record
is
called when a value is recorded for a field defined by a span,
while event
is called when a new event occurs.
The provided Event
struct contains any field values attached to the
event. The collector may pass a visitor to the Event
’s
record
method to record these values.
fn enter(&self, span: &Id)
fn enter(&self, span: &Id)
Records that a span has been entered.
When entering a span, this method is called to notify the collector that the span has been entered. The collector is provided with the span ID of the entered span, and should update any internal state tracking the current span accordingly.
fn exit(&self, span: &Id)
fn exit(&self, span: &Id)
Records that a span has been exited.
When exiting a span, this method is called to notify the collector that the span has been exited. The collector is provided with the span ID of the exited span, and should update any internal state tracking the current span accordingly.
Exiting a span does not imply that the span will not be re-entered.
fn current_span(&self) -> Current
fn current_span(&self) -> Current
Returns a type representing this collector’s view of the current span.
If collectors track a current span, they should return Current::new
if the thread from which this method is called is inside a span,
or Current::none
if the thread is not inside a span.
Provided Methods§
fn on_register_dispatch(&self, collector: &Dispatch)
fn on_register_dispatch(&self, collector: &Dispatch)
Invoked when this collector becomes a Dispatch
.
§Avoiding Memory Leaks
Collectors should not store their own Dispatch
. Because the
Dispatch
owns the collector, storing the Dispatch
within the
collector will create a reference count cycle, preventing the Dispatch
from ever being dropped.
Instead, when it is necessary to store a cyclical reference to the
Dispatch
within a collector, use Dispatch::downgrade
to convert a
Dispatch
into a WeakDispatch
. This type is analogous to
std::sync::Weak
, and does not create a reference count cycle. A
WeakDispatch
can be stored within a collector without causing a
memory leak, and can be upgraded into a Dispatch
temporarily when
the Dispatch
must be accessed by the collector.
fn register_callsite(&self, metadata: &'static Metadata<'static>) -> Interest
fn register_callsite(&self, metadata: &'static Metadata<'static>) -> Interest
Registers a new callsite with this collector, returning whether or not the collector is interested in being notified about the callsite.
By default, this function assumes that the collector’s filter represents an unchanging view of its interest in the callsite. However, if this is not the case, collectors may override this function to indicate different interests, or to implement behaviour that should run once for every callsite.
This function is guaranteed to be called at least once per callsite on every active collector. The collector 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.
The collector should then return an Interest
, indicating
whether it is interested in being notified about that callsite in the
future. This may be Always
indicating that the collector always
wishes to be notified about the callsite, and its filter need not be
re-evaluated; Sometimes
, indicating that the collector may sometimes
care about the callsite but not always (such as when sampling), or
Never
, indicating that the collector never wishes to be notified about
that callsite. If all active collectors return Never
, a callsite will
never be enabled unless a new collector expresses interest in it.
Collector
s which require their filters to be run every time an event
occurs or a span is entered/exited should return Interest::sometimes
.
If a collector returns Interest::sometimes
, then its’ enabled
method
will be called every time an event or span is created from that callsite.
For example, suppose a sampling collector is implemented by
incrementing a counter every time enabled
is called and only returning
true
when the counter is divisible by a specified sampling rate. If
that collector returns Interest::always
from register_callsite
, 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 enabled
.
Collector
s that need to change their filters occasionally should call
rebuild_interest_cache
to re-evaluate register_callsite
for all
callsites.
Similarly, if a Collector
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.
A collector which manages fanout to multiple other collectors
should proxy this decision to all of its child collectors,
returning Interest::never
only if all such children return
Interest::never
. If the set of collectors to which spans are
broadcast may change dynamically, the collector should also never
return Interest::Never
, as a new collector may be added that is
interested.
See the documentation on the callsite registry for more
details on how and when the register_callsite
method is called.
§Notes
This function may be called again when a new collector is created or when the registry is invalidated.
If a collector returns Interest::never
for a particular callsite, it
may still see spans and events originating from that callsite, if
another collector expressed interest in it.
fn max_level_hint(&self) -> Option<LevelFilter>
fn max_level_hint(&self) -> Option<LevelFilter>
Returns the highest verbosity level that this Collector
will
enable, or None
, if the collector does not implement level-based
filtering or chooses not to implement this method.
If this method returns a Level
, 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. collectors which perform filtering are strongly
encouraged to provide an implementation of this method.
If the maximum level the collector 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 only be reflected after the callsite Interest
cache is rebuilt, by calling the callsite::rebuild_interest_cache
function. Therefore, if the collector will change the value returned by
this method, it is responsible for ensuring that
rebuild_interest_cache
is called after the value of the max
level changes.
fn event_enabled(&self, event: &Event<'_>) -> bool
fn event_enabled(&self, event: &Event<'_>) -> bool
fn clone_span(&self, id: &Id) -> Id
fn clone_span(&self, id: &Id) -> Id
Notifies the collector that a span ID has been cloned.
This function is guaranteed to only be called with span IDs that were
returned by this collector’s new_span
function.
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 try_close
to track the number of handles
capable of enter
ing a span. When all the handles have been dropped
(i.e., try_close
has been called one more time than clone_span
for a
given ID), the collector 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.
For more unsafe situations, however, if id
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.
fn drop_span(&self, _id: Id)
👎Deprecated since 0.1.2: use Collector::try_close
instead
fn drop_span(&self, _id: Id)
Collector::try_close
insteadThis method is deprecated.
Using drop_span
may result in collectors composed using
tracing-subscriber
crate’s Subscriber
trait from observing close events.
Use try_close
instead.
The default implementation of this function does nothing.
fn try_close(&self, id: Id) -> bool
fn try_close(&self, id: Id) -> bool
Notifies the collector that a span ID
has been dropped, and returns
true
if there are now 0 IDs that refer to that span.
Higher-level libraries providing functionality for composing multiple collector implementations may use this return value to notify any “layered” collectors that this collector considers the span closed.
The default implementation of this method calls the collector’s
drop_span
method and returns false
. This means that, unless the
collector overrides the default implementation, close notifications
will never be sent to any layered collectors. In general, if the
collector tracks reference counts, this method should be implemented,
rather than drop_span
.
This function is guaranteed to only be called with span IDs that were
returned by this collector’s new_span
function.
It’s guaranteed that if this function has been called once more than the
number of times clone_span
was called with the same id
, then no more
handles that can enter the span with that id
exist. This means that it
can be used in conjunction with clone_span
to track the number of
handles capable of enter
ing a span. When all the handles have been
dropped (i.e., try_close
has been called one more time than
clone_span
for a given ID), the collector may assume that the span
will not be entered again, and should return true
. It is then free to
deallocate storage for data associated with that span, write data from
that span to IO, and so on.
Note: since this function is called when spans are dropped,
implementations should ensure that they are unwind-safe. Panicking from
inside of a try_close
function may cause a double panic, if the span
was dropped due to a thread unwinding.
unsafe fn downcast_raw(&self, id: TypeId) -> Option<NonNull<()>>
unsafe fn downcast_raw(&self, id: TypeId) -> Option<NonNull<()>>
If self
is the same type as the provided TypeId
, returns an untyped
NonNull
pointer to that type. Otherwise, returns None
.
If you wish to downcast a Collector
, it is strongly advised to use
the safe API provided by downcast_ref
instead.
This API is required for downcast_raw
to be a trait method; a method
signature like downcast_ref
(with a generic type parameter) is not
object-safe, and thus cannot be a trait method for Collector
. This
means that if we only exposed downcast_ref
, Collector
implementations could not override the downcasting behavior
This method may be overridden by “fan out” or “chained” collector
implementations which consist of multiple composed types. Such
collectors might allow downcast_raw
by returning references to those
component if they contain components with the given TypeId
.
§Safety
The downcast_ref
method expects that the pointer returned by
downcast_raw
points to a valid instance of the type
with the provided TypeId
. Failure to ensure this will result in
undefined behaviour, so implementing downcast_raw
is unsafe.