pub struct FlameSubscriber<C, W> { /* private fields */ }
Expand description
A Subscriber
that records span open/close events as folded flamegraph stack
samples.
The output of FlameSubscriber
emulates the output of commands like perf
once
they’ve been collapsed by inferno-flamegraph
. The output of this subscriber
should look similar to the output of the following commands:
perf record --call-graph dwarf target/release/mybin
perf script | inferno-collapse-perf > stacks.folded
§Sample Counts
Because tracing-flame
doesn’t use sampling, the number at the end of each
folded stack trace does not represent a number of samples of that stack.
Instead, the numbers on each line are the number of nanoseconds since the
last event in the same thread.
§Dropping and Flushing
If you use a global collector the drop implementations on your various
subscribers will not get called when your program exits. This means that if
you’re using a buffered writer as the inner writer for the FlameSubscriber
you’re not guaranteed to see all the events that have been emitted in the
file by default.
To ensure all data is flushed when the program exits, FlameSubscriber
exposes
the flush_on_drop
function, which returns a FlushGuard
. The FlushGuard
will flush the writer when it is dropped. If necessary, it can also be used to manually
flush the writer.
Implementations§
Source§impl<C, W> FlameSubscriber<C, W>
impl<C, W> FlameSubscriber<C, W>
Sourcepub fn new(writer: W) -> Self
pub fn new(writer: W) -> Self
Returns a new FlameSubscriber
that outputs all folded stack samples to the
provided writer.
Sourcepub fn flush_on_drop(&self) -> FlushGuard<W>
pub fn flush_on_drop(&self) -> FlushGuard<W>
Returns a FlushGuard
which will flush the FlameSubscriber
’s writer when
it is dropped, or when flush
is manually invoked on the guard.
Sourcepub fn with_empty_samples(self, enabled: bool) -> Self
pub fn with_empty_samples(self, enabled: bool) -> Self
Configures whether or not periods of time where no spans are entered should be included in the output.
Defaults to true
.
Setting this feature to false can help with situations where no span is active for large periods of time. This can include time spent idling, or doing uninteresting work that isn’t being measured. When a large number of empty samples are recorded, the flamegraph may be harder to interpret and navigate, since the recorded spans will take up a correspondingly smaller percentage of the graph. In some cases, a large number of empty samples may even hide spans which would otherwise appear in the flamegraph.
Sourcepub fn with_threads_collapsed(self, enabled: bool) -> Self
pub fn with_threads_collapsed(self, enabled: bool) -> Self
Configures whether or not spans from different threads should be collapsed into one pool of events.
Defaults to false
.
Setting this feature to true can help with applications that distribute work evenly across many threads, such as thread pools. In such cases it can be difficult to get an overview of where the application as a whole spent most of its time, because work done in the same span may be split up across many threads.
Sourcepub fn with_module_path(self, enabled: bool) -> Self
pub fn with_module_path(self, enabled: bool) -> Self
Configures whether or not module paths should be included in the output.
Sourcepub fn with_file_and_line(self, enabled: bool) -> Self
pub fn with_file_and_line(self, enabled: bool) -> Self
Configures whether or not file and line should be included in the output.
Source§impl<C> FlameSubscriber<C, BufWriter<File>>where
C: Collect + for<'span> LookupSpan<'span>,
impl<C> FlameSubscriber<C, BufWriter<File>>where
C: Collect + for<'span> LookupSpan<'span>,
Trait Implementations§
Source§impl<C, W> Subscribe<C> for FlameSubscriber<C, W>
impl<C, W> Subscribe<C> for FlameSubscriber<C, W>
Source§fn on_enter(&self, id: &Id, ctx: Context<'_, C>)
fn on_enter(&self, id: &Id, ctx: Context<'_, C>)
Source§fn on_exit(&self, id: &Id, ctx: Context<'_, C>)
fn on_exit(&self, id: &Id, ctx: Context<'_, C>)
Source§fn on_register_dispatch(&self, collector: &Dispatch)
fn on_register_dispatch(&self, collector: &Dispatch)
Source§fn on_subscribe(&mut self, collector: &mut C)
fn on_subscribe(&mut self, collector: &mut C)
Source§fn register_callsite(&self, metadata: &'static Metadata<'static>) -> Interest
fn register_callsite(&self, metadata: &'static Metadata<'static>) -> Interest
Collect::register_callsite
. Read moreSource§fn enabled(&self, metadata: &Metadata<'_>, ctx: Context<'_, C>) -> bool
fn enabled(&self, metadata: &Metadata<'_>, ctx: Context<'_, C>) -> bool
true
if this subscriber is interested in a span or event with the
given metadata
in the current Context
, similarly to
Collect::enabled
. Read moreSource§fn on_new_span(&self, attrs: &Attributes<'_>, id: &Id, ctx: Context<'_, C>)
fn on_new_span(&self, attrs: &Attributes<'_>, id: &Id, ctx: Context<'_, C>)
Attributes
and Id
.Source§fn on_record(&self, _span: &Id, _values: &Record<'_>, _ctx: Context<'_, C>)
fn on_record(&self, _span: &Id, _values: &Record<'_>, _ctx: Context<'_, C>)
Id
recorded the given
values
.Source§fn on_follows_from(&self, _span: &Id, _follows: &Id, _ctx: Context<'_, C>)
fn on_follows_from(&self, _span: &Id, _follows: &Id, _ctx: Context<'_, C>)
span
recorded that it
follows from the span with the ID follows
.Source§fn on_event(&self, _event: &Event<'_>, _ctx: Context<'_, C>)
fn on_event(&self, _event: &Event<'_>, _ctx: Context<'_, C>)
Source§fn on_close(&self, _id: Id, _ctx: Context<'_, C>)
fn on_close(&self, _id: Id, _ctx: Context<'_, C>)
Source§fn on_id_change(&self, _old: &Id, _new: &Id, _ctx: Context<'_, C>)
fn on_id_change(&self, _old: &Id, _new: &Id, _ctx: Context<'_, C>)
Source§fn and_then<S>(self, subscriber: S) -> Layered<S, Self, C>
fn and_then<S>(self, subscriber: S) -> Layered<S, Self, C>
Layered
struct implementing Subscribe
. Read more