Dual-Sink Logging & CLI Diagnostics
Architecture & InternalsDual-Sink Logging & CLI Diagnostics

Dual-Sink Logging & CLI Diagnostics

Apple os.Logger, in-memory ring buffer, rotating log appender, and CLI diagnostic tools.

Dual-Sink Multi-Logger Architecture

OpenClip implements a multi-sink logging architecture anchored by Log.swift under the com.openclip subsystem:

1. Apple os.Logger

Zero-cost kernel trace for Console.app and live streaming via log stream.

2. 500-Entry In-Memory Ring Buffer (DebugLogBuffer)

Fixed-capacity thread-safe ring buffer with 0ms indexing latency and 0% CPU overhead for instant diagnostics.

3. Rotating File Appender (RotatingFileLogSink)

Writes to ~/Library/Logs/OpenClip/openclip.log (5 MB cap, up to 3 rotated backup archives) with restricted 0o600 file permissions.

CLI Diagnostic Flags (--dump-logs)

Export diagnostics directly from the command line:

Terminal
# Dump recent extension loading logs
"/Applications/OpenClip.app/Contents/MacOS/OpenClip" --dump-logs --category=extensions --level=error

# Live stream selection logs
log stream --predicate 'subsystem == "com.openclip" && category == "selection"'
FlagTypeDescription
--dump-logsFlagRuns headlessly, loads extensions, dumps in-memory logs, and exits 0.
--categoryStringFilter logs to a specific channel (extensions, selection, ai, js, shell).
--levelStringFilter severity: debug, info, notice, warning, error, fault.
--countIntegerLimit maximum dumped lines (default: 500).
--collectDoubleAsync collection delay in seconds before dumping (default: 4.0).