buildline: merging cargo and ninja's build profiling into one timeline

nabsei — Wed, 22 Jul 2026 01:43:04 +0000

Every build tool profiles its own silo. cargo build --timings will tell you cargo is fine. Ninja's build log will tell you linking is fine. And yet a CI build takes 22 minutes and nobody can point at where the time actually went, because none of these tools know the others exist.

I built buildline to fix that: it merges the profiling output your build tools already produce into one wall-clock timeline, emitted as standard Chrome Trace Event Format so it opens directly in Perfetto - no UI to build or maintain.

The gap nobody profiles

Here's the part I didn't expect going in. A tiny ninja build finishes in under a second. A real cargo build starts about 2.7 seconds later. Neither tool's own profiler records that gap — ninja doesn't know cargo exists, and cargo's own timer starts from zero the moment it launches. On a merged timeline, it's just visibly empty space, exactly where the surprise usually is in a real CI log: toolchain downloads, dependency resolution, environment setup, all invisible to every tool's own instrumentation because it happens around them, not inside them.

That's the actual thesis of the project: the interesting bottleneck in a multi-tool build is often the join between tools, not inside any one of them.

How it avoids becoming a fragile process-tree hack

The obvious design for "profile a build made of several tools" is an orchestrator that wraps the whole build and somehow intercepts every child process it spawns. I didn't want that — process interception is
platform-specific, fragile against anything that isn't a direct child
(containers, remote shells, build systems that re-exec themselves), and it turns a normalization tool into a ptrace project.

buildline wraps each tool invocation instead, correlated through a shared session file:

BUILDLINE_SESSION=./build.trace buildline -- ninja BUILDLINE_SESSION=./build.trace buildline -- cargo build
# open build.trace in <https://ui.perfetto.dev>

Each invocation is transparent — inherited stdout/stderr, the tool's real exit code passed through unchanged. buildline stamps the wall-clock instant right before it execs the wrapped command, then reads that tool's own profiling artifact after it exits (.ninja_log, cargo's --timings report), and appends the result to the shared trace file. There's no orchestration, no process-tree walking, and no finalize step — build.trace is a valid, openable Chrome Trace file after every single invocation.

The span schema, and the one design decision that matters most

pub struct Span { pub name: String, // "serde v1.0", "obj/parser.o" pub category: Category, // Compile | Link | Configure | Resolve | Download | Test | Other(String) pub status: Status, // Success | Failed | Skipped | Incomplete pub track: String, // "cargo", "ninja" — groups rows in Perfetto pub lane: u32, // sub-row for parallel work within a track pub start_us: i64, // relative to that tool's own start — no wall-clock here pub dur_us: i64, pub args: BTreeMap<String, String>, }

Every adapter is a pure function: native tool output in, a Vec<Span> out, timestamps relative to that tool's own start. The wrapper is the only thing that knows about wall-clock time — it's a thin layer that offsets each adapter's relative spans onto the shared axis. Keeping wall-clock entirely out of the adapters is what makes golden-file testing possible at all: an adapter's output is 100% deterministic, so a fixture (a real .ninja_log or --timingsreport) always produces the exact same normalized JSON, with nothing timing-dependent to make the test flaky.

Category is a closed enum, not a free-form string, on purpose.
A golden test only diffs an adapter against itself — nothing stops one adapter emitting "compile" and another emitting "Compile", each passing its own test while the "unified" timeline is silently incoherent underneath. The enum is the actual contract that makes it one timeline instead of N timelines that happen to render next to each other. Other(String) is the escape hatch for genuinely tool-specific states — cargo's run-custom-build (running an already-compiled build script, as opposed to compiling one) isn't a compile step, so it stays Other rather than being folded into Compile and losing that distinction.

Status includes Incomplete for a reason I only appreciated after hitting it myself elsewhere: a span that started and never finished — the build that hung or got killed. That's not a "duration" problem, it's a "the last thing that happened before everything went sideways" problem, and no other Status variant models it.

Contributing a new adapter is a fixture pair, not a code review

Supporting a new build system (Bazel, Gradle, MSBuild, whatever isn't
covered) is one adapter file plus a fixture pair: a real trace from that tool, and the exact normalized JSON it should produce. CI diffs the two — no subjective judgment call needed to review it. The best fixtures come from people running build systems I don't have access to myself (a real Bazel profile from a remote-execution setup, a real MSBuild trace on Windows) — that coverage isn't something I can produce alone.

Where it's at

Early: ninja and cargo adapters today, both covered by golden-file tests.
Single-machine only for now — distributed/remote-execution builds are out of scope until there's a sane way to align clocks I don't control, and I'd rather say that upfront than have it be a surprise.
The cargo adapter has one real fragility worth naming: stable cargo has no --timings=json output, so it reads the UNIT_DATA array embedded in the --timings HTML report — cargo's own dashboard data, not a documented or versioned format. It could change without notice in a future cargo release. If that golden test ever starts failing after a rustup update, that's why.

cargo install buildline

Repo: https://github.com/nabsei/buildline
Crate: https://crates.io/crates/buildline

Disclosure: built with the assistance of Claude Code. I made the design decisions described above, reviewed the implementation, and tested the result myself.