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.

See also

• Provide better diagnostics for why crates are rebuilt #2904
• Show more details on "Dirty ...: dependency info changed" #13859

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 (DirtyReason was a implementation detail)
    • feat(report): add cargo report rebuilds  #16456 (comment)
  • fix(report): get the same feature parity of --timings #16414 (comment) (classic overloaded "target" term)
• Is losing data on crashes ok? https://github.com/rust-lang/cargo/pull//16150#discussion_r2462056940
• Providing the types for reading log messages, see https://github.com/rust-lang/cargo/pull//16150#discussion_r2462065538

• JSON schema evolution
• Nested Cargo calls Nested Cargo calls and session IDs #16477
• cargo report sessions
  • Format for programmable use cases (--message-format=json?)
  • Currently the global search is implicit (if not in workspace do global search).
    • Should this be explicit with a flag?
    • Should this be an error if not in a workspace?
• cargo report rebuilds
  • Command name feat(report): add cargo report rebuilds  #16456 (comment)
  • Make each dirty reason more actionable and friendly for end-users.
  • This will resolve Provide better diagnostics for why crates are rebuilt #2904 and Show more details on "Dirty ...: dependency info changed" #13859
  • This competes with the existing verbose freshness output. Do we want to keep both or remove the old output?
  • Extend the report from fingerprint to new hash (-Cmetadata/-Cextra-filename) feat(report): add cargo report rebuilds  #16456 (comment)

Future Extensions

• log compression Log compression for structured logging #16475
• log rotation Log rotation for structured logging #16471

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
• A command listing log sessions feat(report): new command cargo report sessions #16428
• 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
    • feat(report): add cargo report rebuilds  #16456

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.