README.md

Error Reporting

Documents

• OVERVIEW.md - Non-technical summary of how error reporting works
• non-critical-errors.md - Recoverable errors: filtering logic, OTel recording
• critical-errors.md - Fatal errors: terminate paths, crash reporter subprocess
• telemetry-otel.md - OTel architecture: ring buffer, IPC forwarding, export
• fingerprint-resolution.md - GitHub workflows that mark error fingerprints as fixed/released in ClickHouse

Key Files

• src/renderer/src/util/message.ts - showError() entry point for non-critical errors
• src/renderer/src/util/errorHandling.ts - withTrackedActivity, recordErrorSpan, terminate (renderer)
• src/main/src/errorHandling.ts - terminate / terminateAsync for main-process crashes
• src/main/src/errorReporting.ts - reportCrash() — short-lived OTel provider for crash spans
• src/main/src/telemetry/RingBufferSpanProcessor.ts - Circular buffer; auto-exports on ERROR status
• src/main/src/telemetry/setup.ts - createMainTelemetryProvider, OTLP exporter config
• src/main/src/telemetry/ipcHandler.ts - Renderer→main span IPC bridge; analytics opt-in watcher
• src/shared/src/telemetry/spans.ts - recordErrorOnSpan shared utility
• src/shared/src/errors.ts - computeErrorFingerprint for deduplication

Flow

error occurs
  └─ recordErrorOnSpan()        sets ERROR status + fingerprint on span
       └─ span.end()
            └─ RingBufferSpanProcessor.onEnd()
                 └─ status == ERROR?
                      yes ──> extract all spans for this traceId
                               isTelemetryEnabled()?
                                 yes ──> OTLPTraceExporter → vortex-collector.nexusmods.com

Renderer spans are forwarded to main via IPC (telemetry:forward-span) before entering the ring buffer.