Tracking Issue for `-Zbuild-analysis`

[weihanglo]

Summary

Original issue: rust-lang/rust-project-goals#332
Documentation: https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#build-analysis
Project goal: rust-lang/rust-project-goals#398

The -Zbuild-analysis feature records and persists detailed build metrics (timings, rebuild reasons, etc.) across runs, with new commands to query past builds.

Considerations for stabilization

• Review the JSON schemas we exposed are reasonable (especially rebuild reason which has lots of variants)
• JSON schema evolution
• log compression
• log rotations

Unresolved Issues

See the unresolved design questions in the design doc: https://hackmd.io/K5-sGEJeR5mLGsJLXqsHrw?view#Unresolved-questions.

• Schema questions
  • fix(log): break timing-info message to multiple #16303 (comment)
  • fix(log): break timing-info message to multiple #16303 (comment)
  • feat(build-analysis): emit rebuild reason log entry #16203
• Is losing data on crashes ok? https://github.com/rust-lang/cargo/pull//16150#discussion_r2462056940
• Providing the types for reading these, see https://github.com/rust-lang/cargo/pull//16150#discussion_r2462065538

Future Extensions

No response

Implementations

See the design doc: https://hackmd.io/K5-sGEJeR5mLGsJLXqsHrw

• Nightly feature gate and configuration feat(unstable): add -Zbuild-analysis unstable feature #15845
• Storage infrastructure, storage path, migration, etc. https://github.com/rust-lang/cargo/pull//16150
• Collecting metrics
  • Collect build metadata feat(build-analysis): JSONL-based logging infra #16150
  • Collect CLI args (so people know what they've run)
  • Collect timing data timing-info event
    • feat(build-analysis): emit timing-info log #16179
    • fix(timing): more self-contained timing/log data #16378
  • Collect rebuild reason data
    • feat(build-analysis): emit rebuild reason log entry #16203
    • fix(log): emit fingeprint log also for no-rebuild unit #16408
  • Collect timing concurrency metrics feat(timings): derive concurrency data from unit data #16350
  • Collect timing CPU usages
  • Collect timing unlocked units (for drawing the dependency lines) fix(log): break timing-info message to multiple #16303
  • Collect resolution time, unit graph construction time, and unit metadata feat(log): add more log events #16390
• Set up new unstable cargo report commands
  • Separate timing tracking and presentation layers (log replay for HTML report)
    • refactor(timings): separate data collection and presentation #16282
    • refactor(timings): store UnitData in RenderContext instead  #16346
  • cargo report timings HTML log replay
    • feat(report): cargo report timings HTML replay #16377
    • feat(log): make timing messages ready for HTML replay #16382
  • cargo report rebuild-reason integration
• benchmark the build performance impact

About tracking issues

Tracking issues are used to record the overall progress of implementation.
They are also used as hubs connecting to other relevant issues, e.g., bugs or open design questions.
A tracking issue is however not meant for large scale discussion, questions, or bug reports about a feature.
Instead, open a dedicated issue for the specific matter and add the relevant feature gate label.

[weihanglo]

Implementation tasks

See the PR description.