Struct tracing_flame::FlameLayer

pub struct FlameLayer<S, W> { /* fields omitted */ }

A Layer that records span open/close events as folded flamegraph stack samples.

The output of FlameLayer emulates the output of commands like perf once they've been collapsed by inferno-flamegraph. The output of this layer 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 subscriber the drop implementations on your various layers will not get called when your program exits. This means that if you're using a buffered writer as the inner writer for the FlameLayer 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, FlameLayer 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<S, W> FlameLayer<S, W> where
    S: Subscriber + for<'span> LookupSpan<'span>,
    W: Write + 'static, 

pub fn new(writer: W) -> Self

Returns a new FlameLayer 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 FlameLayer'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.

impl<S> FlameLayer<S, BufWriter<File>> where
    S: Subscriber + for<'span> LookupSpan<'span>, 

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

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

Trait Implementations

impl<S: Debug, W: Debug> Debug for FlameLayer<S, W>

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

Formats the value using the given formatter.

impl<S, W> Layer<S> for FlameLayer<S, W> where
    S: Subscriber + for<'span> LookupSpan<'span>,
    W: Write + 'static, 

fn on_enter(&self, id: &Id, ctx: Context<S>)

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

fn on_exit(&self, id: &Id, ctx: Context<S>)

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

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

Registers a new callsite with this layer, returning whether or not the layer is interested in being notified about the callsite, similarly to [Subscriber::register_callsite].

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

Returns true if this layer is interested in a span or event with the given metadata in the current [Context], similarly to [Subscriber::enabled].

fn new_span(&self, attrs: &Attributes, id: &Id, ctx: Context<S>)

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

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

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

fn on_follows_from(&self, _span: &Id, _follows: &Id, _ctx: Context<S>)

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

fn on_event(&self, _event: &Event, _ctx: Context<S>)

Notifies this layer that an event has occurred.

fn on_close(&self, _id: Id, _ctx: Context<S>)

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

fn on_id_change(&self, _old: &Id, _new: &Id, _ctx: Context<S>)

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

fn and_then<L>(self, layer: L) -> Layered<L, Self, S> where
    L: Layer<S>, 

Composes this layer around the given Layer, returning a Layered struct implementing Layer.

fn with_subscriber(self, inner: S) -> Layered<Self, S, S>

Composes this Layer with the given [Subscriber], returning a Layered struct that implements [Subscriber].