Skip to content
rusthacks.dev
Performance

Cargo Flamegraph on Linux and Macos Setup Steps Step by Step

Generate a flamegraph from a Rust program on Linux or macOS: install, enable symbols, allow perf access, record and read the SVG, and fix the empty-graph problems.

2 min read
Summarize in AI
Flat illustration for the post “Cargo Flamegraph on Linux and Macos Setup Steps Step by Step”, composed around perf.

A flamegraph shows in one picture where a program spends its time. Generating one for a Rust binary is five minutes of setup the first time and one command afterward. Most failures are the same three: no symbols, no permission to sample, or a program that exits too quickly. This post walks through the setup for Linux and macOS. It supports the profiling guide.

flamegraph 0.6, Rust 1.90.

Install

Shell
cargo install flamegraph

On Linux install perf first: sudo apt install linux-perf or the package for your kernel (linux-tools-generic on Ubuntu). macOS needs the Xcode command line tools for dtrace.

Keep symbols in release

Cargo.tomlTOML
[profile.release]
debug = "line-tables-only"

This leaves optimization alone and records function names and line numbers.

Allow sampling on Linux

Shell
sudo sysctl kernel.perf_event_paranoid=1
sudo sysctl kernel.kptr_restrict=0

These settings let a normal user sample. They reset on reboot unless written to /etc/sysctl.d/. Without them perf fails with Access to performance monitoring and observability operations is limited. In a container, add --cap-add SYS_ADMIN or run perf on the host; profiling inside Docker needs the capability and a matching perf binary.

Record

A program worth profiling:

rust
use std::collections::HashMap;

fn main() {
    let mut counts: HashMap<String, usize> = HashMap::new();
    for i in 0..5_000_000u32 {
        let key = format!("key{}", i % 1000);
        *counts.entry(key).or_insert(0) += 1;
    }
    println!("{}", counts.len());
}
Shell
cargo flamegraph --bin demo

The tool builds in release, runs under the profiler and writes flamegraph.svg. On macOS add sudo, or cargo flamegraph --root. Pass arguments to your program after --: cargo flamegraph --bin demo -- data.csv.

Read it

For this example, the widest frames will be alloc::fmt::format and the malloc family under it, then the HashMap entry call. That tells you the key construction is the cost, and the fix is to avoid building a String for each lookup: look up with a &str, or intern keys. The reading rules are in the profiling guide.

Click a box to zoom to it, use the search box to highlight a name, and read widths as share of time. Colors are only for contrast.

Troubleshooting

SymptomFix
Frames are hex addressesadd debug = "line-tables-only"
perf permission errorperf_event_paranoid as above
Graph has only _start and mainthe program is too short; loop the work
Inlined functions missingexpected in release; they are attributed to their caller
Async code shows mostly runtime framesenable tokio task names or use tokio-console

Alternatives

samply record ./target/release/demo opens the Firefox Profiler with a timeline and works on macOS without sudo. perf record plus perf report gives a text view. cargo-instruments integrates with Xcode on macOS. The tool is documented in the flamegraph-rs repository.

Also inTooling
Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.