use-cases/macos-telemetry-logs.md +161 −0 added
1---
2name: Add Mac telemetry
3tagline: Use Codex to instrument one Mac feature with Logger, run the app, and
4 verify the action from unified logs.
5summary: Use Codex and the Build macOS Apps plugin to add a few high-signal
6 `Logger` events around windows, sidebars, commands, or sync flows, then run
7 the app and prove from Console or `log stream` that the right actions fired.
8skills:
9 - token: build-macos-apps
10 url: https://github.com/openai/plugins/tree/main/plugins/build-macos-apps
11 description: Use the macOS telemetry and build/run skills to add structured
12 `OSLog` instrumentation, launch the app, exercise the UI path, and verify
13 the emitted events from Console or `log stream`.
14bestFor:
15 - Mac app features where Codex needs a reliable trace of window opening,
16 sidebar selection, menu commands, menu bar actions, sync milestones, or
17 fallback paths
18 - Agentic debugging loops where Codex should patch code, rerun the app,
19 inspect logs, and decide the next fix from evidence instead of guessing
20 - Local app-session collection loops where you want a compact sequence of user
21 actions and app lifecycle events that can be compared across repeated runs
22starterPrompt:
23 title: Instrument One Feature and Verify It from Logs
24 body: >-
25 Use the Build macOS Apps plugin to add lightweight unified logging around
26 [name one Mac feature or action flow], then run the app and verify from logs
27 that those events fire in the expected order.
28
29
30 Constraints:
31
32 - Prefer `Logger` from `OSLog`, not `print`, and create a clear
33 subsystem/category pair for this feature so the logs are easy to filter.
34
35 - Log one concise line for each important action boundary or state
36 transition: for example window opened, sidebar selection changed, menu
37 command invoked, sync started, sync finished, or fallback path taken.
38
39 - Keep permanent `info` logs stable and high signal. Use `debug` only for
40 noisy local details, and remove or demote temporary instrumentation before
41 finishing.
42
43 - Do not log secrets, auth tokens, personal data, or raw document contents.
44 If an identifier must be logged, choose the safest privacy annotation and
45 explain why.
46
47 - Build and run the app, exercise the feature path yourself, and verify the
48 events with Console or a focused `log stream` predicate.
49
50 - If the flow is long, intermittent, or easier to reproduce by hand, save
51 the filtered log stream to a small local session trace file, let me manually
52 exercise the app if needed, then read that file back and summarize the event
53 timeline.
54
55 - If an expected event does not appear, move the log closer to the suspected
56 control path, rerun the flow, and continue until the logs explain what
57 happened.
58
59
60 Deliver:
61
62 - the new logger setup and the exact events you added
63
64 - the Console filter or `log stream` predicate you used
65
66 - a short before/after summary of what the logs now make observable
67
68 - the saved trace file and timeline summary if this became a longer capture
69 session
70
71 - one or two representative log lines that prove the flow is instrumented
72 correctly
73relatedLinks:
74 - label: Build macOS Apps plugin
75 url: https://github.com/openai/plugins/tree/main/plugins/build-macos-apps
76 - label: Agent skills
77 url: /codex/skills
78techStack:
79 - need: App logging
80 goodDefault: "[OSLog Logger](https://developer.apple.com/documentation/os/logger)"
81 why: Structured unified logging gives Codex a narrow, filterable feedback loop
82 without turning the codebase into a wall of `print` statements.
83 - need: Agent workflow
84 goodDefault: "[Build macOS Apps
85 plugin](https://github.com/openai/plugins/tree/main/plugins/build-macos-a\
86 pps)"
87 why: "The plugin's telemetry and build/run skills are designed to work together:
88 instrument one flow, launch the app, inspect logs, and tighten the event
89 set."
90 - need: Runtime verification
91 goodDefault: Console.app and `log stream --predicate ...`
92 why: A concrete log filter plus sample output gives the agent a repeatable
93 handoff and makes the new instrumentation easy to verify across runs.
94---
95
96## Add one Logger where debugging gets vague
97
98This use case is for Mac app flows where "something happened" is too fuzzy to debug from code review alone. Ask Codex to add a few high-signal unified logs around one behavior, run the app, trigger that behavior, and verify from Console or `log stream` that the expected events fired.
99
100Use the [Build macOS Apps plugin](https://github.com/openai/plugins/tree/main/plugins/build-macos-apps) for that loop. Its macOS telemetry skill is intentionally lightweight: use Apple's `Logger`, choose a clear subsystem/category pair, log action boundaries and state transitions, avoid sensitive payloads, and verify the event after a local build/run instead of assuming the instrumentation is wired correctly.
101
102## Why telemetry is useful for agentic engineering
103
104Good logs give Codex a repeatable feedback loop after each patch. Instead of asking you to manually inspect every window, menu action, or sync transition, the agent can run the app, exercise the flow, inspect filtered logs, and decide the next code change from evidence.
105
106That is especially useful for three agentic loops:
107
108- **Hands-free debug loop:** Codex instruments a suspicious flow, launches the app, clicks the sidebar or triggers a command, reads the emitted log sequence, patches the state update path, and reruns the same flow until the logs and UI behavior agree.
109- **App session collection loop:** Codex adds one event for app launch, window open, sidebar selection, import started, import finished, and import failed, then runs a local session and summarizes the resulting timeline so missing or out-of-order transitions become obvious.
110- **Human-driven capture loop:** Codex launches the app with logging enabled, keeps a focused log stream running while you manually exercise a tricky flow, then inspects the captured session afterward and proposes the next patch from that trace.
111
112## Keep the instrumentation small and filterable
113
114Ask Codex for one logger per feature area, not one permanent log line for every state mutation. Feature categories such as `Windowing`, `Commands`, `MenuBar`, `Sidebar`, `Sync`, or `Import` make logs much easier to filter during the next debugging pass.
115
116```swift
117import OSLog
118
119private let logger = Logger(
120 subsystem: Bundle.main.bundleIdentifier ?? "SampleApp",
121 category: "Sidebar"
122)
123
124@MainActor
125func selectItem(_ item: SidebarItem) {
126 logger.info("Selected sidebar item: \(item.id, privacy: .public)")
127 selection = item.id
128}
129```
130
131Use `info` for concise action and lifecycle events that should remain useful over time, and `debug` for noisier local state details that may be removed or demoted before the task is done. Add signposts only when you are measuring a timing span, not by default.
132
133## Ask Codex to prove the event from logs
134
135The useful part is not just adding `Logger` calls. Ask Codex to run the app, trigger the instrumented flow, and give you the exact Console filter or `log stream` predicate it used plus one or two representative log lines.
136
137```bash
138log stream --style compact --predicate 'subsystem == "com.example.app" && category == "Sidebar"'
139```
140
141If an expected event does not appear, ask Codex to move the log closer to the suspected control path, rerun the same flow, and keep iterating until the logs explain what happened. If the task turns into a crash or backtrace analysis, pivot to the plugin's build/run debugging workflow and keep the telemetry focused on the action boundaries.
142
143## Save a session trace for a later Codex pass
144
145For longer or intermittent bugs, ask Codex to save a focused log stream to a small local trace file, summarize the timeline, and leave that artifact in the workspace so a later Codex run can inspect the same evidence without replaying the whole session from memory. That makes multi-pass debugging easier when you want one agent run to collect a trace and another run to compare behavior before and after a patch.
146
147This also works well when the human needs to drive part of the session. Ask Codex to launch the app in a logging-friendly debug loop, start a filtered capture, wait while you reproduce the issue manually, and then read the saved trace file once you are done.
148
149## Practical tips
150
151### Instrument one feature at a time
152
153Start with one sidebar, window, command, or sync path so the log sequence stays easy to inspect. If that path becomes reliable, Codex can expand the same pattern to neighboring flows.
154
155### Make privacy part of the prompt
156
157Ask Codex to explain every logged identifier and to avoid writing secrets, personal data, or raw content to unified logs. A tiny event vocabulary is usually enough for local debugging.
158
159### Keep sample output in the final summary
160
161Representative log lines make the change much easier to trust than "telemetry was added." Ask Codex to include the filter predicate and a short action timeline so the next agent run can reuse the same verification loop.