🛈 Note: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem.

For the release documentation, please see docs.rs, instead.

tracing_flame

Struct FlameSubscriber

Source
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>
where C: Collect + for<'span> LookupSpan<'span>, W: Write + 'static,

Source

pub fn new(writer: W) -> Self

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

Source

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.

Source

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.

Source

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.

Source

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

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

Source

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>,

Source

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§

Source§

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

Source§

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

Formats the value using the given formatter. Read more
Source§

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

Source§

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

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

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

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

fn on_register_dispatch(&self, collector: &Dispatch)

Performs late initialization when installing this subscriber as a collector. Read more
Source§

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

Performs late initialization when attaching a subscriber to a collector. Read more
Source§

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. Read more
Source§

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. Read more
Source§

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.
Source§

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.
Source§

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.
Source§

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

Called before on_event, to determine if on_event should be called. Read more
Source§

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

Notifies this subscriber that an event has occurred.
Source§

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

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

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.
Source§

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. Read more
Source§

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. Read more
Source§

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. Read more
Source§

fn boxed(self) -> Box<dyn Subscribe<C> + Sync + Send>
where Self: Sized + Subscribe<C> + Send + Sync + 'static, C: Collect,

Erases the type of this subscriber, returning a Boxed dyn Subscribe trait object. Read more

Auto Trait Implementations§

§

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

§

impl<C, W> RefUnwindSafe for FlameSubscriber<C, W>
where C: RefUnwindSafe,

§

impl<C, W> Send for FlameSubscriber<C, W>
where C: Send, W: Send,

§

impl<C, W> Sync for FlameSubscriber<C, W>
where C: Sync, W: Send,

§

impl<C, W> Unpin for FlameSubscriber<C, W>
where C: Unpin,

§

impl<C, W> UnwindSafe for FlameSubscriber<C, W>
where C: UnwindSafe,

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<T> WithCollector for T

Source§

fn with_collector<C>(self, collector: C) -> WithDispatch<Self>
where C: Into<Dispatch>,

Attaches the provided collector to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_collector(self) -> WithDispatch<Self>

Attaches the current default collector to this type, returning a WithDispatch wrapper. Read more