5.4 Performance

bazel build //app:release --profile=release-profile.json.gz gives you a timeline, not an answer. The largest rectangle may be off the path that gates completion. A run that looks short may still rebuild work that should have been reused. A loading or analysis failure may not be about actions at all.

Performance work becomes reliable when each artifact is treated as evidence for one question. The organizing model for this section is a causal intervention loop: reproduce the user-visible scenario, locate the limiting cost, gather the next evidence needed to explain it, change one relevant factor, and repeat the same scenario. The loop starts with measurement and ends with an end-to-end result, not with a plausible story about why Bazel is slow.

Establish The Measurement, Then Find The Gate

The core path begins with 5.4.1 Timing Profile Analysis. It establishes how to capture a JSON trace with the command, revision, configuration, platform, server, and cache state needed to interpret it. It then teaches how to read overlapping lanes and compare matched cold, warm no-op, or incremental workloads without turning a visible event into a causal claim.

5.4.2 Critical Path builds on that profile. It separates the graph-theoretic lower bound—a longest timed chain of dependent actions—from the messier invocation recorded in a JSON trace. That distinction keeps a profile useful without treating one critical-path lane as a permanent property of the build. It adds near-critical paths and slack so an intervention can target the work that actually gates completion rather than merely the largest rectangle.

Once the gate is visible, two articles examine whether the build's shape makes that gate unnecessarily expensive. 5.4.3 Measuring Granularity Trade-offs asks whether target boundaries produce the right loading and analysis cost, useful action concurrency, and action-level reuse. It prevents the shortcut “more targets means more parallelism” by keeping targets, configured targets, and actions as separate graph layers. The critical-path profile is a compact hands-on case for seeing independent chains join before trying to reason about those trade-offs in a large repository.

5.4.4 Stamping Cache Impact follows the same affected-set reasoning for workspace status. It narrows “stamping ruins the cache” into a traceable chain: a status value changes, a status-consuming action loses reuse, and changed outputs may affect downstream work. Read it when repeated executions, rather than one intrinsically long action, are the performance symptom. Together, granularity and stamping turn a timeline observation into two concrete kinds of intervention: reshape the real action work, or narrow an unnecessary invalidation boundary.

Let Optional Tools Rank Or Deepen Hypotheses

5.4.5 Bazel Invocation Analyzer (BIA) provides a faster entry into a dense profile. Bazel Invocation Analyzer can rank suspicious phases, actions, cache behavior, and other trace signals, but its output remains a triage queue. The useful handoff is from a recommendation to the evidence that can establish cause: the trace for timing, 5.2.3 bazel aquery — Action Graph for the planned action's command and artifacts, an execution log for cache behavior, or a memory workflow for heap pressure.

As an extra branch, this article is worth reading when a dense profile needs assisted triage. Keep its operational boundary attached to the choice of tool: use the hosted UI only when policy permits uploading the profile; otherwise run the open-source analyzer locally. In either mode, the analyzer does not close the loop. A matched before-and-after experiment does.

Escalate Only When The Missing Cause Demands It

The remaining articles are escalation paths. They are valuable precisely because they answer narrower questions that the ordinary profile cannot.

Use the extra 5.4.6 Execution Log Graph when a timed chain needs structural evidence. It distinguishes the ordinary spawn-level execution log from the experimental execution graph log, then shows how the latter can complement the trace and aquery. Its nodes and edges describe one invocation. Critical paths, slack, and drag are downstream calculations, not labels guaranteed by the log. This is the path for proving producer/consumer ordering without inventing a graph edge from two adjacent timeline events.

Choose The Shortest Reading Path

For a general slow-build investigation, read Timing Profile Analysis and Critical Path first. Add Measuring Granularity Trade-offs only after graph and action evidence identifies a candidate boundary. Add the recommended Stamping Cache Impact article when the complaint is “the same work runs again.”

The two extra articles can wait until evidence creates their question:

• Read Execution Log Graph when timeline order must become a defensible dependency-path claim.
• Read BIA when a dense profile needs assisted hypothesis ranking and its data handling and version boundaries are acceptable.

If the profile points to memory rather than elapsed action work, continue with 5.6.5 Memory Diagnostics. If it isolates an opaque remote action whose interior can only be observed by shared executor infrastructure, continue in Level 6 with 6.6.2 Action-Internal Telemetry.

Avoid collecting every available artifact at the start. More telemetry can add overhead, operational risk, and unrelated detail without improving the causal question. Begin with the representative invocation and the least invasive evidence that can distinguish the current hypotheses. Escalate when you can name what the next artifact must resolve.