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

# `commands::diagnostics`

> **Where you are:** [Architecture map](../../README.md) → [Tauri runtime](../README.md) → [Commands](README.md) → 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: `magnotia_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 `magnotia_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/magnotia.log`, home-redacted).

### `save_diagnostic_report` (`:513`)

Generates the report, then writes it to `app_data_dir/diagnostic-reports/magnotia-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)
                            -> magnotia_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](../app-lifecycle.md) — `install_panic_hook` is called from setup.
- [Power assertions and security](power-and-security.md) — `active_assertions_snapshot` feeds the report.
- [Capabilities and ACL](../capabilities-and-acl.md) — the report is local until the user chooses to share.
- [Tests](../tests.md) — no specific test for the report itself, but the redactor helpers could use unit coverage.