給 Mac 應用補遙測能力
基於官方 Codex macOS telemetry 場景教程，面向新手講清什麼時候加 OSLog、怎麼控制範圍、怎麼從日誌證明問題。
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。
如果無法復現，應說明已確認事實、未確認假設和下一步最小驗證。