Struct tracing_tunnel::TracingEventReceiver
source · pub struct TracingEventReceiver { /* private fields */ }
receiver
only.Expand description
Receiver of TracingEvent
s 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 TracingEvent
s 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.