Lumotia/docs/architecture-map/02-tauri-runtime/commands/diagnostics.md

name, type, slice, last_verified

name	type	slice	last_verified
Diagnostics and reports	architecture-map-page	02-tauri-runtime	2026/05/09

commands::diagnostics

Where you are: Architecture map → Tauri runtime → Commands → Diagnostics

Plain English summary. The local-only diagnostic plumbing. Installs the Rust panic hook (writes per-panic dumps to crashes_dir). Captures frontend errors via a global window.onerror handler. Lists recent error-log rows and crash files. Bundles a markdown diagnostic report (settings, recent errors, active power assertions, crash dumps, log tail) so the user can paste it into an email or GitHub issue. Privacy posture: nothing is transmitted; the user reviews exactly what would be shared before sharing it.

At a glance

• Path: src-tauri/src/commands/diagnostics.rs.
• LOC: 534.
• Tauri commands exposed (6 total):
  • log_frontend_error(state, context, message, stack: Option<String>) -> Result<(), String>. No window guard — fires from any window's global error handler.
  • list_recent_errors_command(window, state, limit) -> Result<Vec<ErrorLogDto>, String>. Main-window only.
  • list_crash_files(window) -> Result<Vec<CrashFile>, String>. Main-window only.
  • generate_diagnostic_report(window, state, options: Option<ReportOptions>) -> Result<String, String>. Main-window only.
  • save_diagnostic_report(window, app, state, options) -> Result<String, String>. Main-window only. Returns the absolute file path it wrote.
  • get_os_info() -> OsInfo.
• Public Rust helper used by lib.rs::run: install_panic_hook().
• Events emitted: none.
• Depends on: lumotia_storage::{app_data_dir, crashes_dir, list_recent_errors, log_error, logs_dir, ErrorLogRow}, commands::power::active_assertions_snapshot, commands::security::ensure_main_window. Plus std::fs, std::panic, std::time.
• Called from frontend at: global window.onerror / window.unhandledrejection (log_frontend_error); Settings → About → Diagnostics (the bundle commands and list_* commands); top-of-app Cmd-vs-Ctrl labelling (get_os_info).

What's in here

Constants (src-tauri/src/commands/diagnostics.rs:26)

• DEFAULT_RECENT_ERRORS = 50.
• MAGNOTIA_VERSION = env!("CARGO_PKG_VERSION").

install_panic_hook (:34)

Creates crashes_dir() if missing. Replaces the default panic hook with one that writes a minimal text dump to crashes_dir/<unix_secs>-<short_hash>.crash and then chains to the original hook so the panic still hits stderr. Dump includes version, timestamp, thread name, panic message, OS, arch, RUST_BACKTRACE env. Backtraces require RUST_BACKTRACE=1 and std::backtrace plumbing — neither set up today, so production crashes will lack stack traces.

log_frontend_error (:86)

Truncates the stack to 2,000 chars and calls lumotia_storage::log_error with context "frontend" (or the caller-supplied context), error code "FRONTEND_ERROR", the message, and the stack as metadata.

ErrorLogDto (:114) and list_recent_errors_command (:138)

ErrorLogDto is a camelCase shape over ErrorLogRow. The list command clamps limit to [1, 1000] and defaults to 50.

CrashFile and list_crash_files (:152, :162)

CrashFile exposes filename, mtime_secs, size_bytes, plus a 600-char preview. list_crash_files_inner reads the crashes directory, builds the structs, sorts by mtime descending.

Report options and assembler

• ReportOptions has four boolean flags: include_settings, include_recent_errors, include_crashes, include_log_tail (each defaulting true).
• redact_home(input) replaces home_dir().display() substrings with ~.
• looks_sensitive_key(key) flags keys containing apikey / token / secret / password / bearer.
• redact_json_value(value, key_hint) recursively walks a JSON value redacting strings under sensitive keys.
• sanitise_preferences_json(raw) parses, redacts, re-emits.
• redact_line(input) does line-level redaction for the error-message field.

generate_diagnostic_report_inner (:307)

Builds a markdown document with sections:

1. Header (version, OS / arch, app data dir, generated timestamp, "local-only until you choose to share" notice).
2. Settings (sanitised JSON via sanitise_preferences_json).
3. Recent errors (50 rows, redacted).
4. Power assertions (snapshots from commands::power::active_assertions_snapshot).
5. Crash dumps (up to 5 most-recent, plus a count of older ones).
6. Log tail (8 KB tail of logs_dir/lumotia.log, home-redacted).

save_diagnostic_report (:513)

Generates the report, then writes it to app_data_dir/diagnostic-reports/lumotia-diagnostic-<unix_secs>.md. Returns the absolute path.

OsInfo and get_os_info (:449, :474)

OS family label, arch, uses_cmd boolean (macOS only), is_wayland boolean (Linux only), custom_hotkey_backend (Linux only — true because evdev is the primary path on Linux), and primary_modifier_label ("Cmd" on macOS, "Ctrl" elsewhere). Frontend reads this once at boot to set the hotkey labels and "Open file location" terminology.

Data flow

panic occurs -> install_panic_hook writes crashes_dir/<ts>.crash
window.onerror fires in JS -> invoke('log_frontend_error', context, message, stack)
                            -> lumotia_storage::log_error
                            -> error_log table

Settings -> About -> Diagnostics
  list_crash_files -> [CrashFile, ...]
  list_recent_errors_command -> [ErrorLogDto, ...]
  generate_diagnostic_report(opts) -> markdown string
  user reviews, then optionally:
    save_diagnostic_report(opts) -> absolute path

Watch-outs

• No backtraces in production crashes. RUST_BACKTRACE is not set in the packaged binary. Either set it in a launcher script or call std::backtrace::Backtrace::capture() inside the panic hook.
• log_frontend_error is unguarded by ACL or window-label check. Any window can log a frontend error. That is fine, but the storage layer should enforce a row-rate limiter before this surface ever ships to users with adversarial workloads.
• Crash file prefixes are unix-seconds-and-a-16-bit-hash. Two panics in the same second with the same low-16-bits of seconds will collide. Vanishingly unlikely in practice. If you want bulletproof, use the same counter pattern as commands::audio::recording_filename.
• Diagnostic report is markdown by design so it can be pasted anywhere. If you ever want a structured upload format, keep this command and add a sibling that returns JSON.
• Sensitive-key redaction is a heuristic. It catches the obvious names (api_key, apiKey, token, Bearer) but won't catch a user-named key like mySecretToken: "abc" if the key string is normalised to lowercase first. Fine for "user reviews before sharing"; not fine if you ever auto-upload.
• ensure_main_window is missing on log_frontend_error and get_os_info. Intentional — both should be callable from any window. But document this so future tightening attempts know to leave them alone.

See also

• App lifecycle — install_panic_hook is called from setup.
• Power assertions and security — active_assertions_snapshot feeds the report.
• Capabilities and ACL — the report is local until the user chooses to share.
• Tests — no specific test for the report itself, but the redactor helpers could use unit coverage.