给 Mac 应用补遥测能力
基于官方 Codex macOS telemetry 场景教程，面向新手讲清什么时候加 OSLog、怎么控制范围、怎么从日志证明问题。
Mac app 里很多问题只看代码很难判断。“something happened” 这种描述太模糊。更稳的做法是让 Codex 给一个具体 feature 加少量高信号 unified logs，然后运行 app、触发路径、从 Console 或 log stream 验证事件是否按预期出现。
这类任务的重点不是“加几行 Logger”，而是建立可观察性：让你知道某个 action boundary 或 state transition 真的发生了。
先理解：什么时候该加 telemetry
适合加 telemetry 的场景包括 window opening、sidebar selection、menu commands、sync flows、导入流程、fallback path、间歇性 bug。
这些问题通常不是代码一眼能看出来，而是需要知道用户动作、状态变化和生命周期事件的顺序。
不适合一上来全局加日志。整库一墙 log 会制造噪音，也会增加隐私风险。
怎么判断范围
一次只 instrument 一个 feature。比如一个 sidebar、一个 window、一个 command、一个 sync path。
只记录重要边界：开始、结束、失败、fallback、状态切换。
长期保留的 info logs 要稳定、高信号；临时调试细节用 debug，完成前移除或降低级别。
不要记录 secrets、auth tokens、personal data 或 raw document contents。需要记录 identifier 时，使用最安全的 privacy annotation，并说明原因。
为什么用 OSLog Logger
macOS unified logging 能按 subsystem 和 category 过滤，也能和 Console.app、log stream 配合。
相比 print，Logger 更适合长期诊断，因为它能表达 category、privacy、level，并且能在系统工具里过滤。
新手不要把 telemetry 做成随手 print。那会污染输出，也不适合定位间歇性问题。
Codex 应该怎么做
先找目标 feature 的真实 control path，不要盲目在外围加 log。
再为这个 feature 选择清楚的 subsystem 和 category。
然后添加少量事件，运行 app，触发路径，用 Console filter 或 log stream predicate 证明事件出现。
如果预期事件没出现，说明 log 放错位置或路径没走到。让 Codex 把 log 移到更接近可疑 control path 的位置，而不是继续猜。
长流程怎么处理
对长流程或间歇性 bug，可以让 Codex 保存一个聚焦的小型 trace file。你手动复现，Codex 读取 trace，再整理 timeline。
这种方式比让 Codex 猜 UI 状态可靠，也比把全部系统日志交给它更安全。
新手常见坑
- 一次给全项目加日志：噪音比信息多。
- 用
print代替 unified logging。 - 记录用户内容、token、document raw text。
- 只写 Logger，不运行 app 验证。
- 只给代表性 log line，不给 filter 或 predicate。
- event 没出现时继续改业务代码，而不是先移动 instrumentation。
怎么验收
最终交付应说明添加了哪个 logger setup，哪些 events 被记录，为什么这些 events 足够解释目标 flow。
应提供使用的 Console filter 或 log stream predicate。
应说明实际运行 app 后是否看到了预期事件顺序。
如果保存了 trace file，应给出 timeline summary。
如果无法复现，应说明已确认事实、未确认假设和下一步最小验证。