[−][src]Crate tracing_flame
A Tracing Layer for generating a folded stack trace for generating flamegraphs
and flamecharts with inferno
Overview
tracing
is a framework for instrumenting Rust programs to collect
scoped, structured, and async-aware diagnostics. tracing-flame
provides helpers
for consuming tracing
instrumentation that can later be visualized as a
flamegraph/flamechart. Flamegraphs/flamecharts are useful for identifying performance
issues bottlenecks in an application. For more details, see Brendan Gregg's post
on flamegraphs.
Usage
This crate is meant to be used in a two step process:
- Capture textual representation of the spans that are entered and exited
with
FlameLayer
. - Feed the textual representation into
inferno-flamegraph
to generate the flamegraph or flamechart.
Note: when using a buffered writer as the writer for a FlameLayer
, it is necessary to
ensure that the buffer has been flushed before the data is passed into
inferno-flamegraph
. For more details on how to flush the internal writer
of the FlameLayer
, see the docs for FlushGuard
.
Layer Setup
use std::{fs::File, io::BufWriter}; use tracing_flame::FlameLayer; use tracing_subscriber::{registry::Registry, prelude::*, fmt}; fn setup_global_subscriber() -> impl Drop { let fmt_layer = fmt::Layer::default(); let (flame_layer, _guard) = FlameLayer::with_file("./tracing.folded").unwrap(); let subscriber = Registry::default() .with(fmt_layer) .with(flame_layer); tracing::subscriber::set_global_default(subscriber).expect("Could not set global default"); _guard } // your code here ..
As an alternative, you can provide any type that implements std::io::Write
to
FlameLayer::new
.
Generating the Image
To convert the textual representation of a flamegraph to a visual one, first install inferno
:
cargo install inferno
Then, pass the file created by FlameLayer
into inferno-flamegraph
:
# flamegraph
cat tracing.folded | inferno-flamegraph > tracing-flamegraph.svg
# flamechart
cat tracing.folded | inferno-flamegraph --flamechart > tracing-flamechart.svg
Differences between flamegraph
s and flamechart
s
By default, inferno-flamegraph
creates flamegraphs. Flamegraphs operate by
that collapsing identical stack frames and sorting them on the frame's names.
This behavior is great for multithreaded programs and long-running programs where the same frames occur many times, for short durations, because it reduces noise in the graph and gives the reader a better idea of the overall time spent in each part of the application.
However, it is sometimes desirable to preserve the exact ordering of events
as they were emitted by tracing-flame
, so that it is clear when each
span is entered relative to others and get an accurate visual trace of
the execution of your program. This representation is best created with a
flamechart, which does not sort or collapse identical stack frames.
Structs
Error | The error type for |
FlameLayer | A |
FlushGuard | An RAII guard for managing flushing a global writer that is otherwise inaccessible. |