给 Mac 应用补遥测能力
基于官方 Codex macOS telemetry 场景教程，面向新手讲清什么时候加 OSLog、怎么控制范围、怎么从日志证明问题。
📖 本篇术语速查表
| 英文 / 缩写 | 中文 | 一句话解释 |
|---|---|---|
| Telemetry | 遥测 | 收集运行数据以观察应用行为。 |
| OSLog Logger | 系统日志器 | Apple 推荐的日志记录方式。 |
| 范围控制 | scope | 控制采集什么、不采集什么。 |
不想读完？把下面这段提示词丢给 AI 帮你跑完——帮你规划给 Mac 应用补遥测能力（范围、OSLog、隐私）。
你是 Mac 应用遥测规划顾问，帮我判断该不该加 telemetry、加到什么范围、怎么用 OSLog 实现。
【角色】
你知道什么时候该加 telemetry、怎么判断采集范围、为什么用 OSLog Logger、Codex 应该怎么实现。
【输入】
- 我想通过遥测了解什么：___
- 应用类型和用户量：___
- 隐私和合规要求：___
- 现有的日志情况：___
【工作流程】
1. 判断该不该加、加什么指标
2. 控制采集范围，避免过度采集
3. 用 OSLog Logger 实现
4. 给隐私合规检查
【输出规范】
▌一、该采集的指标
▌二、采集范围控制
▌三、OSLog 实现方案
▌四、隐私合规检查
【硬约束】
- 只采集真正需要的，不过度收集
- 不采集个人隐私数据，合规优先
- 用 OSLog 而非自造方案
- 采集要可关闭、可审查
- 不确定的 API 标注需查官方文档Mac app 里很多问题只看代码很难判断。“something happened” 这种描述太模糊。更稳的做法是让 Codex 给一个具体 feature 加少量高信号 unified logs，然后运行 app、触发路径、从 Console 或 log stream 验证事件是否按预期出现。
这类任务的重点不是“加几行 Logger”，而是建立可观察性：让你知道某个 action boundary 或 state transition 真的发生了。
Telemetry 不是把用户行为全部打出来。只记录高信号边界，避免 secrets、token、个人数据和原始文档内容，并在交付时说明 filter 或 predicate。
先理解：什么时候该加 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。
如果无法复现，应说明已确认事实、未确认假设和下一步最小验证。