Buildprof

See where the time went in your build.

Quick start · Try the demo · Features · Install · Documentation

What is Buildprof?

Buildprof traces every process a build launches and turns the recording into an interactive timeline you can explore in the browser. Put buildprof -- in front of your build command to get started.

• See the whole build. Every command the build ran, however it was launched, with its command line, working directory, exit status, and place in the process tree.
• Follow the files. File opens and renames are recorded alongside the processes, so the recording links a file's producer to everything that consumed it. This shows when a step waits for another step whose output it never reads.
• Whatever your build system. Buildprof follows processes rather than build systems, so Make, Ninja, CMake, Meson, Cargo, Go, npm, Bazel and Buck2 all work, as do the shell scripts, code generators and wrapper scripts they launch. Every change is tested by recording a real build with each of them on Linux; the build systems page lists what each test covers.

Recording requires Linux or macOS. You can explore recordings on any platform in the web UI; trace data stays in your browser.

Try it in your browser

Explore a clean ripgrep release build without installing anything. Click the screenshot to open the recording, or follow the guided tour.

Quick start

1. Install Buildprof

On the machine that runs your build:

curl -fsSL https://buildprof.lalitm.com/install.sh | sh

Prefer a package manager? See Install for Homebrew, mise, Cargo, and Linux packages.

2. Record a build

In your project directory, put buildprof -- in front of your usual build command:

buildprof -- make -j8

Replace make -j8 with your build command, such as cargo build or ninja -C out. Bazel, Gradle and Docker hand work to a daemon, which needs a little more care.

3. Explore the recording

When the build finishes, the recording is saved as output.buildprof and opens in your browser. Allow the one-time prompt to access other apps and services on this device: that is the page fetching the recording from localhost. Nothing is ever uploaded.

Start with the longest commands and gaps in parallelism. The investigation guide walks through finding bottlenecks, following file dependencies, and checking whether a change helped.

Features

• Look inside compilers. --compiler-traces records what a compiler did internally, as per-thread phase tracks under the process that produced them, so you can go from "this rustc took 40 seconds" to which part of it did. (details)
  • Clang -ftime-trace: parsing, template instantiation, optimisation.
  • LLD --time-trace, when the build selects LLD explicitly.
  • Nightly Rust self-profile data, per compiler query.
• Record in CI. The GitHub Action records a build and attaches the recording to the job summary, including when the build fails, which is the quickest way to find out why CI is slower than your laptop. (details)
• Record over SSH. On a build host there is no browser to launch, so Buildprof prints the port forward to run from your own machine and waits for it. (details)
• Turn collection down. --no-file-events keeps the process timeline and skips filesystem interception entirely, for builds where that overhead matters. (details)
• Keep your build to yourself. buildprof.lalitm.com only serves the UI. Your browser loads the recording from your own machine and processes it in the page, so the recording stays on your machine. A recording contains command lines and paths, so review it before sending it to anyone.

Why use Buildprof?

Build tools generally explain only the work they manage themselves:

• Cargo timings cannot break down an arbitrary build.rs script.
• Ninja cannot see inside the commands it launches.
• Compiler traces describe a single compiler invocation rather than the build around it.

Buildprof follows the complete process tree instead, so the build system, compilers, linkers, code generators and whatever else the build launches all land in one timeline, and you can see how their work fits together.

Install

Install on your build machine using whichever method you prefer.

Shell installer

curl -fsSL https://buildprof.lalitm.com/install.sh | sh

Homebrew, mise, or Cargo

brew install lalitmaganti/tap/buildprof
mise use -g github:LalitMaganti/buildprof
cargo install --locked buildprof          # builds from source; needs Rust 1.91 or newer

Debian, Ubuntu, Fedora, and other .deb or .rpm distributions

Download the package for your architecture from the latest release:

apt install ./buildprof_*.deb
dnf install ./buildprof-*.rpm

Tarballs

The release page carries prebuilt binaries for x86_64 and aarch64 Linux, both glibc and static musl. The musl build is the one to mount into a container.

Requirements

• Recording on Linux needs a kernel and container configuration that permits tracing child processes:
  • Docker needs --cap-add SYS_PTRACE.
  • kernel.yama.ptrace_scope must be below 3.
  • gVisor-style sandboxes cannot trace at all.
• Recording on macOS needs macOS 13 or newer. Buildprof asks for your password through sudo, and gives up root before your build starts. The root policy says what runs as root.
• Viewing just needs a browser. Any recording opens in the web UI on any computer, with or without Buildprof installed.
• Compiling Buildprof from source needs Rust 1.91 or newer.

Documentation

• Reading a recording:
  • Investigation guide: finding bottlenecks, following dependencies, and checking whether a change helped.
  • Guided tour: the example recording, explained.
• Recording one:
  • Recording and opening builds: GitHub Actions, remote machines, collection options, compiler details.
  • Build systems: what the conformance suite covers.
  • Troubleshooting: daemon build systems and containers.
  • Data loss: what a recording can miss and how you can tell.
• Under the hood:
  • How it works: tracing, the trace format, its compatibility rules, and self-hosting the UI.
  • CONTRIBUTING.md: building, testing, and the UI workflow.

License

Licensed under the Apache License, Version 2.0. See LICENSE and AUTHORS.