Struct FlamegraphConfig

pub struct FlamegraphConfig(/* private fields */);

Available on crate feature default only.

The FlamegraphConfig which allows the customization of the created flamegraphs

Callgrind flamegraphs are very similar to callgrind_annotate output. In contrast to callgrind_annotate text based output, the produced flamegraphs are svg files (located in the target/iai directory) which can be viewed in a browser.

Experimental

Note the following considerations only affect flamegraphs of multi-threaded/multi-process benchmarks and benchmarks which produce multiple parts with a total over all sub-metrics.

Currently, Iai-Callgrind creates the flamegraphs only for the total over all threads/parts and subprocesses. This leads to complications since the call graph is not be fully recovered just by examining each thread/subprocess separately. So, the total metrics in the flamegraphs might not be the same as the total metrics shown in the terminal output. If in doubt, the terminal output shows the the correct metrics.

Examples

use iai_callgrind::{LibraryBenchmarkConfig, FlamegraphConfig, main};
main!(
    config = LibraryBenchmarkConfig::default()
                .flamegraph(FlamegraphConfig::default());
    library_benchmark_groups = some_group
);

Implementations

impl FlamegraphConfig

pub fn kind(&mut self, kind: FlamegraphKind) -> &mut Self

Option to change the FlamegraphKind

The default is FlamegraphKind::All.

Examples

For example, to only create a differential flamegraph:

use iai_callgrind::{FlamegraphConfig, FlamegraphKind};

let config = FlamegraphConfig::default().kind(FlamegraphKind::Differential);

pub fn negate_differential(&mut self, negate_differential: bool) -> &mut Self

Negate the differential flamegraph FlamegraphKind::Differential

The default is false.

Instead of showing the differential flamegraph from the viewing angle of what has happened the negated differential flamegraph shows what will happen. Especially, this allows to see vanished event lines (in blue) for example because the underlying code has improved and removed an unnecessary function call.

See also Differential Flame Graphs from Brendan Gregg’s Blog.

Examples

use iai_callgrind::{FlamegraphConfig, FlamegraphKind};

let config = FlamegraphConfig::default().negate_differential(true);

pub fn normalize_differential( &mut self, normalize_differential: bool, ) -> &mut Self

Normalize the differential flamegraph

This’ll make the first profile event count to match the second. This’ll help in situations when everything looks read (or blue) to get a balanced profile with the full red/blue spectrum

Examples

use iai_callgrind::{FlamegraphConfig, FlamegraphKind};

let config = FlamegraphConfig::default().normalize_differential(true);

pub fn event_kinds<T>(&mut self, event_kinds: T) -> &mut Self

where T: IntoIterator<Item = EventKind>,

One or multiple EventKind for which a flamegraph is going to be created.

The default is EventKind::Ir

Currently, flamegraph creation is limited to one flamegraph for each EventKind and there’s no way to merge all event kinds into a single flamegraph.

Note it is an error to specify a EventKind which isn’t recorded by callgrind. See the docs of the variants of EventKind which callgrind option is needed to create a record for it. See also the Callgrind Documentation. The EventKinds recorded by callgrind which are available as long as the cache simulation is turned on with --cache-sim=yes (which is the default):

• EventKind::Ir
• EventKind::Dr
• EventKind::Dw
• EventKind::I1mr
• EventKind::ILmr
• EventKind::D1mr
• EventKind::DLmr
• EventKind::D1mw
• EventKind::DLmw

If the cache simulation is turned on, the following derived EventKinds are also available:

• EventKind::L1hits
• EventKind::LLhits
• EventKind::RamHits
• EventKind::TotalRW
• EventKind::EstimatedCycles

Examples

use iai_callgrind::{EventKind, FlamegraphConfig};

let config =
    FlamegraphConfig::default().event_kinds([EventKind::EstimatedCycles, EventKind::Ir]);

pub fn direction(&mut self, direction: Direction) -> &mut Self

Set the Direction in which the flamegraph should grow.

The default is Direction::TopToBottom.

Examples

For example to change the default

use iai_callgrind::{Direction, FlamegraphConfig};

let config = FlamegraphConfig::default().direction(Direction::BottomToTop);

pub fn title(&mut self, title: String) -> &mut Self

Overwrite the default title of the final flamegraph

Examples

use iai_callgrind::{Direction, FlamegraphConfig};

let config = FlamegraphConfig::default().title("My flamegraph title".to_owned());

pub fn subtitle(&mut self, subtitle: String) -> &mut Self

Overwrite the default subtitle of the final flamegraph

Examples

use iai_callgrind::FlamegraphConfig;

let config = FlamegraphConfig::default().subtitle("My flamegraph subtitle".to_owned());

pub fn min_width(&mut self, min_width: f64) -> &mut Self

Set the minimum width (in pixels) for which event lines are going to be shown.

The default is 0.1

To show all events, set the min_width to 0f64.

Examples

use iai_callgrind::FlamegraphConfig;

let config = FlamegraphConfig::default().min_width(0f64);

Trait Implementations

impl AsRef<FlamegraphConfig> for FlamegraphConfig

fn as_ref(&self) -> &InternalFlamegraphConfig

Converts this type into a shared reference of the (usually inferred) input type.

impl Clone for FlamegraphConfig

fn clone(&self) -> FlamegraphConfig

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for FlamegraphConfig

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

Formats the value using the given formatter.

impl Default for FlamegraphConfig

fn default() -> FlamegraphConfig

Returns the “default value” for a type.

impl From<&FlamegraphConfig> for InternalFlamegraphConfig

fn from(value: &FlamegraphConfig) -> Self

Converts to this type from the input type.

impl From<&mut FlamegraphConfig> for InternalFlamegraphConfig

fn from(value: &mut FlamegraphConfig) -> Self

Converts to this type from the input type.

impl From<FlamegraphConfig> for InternalFlamegraphConfig

fn from(value: FlamegraphConfig) -> Self

Converts to this type from the input type.