Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 31 additions & 1 deletion crates/diagnostics/src/bundle.rs
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,37 @@ use tokio::io::{AsyncReadExt as _, AsyncWrite, AsyncWriteExt as _};
use crate::manifest::{CollectedEntry, CollectorError, Manifest, Redaction, SkippedEntry};

/// Default per-file tail cap for bundled logs.
pub const LOG_TAIL_CAP: u64 = 5 * 1024 * 1024;
///
/// Sized against the shipping file format (`mlog`'s JSON-lines, measured at
/// ~214 B/record on a real capture), so this holds order 157k records per
/// file — about 6x what 5 MiB held. The wire cost of the increase is close to
/// nothing: log text compresses ~70x inside the bundle's zstd stream, so five
/// rotated files go from ~0.3 MiB to ~2.2 MiB of archive.
///
/// The real cost is uncompressed: `add_file_tail` buffers a whole tail in
/// memory, and a bundle collects up to ~16 log files, so this value also sets
/// peak allocation per file and bounds extraction at ~512 MiB. That is what
/// keeps it here rather than higher — at `RUST_LOG=debug` no cap "holds the
/// incident" anyway (a measured burst produced 36 MB of records in eight
/// seconds, nearly all of it dependency chatter), so a larger default buys
/// linear history for linear extraction cost, not a categorical win.
pub const LOG_TAIL_CAP: u64 = 32 * 1024 * 1024;

/// Largest per-file tail cap [`BundleWriter::add_file_tail`] can honor.
///
/// The ceiling is structural, not politeness: `add_file_tail` seeks
/// `-(cap as i64)` from the end, so a cap past `i64::MAX` is a nonsense seek,
/// and any very large cap is an unbounded read into memory. A caller that
/// takes this value from a user must *reject* anything above it rather than
/// clamp — a silently clamped cap reports success while capturing less than
/// was asked for, and the short log then reads as evidence.
pub const MAX_LOG_TAIL_BYTES: u64 = 64 * 1024 * 1024;

/// The default has to leave room to ask for more, or a caller-facing knob
/// validated against [`MAX_LOG_TAIL_BYTES`] becomes downward-only. Enforced at
/// compile time so raising [`LOG_TAIL_CAP`] past the halfway mark cannot land
/// silently.
const _: () = assert!(LOG_TAIL_CAP * 2 <= MAX_LOG_TAIL_BYTES);

mod sealed {
pub trait Sealed {}
Expand Down
4 changes: 3 additions & 1 deletion crates/diagnostics/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,9 @@ pub mod redact;
#[cfg(unix)]
pub mod system;

pub use bundle::{BundleSink, BundleWriter, LOG_TAIL_CAP, open_regular_nofollow};
pub use bundle::{
BundleSink, BundleWriter, LOG_TAIL_CAP, MAX_LOG_TAIL_BYTES, open_regular_nofollow,
};
pub use capture::{Capture, CaptureError, command_capture, command_stdout, first_stdout_line};
#[cfg(unix)]
pub use disk::{DiskUsage, disk_usage};
Expand Down
14 changes: 10 additions & 4 deletions crates/minimal/src/diag/collect.rs
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ use serde::Serialize;

use super::redact::is_env_value_allowlisted;
use diagnostics::redact::{masked_process_env, redact_toml};
use diagnostics::{BundleWriter, LOG_TAIL_CAP, Redaction, open_regular_nofollow};
use diagnostics::{BundleWriter, Redaction, open_regular_nofollow};

/// Cap on entries in a recursive state-dir listing; a runaway tree (huge
/// session workspaces) is truncated with a marker line, not walked forever.
Expand Down Expand Up @@ -208,7 +208,13 @@ pub async fn state(w: &mut BundleWriter, paths: &DiagPaths) -> Result<(), anyhow
/// How many rotated files per log prefix make it into the bundle.
const LOG_FILES_PER_PREFIX: usize = 5;

pub async fn logs(w: &mut BundleWriter, paths: &DiagPaths) -> Result<(), anyhow::Error> {
/// `tail_bytes` is the per-file cap, already validated by the caller against
/// [`diagnostics::MAX_LOG_TAIL_BYTES`].
pub async fn logs(
w: &mut BundleWriter,
paths: &DiagPaths,
tail_bytes: u64,
) -> Result<(), anyhow::Error> {
let log_dir = paths.state.join("logs");
// Absence and inaccessibility are different facts: "no log directory"
// may only be claimed on a real NotFound, never on EACCES or I/O errors.
Expand All @@ -229,7 +235,7 @@ pub async fn logs(w: &mut BundleWriter, paths: &DiagPaths) -> Result<(), anyhow:
for path in files {
let name = path.file_name().unwrap_or_default().to_string_lossy();
let dest = format!("logs/{name}");
if let Err(e) = w.add_file_tail(&dest, &path, LOG_TAIL_CAP).await {
if let Err(e) = w.add_file_tail(&dest, &path, tail_bytes).await {
w.skip(&dest, format!("unreadable: {e}"));
}
}
Expand All @@ -246,7 +252,7 @@ pub async fn logs(w: &mut BundleWriter, paths: &DiagPaths) -> Result<(), anyhow:
for log_name in ["run.log", "boot.log"] {
let dest = format!("providers/{name}/{log_name}");
match w
.add_file_tail(&dest, &dir.join(log_name), LOG_TAIL_CAP)
.add_file_tail(&dest, &dir.join(log_name), tail_bytes)
.await
{
Ok(()) => {}
Expand Down
96 changes: 94 additions & 2 deletions crates/minimal/src/diag/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ pub mod collect;
pub mod redact;

use collect::DiagPaths;
use diagnostics::{BundleWriter, Redaction};
use diagnostics::{BundleWriter, LOG_TAIL_CAP, MAX_LOG_TAIL_BYTES, Redaction};

use crate::GlobalArgs;

Expand All @@ -26,6 +26,36 @@ pub struct BugArgs {
/// Output path (default: ./minimal-diag-<timestamp>.tar.zst)
#[arg(long, short)]
pub output: Option<PathBuf>,
/// Bytes of each log file to capture, counted from the end
///
/// Raise this when the interesting window is older than the tail the
/// default buys you. A daemon at `RUST_LOG=debug` can outrun any cap —
/// most of that volume is dependency chatter, not minimal's own records —
/// and the current day's file is not size-rotated, so a fixed tail can
/// start well after the incident.
#[arg(long, default_value_t = LOG_TAIL_CAP, value_parser = parse_log_tail_bytes)]
pub log_tail_bytes: u64,
}

/// Parses `--log-tail-bytes`, refusing anything the bundle writer cannot
/// honor.
///
/// Refusing rather than clamping is the point. A clamp reports success while
/// quietly capturing less than was asked for, so the resulting short log
/// reads as a fact about the system instead of a fact about the flag — the
/// exact shape of mistake that makes a diagnostic bundle actively misleading.
fn parse_log_tail_bytes(raw: &str) -> Result<u64, String> {
let bytes: u64 = raw
.parse()
.map_err(|_| format!("`{raw}` is not a whole number of bytes"))?;
match bytes {
0 => Err("must be at least 1 byte; 0 would collect empty log files".to_string()),
b if b > MAX_LOG_TAIL_BYTES => Err(format!(
"{b} exceeds the maximum of {MAX_LOG_TAIL_BYTES} bytes ({} MiB)",
MAX_LOG_TAIL_BYTES / (1024 * 1024)
)),
b => Ok(b),
}
}

/// A collector timeout generous enough for slow disks, small enough that a
Expand Down Expand Up @@ -114,7 +144,11 @@ pub async fn cmd_bug(global: &GlobalArgs, args: BugArgs) -> Result<(), anyhow::E
collect_step!(w, "host.power", diagnostics::power::power(&mut w, "host"));
collect_step!(w, "config", collect::config(&mut w, &paths));
collect_step!(w, "state", collect::state(&mut w, &paths));
collect_step!(w, "logs", collect::logs(&mut w, &paths));
collect_step!(
w,
"logs",
collect::logs(&mut w, &paths, args.log_tail_bytes)
);

// Daemon-side state (socket probes, guest bundles, per-provider status)
// is collected over the daemon connection, not from the host bundle;
Expand Down Expand Up @@ -188,3 +222,61 @@ async fn dirs_report(w: &mut BundleWriter, global: &GlobalArgs) -> Result<(), an
w.add_bytes("host/dirs.txt", report.as_bytes(), Redaction::None)
.await
}

#[cfg(test)]
mod tests {
use super::*;
use clap::Parser as _;

/// Parses `min bug`'s arguments the way the real CLI does, so these
/// assertions cover the `value_parser` wiring and not just the function.
#[derive(Debug, clap::Parser)]
struct Harness {
#[command(flatten)]
args: BugArgs,
}

fn parse(argv: &[&str]) -> Result<BugArgs, clap::Error> {
Harness::try_parse_from(std::iter::once("bug").chain(argv.iter().copied())).map(|h| h.args)
}

/// The flag tracks the shared default rather than restating it, so
/// raising `LOG_TAIL_CAP` raises what an unflagged `min bug` collects.
#[test]
fn omitting_the_flag_uses_the_shared_default() {
assert_eq!(parse(&[]).unwrap().log_tail_bytes, LOG_TAIL_CAP);
}

#[test]
fn a_cap_within_the_contract_is_accepted_verbatim() {
for bytes in [1, LOG_TAIL_CAP, MAX_LOG_TAIL_BYTES] {
let args = parse(&["--log-tail-bytes", &bytes.to_string()]).unwrap();
assert_eq!(args.log_tail_bytes, bytes, "{bytes} must survive intact");
}
}

/// The whole point of the flag's validation: an over-large cap fails the
/// command rather than being quietly reduced to the ceiling.
#[test]
fn an_over_large_cap_is_rejected_not_clamped() {
for bytes in [MAX_LOG_TAIL_BYTES + 1, u64::MAX] {
let Err(err) = parse(&["--log-tail-bytes", &bytes.to_string()]) else {
panic!("{bytes} is above the ceiling and must be rejected, not clamped");
};
let err = err.to_string();
assert!(
err.contains(&MAX_LOG_TAIL_BYTES.to_string()) && err.contains("exceeds"),
"the error must name the ceiling it broke: {err}"
);
}
}

#[test]
fn a_zero_or_non_numeric_cap_is_rejected() {
// 0 is the wire contract's "use the default" sentinel; taken
// literally here it would bundle empty logs labelled tail-capped.
assert!(parse(&["--log-tail-bytes", "0"]).is_err());
assert!(parse(&["--log-tail-bytes", "5MiB"]).is_err());
assert!(parse(&["--log-tail-bytes", "-1"]).is_err());
}
}
47 changes: 47 additions & 0 deletions crates/minimal/tests/bug.rs
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,7 @@ fn global_args(state: &Path, config: &Path) -> GlobalArgs {
fn bug_args(out: &Path) -> BugArgs {
BugArgs {
output: Some(out.to_path_buf()),
log_tail_bytes: diagnostics::LOG_TAIL_CAP,
}
}

Expand Down Expand Up @@ -260,6 +261,52 @@ async fn logs_collects_newest_five_per_prefix_and_provider_logs() {
assert_eq!(manifest["errors"].as_array().unwrap().len(), 0, "no errors");
}

/// The `--log-tail-bytes` cap reaches every log the collector bundles — the
/// rotated host logs and the provider-scoped ones — and the manifest labels
/// each capped file so a reader can tell a truncated log from a short one.
#[tokio::test]
async fn a_custom_tail_cap_applies_to_every_log() {
let state = tempfile::TempDir::new().unwrap();
let config = tempfile::TempDir::new().unwrap();

let log_dir = state.path().join("logs");
std::fs::create_dir_all(&log_dir).unwrap();
std::fs::write(log_dir.join("minimald.log.2026-07-21"), "x".repeat(500)).unwrap();
let provider = state.path().join("providers/local-0");
std::fs::create_dir_all(&provider).unwrap();
std::fs::write(provider.join("run.log"), "y".repeat(500)).unwrap();

let out_dir = tempfile::TempDir::new().unwrap();
let out = out_dir.path().join("diag.tar.zst");
let mut args = bug_args(&out);
args.log_tail_bytes = 100;
cmd_bug(&global_args(state.path(), config.path()), args)
.await
.unwrap();

let files = unpack(&out).await;
for suffix in ["logs/minimald.log.2026-07-21", "providers/local-0/run.log"] {
let contents = find(&files, suffix).unwrap_or_else(|| panic!("missing {suffix}"));
assert_eq!(contents.len(), 100, "{suffix} honors the requested cap");
}

let manifest: serde_json::Value =
serde_json::from_slice(find(&files, "manifest.json").expect("manifest")).unwrap();
let capped: Vec<&serde_json::Value> = manifest["collected"]
.as_array()
.unwrap()
.iter()
.filter(|e| e["redaction"] == "tail-capped")
.collect();
assert_eq!(capped.len(), 2, "both logs recorded as tail-capped");
// Today the applied cap is only recoverable from a capped entry's own
// byte count; the manifest has no field naming it outright.
assert!(
capped.iter().all(|e| e["bytes"] == 100),
"a capped entry's size is the cap: {capped:?}"
);
}

/// R5.1–R5.3: the incident collectors (net/procs/power) land in the bundle,
/// and interface MACs are masked to their vendor OUI. No daemon needed — these
/// capture host state.
Expand Down