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.

Compiler support: requires rustc 1.42+

Usage

This crate is meant to be used in a two step process:

1. Capture textual representation of the spans that are entered and exited with FlameLayer.
2. 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:

cat tracing.folded | inferno-flamegraph > tracing-flamegraph.svg

cat tracing.folded | inferno-flamegraph --flamechart > tracing-flamechart.svg

Differences between flamegraphs and flamecharts

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.

Supported Rust Versions

Tracing is built against the latest stable release. The minimum supported version is 1.42. The current Tracing version is not guaranteed to build on Rust versions earlier than the minimum supported version.

Tracing follows the same compiler support policies as the rest of the Tokio project. The current stable Rust compiler and the three most recent minor versions before it will always be supported. For example, if the current stable compiler version is 1.45, the minimum supported version will not be increased past 1.42, three minor versions prior. Increasing the minimum supported compiler version is not considered a semver breaking change as long as doing so complies with this policy.

Structs

Error

The error type for tracing-flame

FlameLayer

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

FlushGuard

An RAII guard for managing flushing a global writer that is otherwise inaccessible.