Struct Registry

pub struct Registry { /* private fields */ }

Available on crate features registry and std only.

A shared, reusable store for spans.

A Registry is a Collect around which multiple subscribers implementing various behaviors may be added. Unlike other types implementing Collect, Registry does not actually record traces itself: instead, it collects and stores span data that is exposed to any subscribers wrapping it through implementations of the LookupSpan trait. The Registry is responsible for storing span metadata, recording relationships between spans, and tracking which spans are active and which are closed. In addition, it provides a mechanism for subscribers to store user-defined per-span data, called extensions, in the registry. This allows Subscriber-specific data to benefit from the Registry’s high-performance concurrent storage.

This registry is implemented using a lock-free sharded slab, and is highly optimized for concurrent access.

Span ID Generation

Span IDs are not globally unique, but the registry ensures that no two currently active spans have the same ID within a process.

One of the primary responsibilities of the registry is to generate span IDs. Therefore, it’s important for other code that interacts with the registry, such as subscribers, to understand the guarantees of the span IDs that are generated.

The registry’s span IDs are guaranteed to be unique at a given point in time. This means that an active span will never be assigned the same ID as another currently active span. However, the registry will eventually reuse the IDs of closed spans, although an ID will never be reassigned immediately after a span has closed.

Spans are not considered closed by the Registry until every Span reference with that ID has been dropped.

Thus: span IDs generated by the registry should be considered unique only at a given point in time, and only relative to other spans generated by the same process. Two spans with the same ID will not exist in the same process concurrently. However, if historical span data is being stored, the same ID may occur for multiple spans times in that data. If spans must be uniquely identified in historical data, the user code storing this data must assign its own unique identifiers to those spans. A counter is generally sufficient for this.

Similarly, span IDs generated by the registry are not unique outside of a given process. Distributed tracing systems may require identifiers that are unique across multiple processes on multiple machines (for example, OpenTelemetry’s SpanIds and TraceIds). tracing span IDs generated by the registry should not be used for this purpose. Instead, code which integrates with a distributed tracing system should generate and propagate its own IDs according to the rules specified by the distributed tracing system. These IDs can be associated with tracing spans using fields and/or stored span data.

Trait Implementations

impl Collect for Registry

fn record(&self, _: &Id, _: &Record<'_>)

This is intentionally not implemented, as recording fields on a span is the responsibility of subscribers atop of this registry.

fn event(&self, _: &Event<'_>)

This is intentionally not implemented, as recording events is the responsibility of subscribers atop of this registry.

fn try_close(&self, id: Id) -> bool

Decrements the reference count of the span with the given id, and removes the span if it is zero.

The allocated span slot will be reused when a new span is created.

fn register_callsite(&self, _: &'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.

fn enabled(&self, _: &Metadata<'_>) -> bool

Returns true if a span or event with the specified metadata would be recorded.

fn new_span(&self, attrs: &Attributes<'_>) -> Id

Visit the construction of a new span, returning a new span ID for the span being constructed.

fn record_follows_from(&self, _span: &Id, _follows: &Id)

Adds an indication that span follows from the span with the id follows.

fn event_enabled(&self, _event: &Event<'_>) -> bool

Determine if an Event should be recorded.

fn enter(&self, id: &Id)

Records that a span has been entered.

fn exit(&self, id: &Id)

Records that a span has been exited.

fn clone_span(&self, id: &Id) -> Id

Notifies the collector that a span ID has been cloned.

fn current_span(&self) -> Current

Returns a type representing this collector’s view of the current span.

fn on_register_dispatch(&self, collector: &Dispatch)

Invoked when this collector becomes a Dispatch.

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.

fn drop_span(&self, _id: Id)

👎Deprecated since 0.1.2: use Collector::try_close instead

This method is deprecated.

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.

impl Debug for Registry

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Registry

fn default() -> Self

Returns the “default value” for a type.

impl<'a> LookupSpan<'a> for Registry

type Data = Data<'a>

The type of span data stored in this registry.

fn span_data(&'a self, id: &Id) -> Option<Self::Data>

Returns the SpanData for a given Id, if it exists.

fn register_filter(&mut self) -> FilterId

Registers a Filter for per-subscriber filtering with this collector.

fn span(&'a self, id: &Id) -> Option<SpanRef<'_, Self>>

where Self: Sized,

Returns a SpanRef for the span with the given Id, if it exists.