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 Linux 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. That link is usually how you find the step waiting on work it did not need.
• 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.

Recording requires Linux. 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 Linux 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 delivers the UI and nothing else: your browser fetches the recording from localhost and processes it in the page. Recordings do contain command lines and paths, so review one before sending it to anyone.
• Check the conformance suite. Every change records a real build with each supported build system and checks the resulting trace. (details)

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 Linux 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 needs Linux, with 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.
• Viewing needs nothing. Recordings open on any platform in the web UI, whatever they were recorded on, with Buildprof installed or not.
• Building 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.
• 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.