feat(build-analysis): add simple logger

The logging infrastructure for `-Zbuild-analysis`.

Some highlights:

- JSONL logs stored in `~/.cargo/log/`.
- Unique log file for each cargo invocation,
  with a run ID based on workspace hash and timestamp.
- Uses background thread for log writes and serialization.
  Open to use other battle-tested crates in the future.

Author: weihanglo

Cargo.toml

@@ -183,7 +183,7 @@ ignore.workspace = true
 im-rc.workspace = true
 indexmap.workspace = true
 itertools.workspace = true
-jiff.workspace = true
+jiff = { workspace = true, features = ["serde", "std"] }
 jobserver.workspace = true
 lazycell.workspace = true
 libgit2-sys.workspace = true

src/cargo/ops/cargo_compile/mod.rs

@@ -53,6 +53,7 @@ use crate::core::{PackageId, PackageSet, SourceId, TargetKind, Workspace};
 use crate::drop_println;
 use crate::ops;
 use crate::ops::resolve::{SpecsAndResolvedFeatures, WorkspaceResolve};
+use crate::util::BuildLogger;
 use crate::util::context::{GlobalContext, WarningHandling};
 use crate::util::interning::InternedString;
 use crate::util::{CargoResult, StableHasher};
@@ -155,6 +156,8 @@ pub fn compile_ws<'a>(
     exec: &Arc<dyn Executor>,
 ) -> CargoResult<Compilation<'a>> {
     let interner = UnitInterner::new();
+    let _logger = BuildLogger::maybe_new(ws)?;
+
     let bcx = create_bcx(ws, options, &interner)?;
     if options.build_config.unit_graph {
         unit_graph::emit_serialized_unit_graph(&bcx.roots, &bcx.unit_graph, ws.gctx())?;

src/cargo/util/log_message.rs

@@ -0,0 +1,36 @@
+//! Messages for logging.
+
+use std::io::Write;
+
+use jiff::Timestamp;
+use serde::Serialize;
+
+/// A log message.
+///
+/// Each variant represents a different type of event.
+#[derive(Serialize)]
+#[serde(tag = "reason", rename_all = "kebab-case")]
+pub enum LogMessage {}
+
+impl LogMessage {
+    /// Serializes this message as a JSON log line directly to the writer.
+    pub fn write_json_log<W: Write>(&self, writer: &mut W, run_id: &str) -> std::io::Result<()> {
+        #[derive(Serialize)]
+        struct LogEntry<'a> {
+            run_id: &'a str,
+            timestamp: Timestamp,
+            #[serde(flatten)]
+            msg: &'a LogMessage,
+        }
+
+        let entry = LogEntry {
+            run_id,
+            timestamp: Timestamp::now(),
+            msg: self,
+        };
+
+        serde_json::to_writer(&mut *writer, &entry)?;
+        writer.write_all(b"\n")?;
+        Ok(())
+    }
+}

src/cargo/util/logger.rs

@@ -0,0 +1,105 @@
+//! Build analysis logging infrastructure.
+
+use std::io::{BufWriter, Write};
+use std::mem::ManuallyDrop;
+use std::path::Path;
+use std::sync::mpsc;
+use std::sync::mpsc::Sender;
+use std::thread::JoinHandle;
+
+use cargo_util::paths;
+
+use crate::CargoResult;
+use crate::core::Workspace;
+use crate::util::log_message::LogMessage;
+use crate::util::short_hash;
+
+/// Logger for `-Zbuild-analysis`.
+pub struct BuildLogger {
+    tx: ManuallyDrop<Sender<LogMessage>>,
+    run_id: String,
+    handle: Option<JoinHandle<()>>,
+}
+
+impl BuildLogger {
+    /// Creates a logger if `-Zbuild-analysis` is enabled.
+    pub fn maybe_new(ws: &Workspace<'_>) -> CargoResult<Option<Self>> {
+        let analysis = ws.gctx().build_config()?.analysis.as_ref();
+        match (analysis, ws.gctx().cli_unstable().build_analysis) {
+            (Some(analysis), true) if analysis.enabled => Ok(Some(Self::new(ws)?)),
+            (Some(_), false) => {
+                ws.gctx().shell().warn(
+                    "ignoring 'build.analysis' config, pass `-Zbuild-analysis` to enable it",
+                )?;
+                Ok(None)
+            }
+            _ => Ok(None),
+        }
+    }
+
+    fn new(ws: &Workspace<'_>) -> CargoResult<Self> {
+        let run_id = Self::generate_run_id(ws)?;
+
+        let log_dir = ws.gctx().home().join("log");
+        paths::create_dir_all(log_dir.as_path_unlocked())?;
+
+        let filename = format!("{run_id}.jsonl");
+        let log_file = log_dir.open_rw_exclusive_create(
+            Path::new(&filename),
+            ws.gctx(),
+            "build analysis log",
+        )?;
+
+        let (tx, rx) = mpsc::channel::<LogMessage>();
+
+        let run_id_clone = run_id.clone();
+        let handle = std::thread::spawn(move || {
+            let mut writer = BufWriter::new(log_file);
+            for msg in rx {
+                let _ = msg.write_json_log(&mut writer, &run_id_clone);
+            }
+            let _ = writer.flush();
+        });
+
+        Ok(Self {
+            tx: ManuallyDrop::new(tx),
+            run_id,
+            handle: Some(handle),
+        })
+    }
+
+    /// Generates a unique run ID.
+    ///
+    /// The format is `{timestamp}-{hash}`, with `:` and `.` in the timestamp
+    /// removed to make it safe for filenames.
+    /// For example, `20251024T194502773638Z-f891d525d52ecab3`.
+    pub fn generate_run_id(ws: &Workspace<'_>) -> CargoResult<String> {
+        let hash = short_hash(&ws.root());
+        let timestamp = jiff::Timestamp::now().to_string().replace([':', '.'], "");
+        Ok(format!("{timestamp}-{hash}"))
+    }
+
+    /// Returns the run ID for this build session.
+    pub fn run_id(&self) -> &str {
+        &self.run_id
+    }
+
+    /// Logs a message.
+    pub fn log(&self, msg: LogMessage) {
+        let _ = self.tx.send(msg);
+    }
+}
+
+impl Drop for BuildLogger {
+    fn drop(&mut self) {
+        // SAFETY: tx is dropped exactly once here to signal thread shutdown.
+        // ManuallyDrop prevents automatic drop after this impl runs.
+        unsafe {
+            ManuallyDrop::drop(&mut self.tx);
+        }
+
+        if let Some(handle) = self.handle.take() {
+            let _ = handle.join();
+        }
+    }
+}

src/cargo/util/mod.rs

@@ -18,6 +18,7 @@ pub use self::into_url::IntoUrl;
 pub use self::into_url_with_base::IntoUrlWithBase;
 pub(crate) use self::io::LimitErrorReader;
 pub use self::lockserver::{LockServer, LockServerClient, LockServerStarted};
+pub use self::logger::BuildLogger;
 pub use self::once::OnceExt;
 pub use self::progress::{Progress, ProgressStyle};
 pub use self::queue::Queue;
@@ -55,6 +56,8 @@ mod io;
 pub mod job;
 pub mod lints;
 mod lockserver;
+pub mod log_message;
+mod logger;
 pub mod machine_message;
 pub mod network;
 mod once;