a1f3f3f134
Five-slice navigable map of the entire codebase under
docs/architecture-map/. Each slice is a self-contained
breadcrumbed sub-tree:
01-frontend (16) Svelte/SvelteKit UI
02-tauri-runtime (26) src-tauri commands + lifecycle
03-audio-transcription (16) audio + transcription crates
04-llm-formatting-mcp (19) llm, ai-formatting, mcp, cloud
05-core-storage-hotkey-build core, storage, hotkey, workspace,
(26) CI, dev glue
Plus master README.md and data-flow-end-to-end.md tracing
audio bytes from microphone to FTS5 search to MCP read.
Generated by 5 parallel subagents on 2026/05/09 against
HEAD 3c47000. Each page has YAML frontmatter, file:line code
refs, sibling cross-links, plain-English summaries.
Aggregated debt surfaced (full lists in master README):
RB-08 macOS power assertion, schema head drift v14 vs v15,
VAD blocked on ort version conflict, streaming primitives
not wired into live.rs, no prompt versioning, MCP has no
auth, cloud-providers in-memory keystore, SettingsPage
2 484 LOC, commands/live.rs 1 737 LOC, dual theme system,
brand rename to Lumenote pending across the codebase.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
112 lines
7.4 KiB
Markdown
112 lines
7.4 KiB
Markdown
---
|
|
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.
|