Unified Logging & Diagnostics
Relevant source files
The following files were used as context for generating this wiki page:
Unified Logging & Diagnostics in Spotty provides a mechanism for recording operational events and analyzing the health of the application. The system captures local operational data to assist in debugging and performance monitoring while adhering to strict privacy and security policies.
The project uses Apple Unified Logging to store events locally on the user's Mac. These logs are intended to be privacy-safe, excluding sensitive data such as OAuth tokens, redirects, and raw API bodies. Users can export these logs for analysis using provided scripts.
Sources: PRIVACY.md:27-31, README.md:65-67
Architecture and Data Flow
Spotty's diagnostic architecture relies on native macOS tools to collect and report on the application's state. The flow starts with operational events being emitted by the Swift and Rust components, which are then stored in the system-level Apple Unified Logging facility.
The diagram shows how operational events from different application layers are centralized in Unified Logging before being extracted by diagnostic scripts for manual review.
Sources: AGENTS.md:46-49, PRIVACY.md:38-40, Scripts/report-size.sh:3-7
Logging Policies and Privacy
Spotty maintains a strict boundary between operational visibility and user privacy. The logging contract explicitly defines what data must be excluded to ensure that diagnostic exports do not leak sensitive information.
- Exclusions: Logs must not contain tokens, OAuth redirects, raw API bodies, or raw user payloads.
- Storage: Operational logs are stored locally using Apple Unified Logging.
- User Responsibility: Users are instructed to review every diagnostic report before sharing it to ensure no sensitive data is accidentally included.
Sources: PRIVACY.md:29-31, PRIVACY.md:38-40, SECURITY.md:21-27
Log Review and Security Reporting
When reporting vulnerabilities or issues, developers and users must follow a specific process to prevent data exposure:
- Use the
Scripts/export-diagnostics.shscript to capture a bounded slice of logs. - Manually review the output in the
diagnostics/directory. - Remove any accidental account data or tokens.
- Submit via the private Security -> Report a vulnerability flow if applicable.
Sources: PRIVACY.md:38-40, SECURITY.md:7-13
Size and Resource Diagnostics
The project includes specialized diagnostic scripts to measure resource consumption and binary integrity. The Scripts/report-size.sh script generates detailed reports on the release build to facilitate measured resource comparisons.
| Metric | Description | Source Tool |
|---|---|---|
| App Binary Size | Total bytes of the compiled Spotty executable. | stat |
| Segment Sizes | Breakdown of __TEXT, __DATA, and __LINKEDIT segments. | size -m |
| Static Archive Size | Size of the Rust-based playback archive. | stat |
| Exported Symbols | Count of global defined symbols in the playback archive. | nm -gU |
Sources: Scripts/report-size.sh:137-160, Scripts/report-size.sh:185-199
Implementation Constraints
Architecture and implementation rules for logging and diagnostics are governed by the following constraints:
- Native Behavior: Diagnostics must prioritize native macOS behavior and truthful state representation.
- Actionable Errors: User-facing errors must be actionable and privacy-safe, following the guidelines in
PRIVACY.md. - Concurrency: Swift concurrency diagnostics are treated as correctness failures; developers must not bypass them with
nonisolated(unsafe). - No Telemetry: Spotty must not include analytics, advertising, or crash-reporting SDKs that transmit data to project-operated servers.
Sources: AGENTS.md:12-14, AGENTS.md:46-49, PRIVACY.md:42-44
Summary
Unified Logging & Diagnostics in Spotty provides developer visibility through local system logs and build-time resource analysis. By leveraging Apple Unified Logging and custom shell scripts, the project ensures that diagnostic data is available for debugging without compromising the user's Spotify credentials or private account data. All diagnostic output is designed for local consumption and manual user review before any external sharing occurs.
Sources: PRIVACY.md:38-41, AGENTS.md:46-49