telemetry
Add and verify lightweight macOS runtime telemetry. Use when wiring Logger events or inspecting logs for windows, sidebars, menus, and actions.
- License 许可
- MIT
- 最近更新
- 2026-09-22
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- telemetry
- description
- Add and verify lightweight macOS runtime telemetry. Use when wiring Logger events or inspecting logs for windows, sidebars, menus, and actions.
02 资源文件 1
- 参考文档agents/openai.yaml343 B
03 SKILL.md 正文
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
Loggerfrom theOSLogframework 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
-
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
-
Add the smallest useful instrumentation.
- Create one
Loggerper feature area or type. - Log action boundaries and key state transitions.
- Prefer one high-signal line per user action over noisy value dumps.
- Create one
-
Build and run the app.
- Use
build-run-debugfor the build/run loop. - If
script/build_and_run.shexists, prefer./script/build_and_run.sh --telemetryfor live telemetry checks or./script/build_and_run.sh --logsfor broader process logs. - Exercise the UI or command path that should emit telemetry.
- Use
-
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"'
-
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
printas 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
build-run-debug.
04 同仓库更多 Skills
skill-installer
Install Codex skills into $CODEX_HOME/skills from a curated list or a GitHub repo path. Use when a user asks to list installable skills, install a curated skill, or install a skill from another repo (including private repos).
skill-creator
Create or update a Codex skill with appropriately scoped instructions and any needed supporting resources.
review-agent
Perform a read-only, defect-first review of a specified code change and return every actionable finding. Use when another agent delegates review of uncommitted changes, a base-branch diff, a commit, or custom review instructions.
plugin-creator
Create and scaffold plugin directories for Codex with a required `.codex-plugin/plugin.json`, optional plugin folders/files, valid manifest defaults, and personal-marketplace entries by default. Use when Codex needs to create a new personal plugin, add optional plugin structure, generate or update marketplace entries for plugin ordering and availability metadata, or update an existing local plugin during development with the CLI-driven cachebuster and reinstall flow.
openai-docs
Use for Codex models/pricing, scheduled tasks, skills, settings, setup, troubleshooting, customization, automations, and self-knowledge—including 'you,' 'your,' 'this app,' or 'this coding agent' when they refer to Codex—and for OpenAI APIs/products and ChatGPT Work. Also use for model choice/migration, prompting, SDKs, Responses, Realtime, agents, evals, and Chat/Work/Codex comparisons. Do not use for generic app/software tasks that merely mention Codex.
imagegen
Generate or edit raster images when the task benefits from AI-created bitmap visuals such as photos, illustrations, textures, sprites, mockups, or transparent-background cutouts. Use when Codex should create a brand-new image, transform an existing image, or derive visual variants from references, and the output should be a bitmap asset rather than repo-native code or vector. Do not use when the task is better handled by editing existing SVG/vector/code-native assets, extending an established icon or logo system, or building the visual directly in HTML/CSS/canvas.