macos-telemetry

Telemetry

Quick Start

Use this skill to add lightweight app instrumentation that helps debug behavior without turning the codebase into a logging landfill. Prefer Apple's unified logging APIs and verify the events after a build/run loop.

Core Guidelines

• Prefer Logger from the OSLog framework for structured app logs.
• Give each feature a clear subsystem/category pair so runtime filtering stays easy.
• Log meaningful user and app lifecycle events: window opening, sidebar selection changes, menu commands, menu bar extra actions, sync/load milestones, and unexpected fallback paths.
• Keep info logs concise and stable. Use debug logs for noisy state details.
• Do not log secrets, auth tokens, personal data, or raw document contents.
• Add signposts only when measuring timing or performance spans; do not overinstrument by default.

Minimal Logger Pattern

import OSLog

private let logger = Logger(
  subsystem: Bundle.main.bundleIdentifier ?? "SampleApp",
  category: "Sidebar"
)

@MainActor
func selectItem(_ item: SidebarItem) {
  logger.info("Selected sidebar item: \(item.id, privacy: .public)")
  selection = item.id
}

Use feature-specific categories like Windowing, Commands, MenuBar, Sidebar, Sync, or Import so logs can be filtered quickly.

Workflow

1. Identify the behavior that needs observability.

   • Window open/close
   • Sidebar or inspector selection changes
   • Menu or keyboard command actions
   • Menu bar extra actions
   • Background load/sync/import events
   • Error and recovery paths

2. Add the smallest useful instrumentation.

   • Create one Logger per feature area or type.
   • Log action boundaries and key state transitions.
   • Prefer one high-signal line per user action over noisy value dumps.

3. Build and run the app.

   • Use macos-build-run-debug for the build/run loop.
   • If script/build_and_run.sh exists, prefer ./script/build_and_run.sh --telemetry for live telemetry checks or ./script/build_and_run.sh --logs for broader process logs.
   • Exercise the UI or command path that should emit telemetry.