Struct tracing_tunnel::TracingEventReceiver
source · pub struct TracingEventReceiver { /* private fields */ }receiver only.Expand description
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§
source§impl TracingEventReceiver
impl TracingEventReceiver
sourcepub fn new(
metadata: PersistedMetadata,
spans: PersistedSpans,
local_spans: LocalSpans
) -> Self
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().
sourcepub fn try_receive(&mut self, event: TracingEvent) -> Result<(), ReceiveError>
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).
sourcepub fn receive(&mut self, event: TracingEvent)
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.
sourcepub fn persist_metadata(&self) -> PersistedMetadata
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().
sourcepub fn persist(self) -> (PersistedSpans, LocalSpans)
pub fn persist(self) -> (PersistedSpans, LocalSpans)
Returns persisted and local spans.