Struct tracing_flame::FlameSubscriber

pub struct FlameSubscriber<C, W> { /* private fields */ }

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

impl<C, W> FlameSubscriber<C, W>

where C: Collect + for<'span> LookupSpan<'span>, W: Write + 'static,

pub fn new(writer: W) -> Self

Returns a new FlameSubscriber that outputs all folded stack samples to the provided writer.

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.

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.

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.

pub fn with_module_path(self, enabled: bool) -> Self

Configures whether or not module paths should be included in the output.

pub fn with_file_and_line(self, enabled: bool) -> Self

Configures whether or not file and line should be included in the output.

impl<C> FlameSubscriber<C, BufWriter<File>>

where C: Collect + for<'span> LookupSpan<'span>,

pub fn with_file( path: impl AsRef<Path> ) -> Result<(Self, FlushGuard<BufWriter<File>>), Error>

Constructs a FlameSubscriber that outputs to a BufWriter to the given path, and a FlushGuard to ensure the writer is flushed.

Trait Implementations

impl<C: Debug, W: Debug> Debug for FlameSubscriber<C, W>

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

Formats the value using the given formatter.

impl<C, W> Subscribe<C> for FlameSubscriber<C, W>

where C: Collect + for<'span> LookupSpan<'span>, W: Write + 'static,

fn on_enter(&self, id: &Id, ctx: Context<'_, C>)

Notifies this subscriber that a span with the given ID was entered.

fn on_exit(&self, id: &Id, ctx: Context<'_, C>)

Notifies this subscriber that the span with the given ID was exited.

fn on_register_dispatch(&self, collector: &Dispatch)

Performs late initialization when installing this subscriber as a collector.

fn on_subscribe(&mut self, collector: &mut C)

Performs late initialization when attaching a subscriber to a collector.

fn register_callsite(&self, metadata: &'static Metadata<'static>) -> Interest

Registers a new callsite with this subscriber, returning whether or not the subscriber is interested in being notified about the callsite, similarly to Collect::register_callsite.

fn enabled(&self, metadata: &Metadata<'_>, ctx: Context<'_, C>) -> bool

Returns true if this subscriber is interested in a span or event with the given metadata in the current Context, similarly to Collect::enabled.

fn on_new_span(&self, attrs: &Attributes<'_>, id: &Id, ctx: Context<'_, C>)

Notifies this subscriber that a new span was constructed with the given Attributes and Id.

fn on_record(&self, _span: &Id, _values: &Record<'_>, _ctx: Context<'_, C>)

Notifies this subscriber that a span with the given Id recorded the given values.

fn on_follows_from(&self, _span: &Id, _follows: &Id, _ctx: Context<'_, C>)

Notifies this subscriber that a span with the ID span recorded that it follows from the span with the ID follows.

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

Called before on_event, to determine if on_event should be called.

fn on_event(&self, _event: &Event<'_>, _ctx: Context<'_, C>)

Notifies this subscriber that an event has occurred.

fn on_close(&self, _id: Id, _ctx: Context<'_, C>)

Notifies this subscriber that the span with the given ID has been closed.

fn on_id_change(&self, _old: &Id, _new: &Id, _ctx: Context<'_, C>)

Notifies this subscriber that a span ID has been cloned, and that the subscriber returned a different ID.

fn and_then<S>(self, subscriber: S) -> Layered<S, Self, C>

where S: Subscribe<C>, Self: Sized,

Composes this subscriber around the given collector, returning a Layered struct implementing Subscribe.

fn with_collector(self, inner: C) -> Layered<Self, C>

where Self: Sized,

Composes this subscriber with the given collector, returning a Layered struct that implements Collect.

fn with_filter<F>(self, filter: F) -> Filtered<Self, F, C>

where Self: Sized, F: Filter<C>,

Combines self with a Filter, returning a Filtered subscriber.