# Macos Telemetry

Add and verify lightweight macOS runtime telemetry.

- Repository: https://github.com/robinebers/openusage (4503 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add robinebers/openusage --skill macos-telemetry -g -a claude-code -y`
Codex: `npx skills add robinebers/openusage --skill macos-telemetry -g -a codex -y`
Cursor: `npx skills add robinebers/openusage --skill macos-telemetry -g -a cursor -y`
Gemini CLI: `npx skills add robinebers/openusage --skill macos-telemetry -g -a gemini-cli -y`

## Description

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

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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

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

The rest: https://github.com/robinebers/openusage/blob/HEAD/.agents/skills/macos-telemetry/SKILL.md