macos-telemetry-probe

macOS Telemetry Probe

Before invoking Apple-only binaries, confirm the execution context is macOS. From Windows or Linux, run those steps in a Mac SSH project or through an already configured remote transport; do not retry missing Apple binaries locally.

Add high-signal app instrumentation without leaving noisy permanent logs. Prefer Apple's unified logging and verify events after build/run.

Rules

• Use Logger from OSLog.
• Give each feature a clear subsystem/category.
• Log meaningful lifecycle/user events: windows, sidebar/inspector selection, commands, menu bar actions, sync/load milestones, fallback/error paths.
• Keep info logs stable; use debug for noisy state.
• Never log secrets, tokens, personal data, or raw document contents.
• Add signposts only for timing/performance spans.

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 categories like Windowing, Commands, MenuBar, Sidebar, Sync, or Import.

Workflow

1. Identify the behavior needing observability.

2. Add one useful log per action boundary or key state transition.

3. Build/run with macos-runtime-debugger; if present, prefer ./script/build_and_run.sh --telemetry or --logs.

4. Exercise the UI/command path.

5. Verify through Console or:

   log stream --style compact --predicate 'process == "AppName"'
   log stream --style compact --predicate 'subsystem == "com.example.app" && category == "Sidebar"'
   

6. Keep useful logs; remove or demote temporary noise.

Verification

Confirm the app builds, the relevant action emits exactly one clear line or bounded sequence, logs filter by process/subsystem/category, no sensitive payloads are written, and temporary debug noise is gone. If the task is mainly crash/backtrace work, switch to macos-runtime-debugger.