---
title: "给 Mac 应用补遥测能力"
description: "基于官方 Codex macOS telemetry 场景教程，面向新手讲清什么时候加 OSLog、怎么控制范围、怎么从日志证明问题。"
verifiedAt: "2026-05-06"
---

import { Cards, Card } from 'fumadocs-ui/components/card';

Mac app 里很多问题只看代码很难判断。“something happened” 这种描述太模糊。更稳的做法是让 Codex 给一个具体 feature 加少量高信号 unified logs，然后运行 app、触发路径、从 Console 或 `log stream` 验证事件是否按预期出现。

这类任务的重点不是“加几行 Logger”，而是建立可观察性：让你知道某个 action boundary 或 state transition 真的发生了。

> [!WARNING]
> 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。

如果无法复现，应说明已确认事实、未确认假设和下一步最小验证。

## 官方资料

- [Codex macOS telemetry logs use case](https://developers.openai.com/codex/use-cases/macos-telemetry-logs)
- [Build macOS Apps plugin](https://github.com/openai/plugins/tree/main/plugins/build-macos-apps)
- [Agent skills](https://developers.openai.com/codex/skills)
- [Apple OSLog Logger](https://developer.apple.com/documentation/os/logger)

## 接下来去哪

<Cards>
  <Card title="构建 macOS 应用" description="需要从 app shell、build、run 和 debug 建立更完整的 macOS 工作流。" href="/docs/codex/official/08-scenarios/110-macos-app" />
  <Card title="Mac App 基础壳" description="如果还没有清晰结构，先建立 sidebar、detail 和 inspector 基础形态。" href="/docs/codex/official/08-scenarios/105-mac-app-skeleton" />
  <Card title="Computer Use QA" description="需要通过 GUI 触发流程和收集证据时，看 Computer Use 验收场景。" href="/docs/codex/official/08-scenarios/113-computer-use-qa" />
  <Card title="官方 telemetry use case" description="最新插件和 OSLog 场景说明以官方页面为准。" href="https://developers.openai.com/codex/use-cases/macos-telemetry-logs" />
</Cards>
