給 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。
如果無法復現，應說明已確認事實、未確認假設和下一步最小驗證。