macos-telemetry

name	macos-telemetry
description	Add and verify lightweight macOS runtime telemetry. Use when wiring Logger events or inspecting logs for windows, sidebars, menus, and actions.

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.

4. Read runtime logs and verify the event fired.

   • Use Console.app with a process/subsystem filter when that is the fastest manual check.
   • Use log stream --style compact --predicate 'process == "AppName"' for live terminal verification.
   • Prefer tighter predicates when you know the subsystem/category: log stream --style compact --predicate 'subsystem == "com.example.app" && category == "Sidebar"'

5. Tighten or remove instrumentation.

   • If the event fires, keep only the logs that remain useful for future debugging.
   • If it does not fire, move the log closer to the suspected control path and rerun.

Verification Checklist

• The app builds after telemetry changes.
• The relevant action emits exactly one clear log line or a small bounded sequence.
• The log can be filtered by process, subsystem, or category.
• No sensitive payloads are written to unified logs.
• Noisy temporary debug logs are removed or demoted before finishing.

Guardrails

• Do not use print as the primary app telemetry mechanism for macOS app code.
• Do not leave a dense trail of permanent debug logs around every state mutation.
• Do not claim an event is wired correctly until you have a concrete verification path through Console, log stream, or captured process output.
• If the debugging task is mostly about crash/backtrace analysis rather than action telemetry, switch to macos-build-run-debug.