# Macos Telemetry Probe

> macOS runtime telemetry: add and verify privacy-safe Logger/OSLog events, log stream filters, and signposts; not crash diagnosis.

- Skill: `xopoko/macos-telemetry-probe` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add xopoko/macos-telemetry-probe`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xopoko/macos-telemetry-probe/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Xopoko (https://skillmd.com/u/xopoko)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/xopoko/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.

```swift
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:

   ```bash
   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`.