atrium — Docs
docs/reference/diagnostics.md

Diagnostics: profile atrium when it feels slow

Record bounded performance traces, capture a performance bundle or Rust flame graph, inspect process memory, and find local error logs.

When atrium feels slow, Settings → Diagnostics can record performance traces and package evidence into a ZIP. Record while reproducing the problem, then inspect the files before sharing them.

Recorder

The recorder is off by default. Turn on Enable recorder, then choose which streams to record: long tasks, render stats, IPC timings, terminal stats, and memory stats. The stream controls are disabled while the recorder is off. See config.diagnostics for the JSON shape.

Stop recording after offers 30 minutes, 2 hours (the default), 8 hours, or Until I stop it. Changing the duration during a recording starts a new time window from that moment. A saved deadline still applies after sleep or restarting atrium.

A visible recording indicator shows the remaining time; click it to stop. Settings also shows the trace path and saved size. Recording stops automatically at its time limit or 500 MB, including when Until I stop it is selected. A notice links to the saved trace.

atrium keeps the newest five perf-*.ndjson traces within a combined 2 GB budget, pruning older traces as new data is written. This retention rule applies to recorder traces, not manually captured ZIPs, flame graphs, or support reports.

Performance Bundle

The Performance Bundle combines command and background-work statistics, system information, and any active recorder trace into one archive. On macOS it also captures a Rust CPU profile. Windows bundles include the other evidence and explain that the CPU profile was skipped.

  • Start from Settings → Diagnostics → Captures → Capture performance bundle.
  • Duration — choose 10 seconds through 10 minutes. The capture continues if you close Settings, so you can use the app normally during the recording.
  • Bundle note — optionally describe what you were doing; the note is included in the archive.
  • Notification — atrium attempts a system notification when the bundle is ready. The completed bundle is also available in Settings to reveal in your file manager.
What's inside:
  • flamegraph.svg and, when encoding succeeds, profile.pb on macOS.
  • diagnostics.ndjson when a recorder trace was available.
  • command-stats-delta.json with before/after statistics and changes over the capture window. Windows also includes browser frame-delivery and stalled-pane information.
  • system-info.json and a README.md explaining the files and any omitted evidence.
The bundle does not add project files, scrollback, or transcripts as attachments. Diagnostic fields and your bundle note can still contain identifying details. Inspect the ZIP before sharing it.

Rust flame graph

On macOS, use Settings → Diagnostics → Captures → Capture flame graph for a CPU profile without the full bundle. The current daemon-based app samples atriumd; the profile does not include the desktop webview, CEF subprocesses, or agent processes.

The capture writes into the active instance's diagnostics/ directory:

  • profile-<timestamp>.svg — a flame graph you can open in a browser.
  • profile-<timestamp>.pb — pprof protobuf, when encoding succeeds.
The default capture lasts 10 seconds. Packaged builds may show addresses instead of function names; the protobuf preserves information needed to resolve them against matching release symbols. There is no bundled symbols/ directory.

Pane stats badge

Enable Settings → Diagnostics → In-app overlays → Pane stats badge for per-pane IPC and render activity in pane headers. This setting is independent of the trace recorder.

Memory from the CLI

atrium diagnostics memory reports the memory attributed to the app, its child processes, and WKWebView renderers using macOS physical footprint—the number closest to Activity Monitor's Memory column.

atrium diagnostics memory
atrium diagnostics memory --top 25
atrium diagnostics memory --watch 60

--top keeps the heaviest processes expanded and rolls the rest into one counted row. --watch <seconds> takes a second sample and adds MB/min growth, which helps distinguish a steadily growing renderer from ordinary allocation and garbage-collection noise.

Safari Web Inspector

On macOS, launch atrium with ATRIUM_DEVELOPER=1, then choose Enable Safari Web Inspector in the command palette's Debug category. The command enables inspection for the current launch; it is not a persistent Diagnostics setting.

In Safari, select Develop → your machine → atrium to inspect the frontend webview. This command is not available on Windows.

Local error logs

Logs are separate from the optional performance recorder and live under the active data directory:

FileWhat it records
logs/runtime.<date>.logBackground daemon operations, in UTC, rotated daily.
logs/app.<date>.logDesktop warnings and errors, startup failures, browser renderer crashes, and selected capture, speech, menu, and updater events. Files older than seven days by modification time are pruned at startup.
logs/atriumd.stderr.logRaw daemon stderr, including panic and loader output. Append-only across launches, without a universal timestamp prefix.
logs/chat-runtime.<date>.logChat sidecar stderr. Usually timestamped and rotated daily; session-survival mode writes raw stderr to the sidecar's startup-day file. Old files are pruned after seven days by modification time when a writer starts.
logs/webview-errors.ndjsonFrontend crashes, unexpected IPC rejections, and reported chat-restore failures; rotates at 2 MiB with one backup.
logs/cef.logChromium browser-pane logs, using local time.
logs/daemon-signals.logatrium's attempts to signal its daemon during shutdown, recovery, or updates.

A caught error may still appear in a log when atrium explicitly records it. Console-only messages are not automatically saved. Missing log entries do not prove that an operation succeeded or never ran.

Where the data lives

  • Diagnostics traces — <data-directory>/diagnostics/perf-*.ndjson.
  • Flame graphs and performance bundles — the same directory, named profile-* and bundle-*.zip.
  • The standard installed app uses ~/.atrium/; dev worktrees and other instances have separate directories. Use the path shown in Settings or $ATRIUM_DATA_DIR.
Review diagnostic files and logs before sharing. Local error details, paths, process information, and any notes you supply are not a promise of automatic redaction.

Privacy

Diagnostics recording is separate from telemetry. Captures and bundles stay on disk until you share them; creating a bundle does not upload it or provide an audit of every outbound telemetry payload.