Struct TracingEventReceiver

pub struct TracingEventReceiver { /* private fields */ }

Available on crate feature receiver only.

Receiver of TracingEvents produced by TracingEventSender that relays them to the tracing infrastructure.

The receiver takes care of persisting [Metadata] / spans that can outlive the lifetime of the host program (not just the TracingEventReceiver instance!). As an example, in the Tardigrade runtime, a consumer instance is created each time a workflow is executed. It relays tracing events from the workflow logic (executed in WASM) to the host.

In some cases, the execution tracked by TracingEventReceiver may finish abnormally. (E.g., a WASM module instance panics while it has the panic = abort set in the compilation options.) In these cases, all entered spans are force-exited when the receiver is dropped. Additionally, spans created by the execution are closed on drop as long as they are not persisted. That is, persistence acts as a commitment of the execution results, while the default behavior is rollback.

⚠ Resource consumption

To fit the API of the tracing-core crate, the receiver leaks string parts of CallSiteData: we need a &'static str when we only have a String. Steps are taken to limit the amount of leaked memory; we use a static string arena which checks whether a particular string was already leaked, and reuses the existing &'static str if possible. Still, this has negative implications regarding both memory consumption and performance, so you probably should limit the number of executables to use with a TracingEventReceiver. The number of executions of each executable is not a limiting factor.

Examples

See crate-level docs for an example of usage.

Implementations

impl TracingEventReceiver

pub fn new( metadata: PersistedMetadata, spans: PersistedSpans, local_spans: LocalSpans, ) -> Self

Restores the receiver from the persisted metadata and tracing spans.

A receiver will work fine if local_spans information is lost (e.g., reset to the default empty value). However, this is likely to result in span leakage in the underlying Subscriber. On the other hand, mismatch between metadata / spans and the execution producing TracingEvents is bad; it will most likely result in errors returned from Self::try_receive().

pub fn try_receive(&mut self, event: TracingEvent) -> Result<(), ReceiveError>

Tries to consume an event and relays it to the tracing infrastructure.

Errors

Fails if the event contains a bogus reference to a call site or a span, or if it contains too many values. In general, an error can mean that the consumer was restored from an incorrect persisted state, or that the event generator is bogus (e.g., not a TracingEventSender).

pub fn receive(&mut self, event: TracingEvent)

Consumes an event and relays it to the tracing infrastructure.

Panics

Panics in the same cases when Self::try_receive() returns an error.

pub fn persist_metadata(&self) -> PersistedMetadata

Persists [Metadata] produced by the previously consumed events. The returned metadata should be merged into the metadata provided to Self::new().

pub fn persist(self) -> (PersistedSpans, LocalSpans)

Returns persisted and local spans.

Trait Implementations

impl Debug for TracingEventReceiver

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

Formats the value using the given formatter.

impl Default for TracingEventReceiver

fn default() -> TracingEventReceiver

Returns the “default value” for a type.

impl Drop for TracingEventReceiver

fn drop(&mut self)

Executes the destructor for this type.