telemetry

遥测

快速入门

使用此技能添加轻量级应用埋点，帮助调试行为，同时避免代码库变成日志堆积场。优先使用 Apple 的统一日志 API，并在构建／运行循环后验证事件。

核心指南

• 使用 OSLog 框架中的 Logger 记录结构化应用日志。
• 为每个功能设置清晰的子系统／类别组合，便于在运行时筛选。
• 记录有意义的用户操作和应用生命周期事件：窗口打开、侧边栏选择变化、菜单命令、菜单栏额外项操作、同步／加载里程碑，以及意外的回退路径。
• 信息日志应简洁、稳定。使用调试日志记录嘈杂的状态细节。
• 不要记录机密、身份验证令牌、个人数据或原始文档内容。
• 仅在测量耗时或性能区间时添加 signpost；默认情况下不要过度埋点。

最简 Logger 模式

import OSLog

private let logger = Logger(
  subsystem: Bundle.main.bundleIdentifier ?? "SampleApp",
  category: "Sidebar"
)

@MainActor
func selectItem(_ item: SidebarItem) {
  logger.info("Selected sidebar item: \(item.id, privacy: .public)")
  selection = item.id
}

使用特定于功能的类别，例如 Windowing、Commands、MenuBar、Sidebar、Sync 或 Import，以便快速筛选日志。

工作流

1. 确定需要观测的行为。

   • 窗口打开／关闭
   • 侧边栏或检查器选择变化
   • 菜单或键盘命令操作
   • 菜单栏额外项操作
   • 后台加载／同步／导入事件
   • 错误和恢复路径

2. 添加最少但有用的埋点。

   • 为每个功能区域或类型创建一个 Logger。
   • 记录操作边界和关键状态转换。
   • 对每个用户操作，优先记录一条高信号日志，而不是输出嘈杂的值转储。

3. 构建并运行应用。

   • 使用 build-run-debug 完成构建／运行循环。
   • 如果存在 script/build_and_run.sh，实时检查遥测时优先使用 ./script/build_and_run.sh --telemetry，查看更广泛的进程日志时使用 ./script/build_and_run.sh --logs。
   • 操作应触发遥测的 UI 或命令路径。

4. 查看运行时日志并确认事件已触发。

   • 如果这是最快的手动检查方式，请使用 Console.app，并按进程／子系统筛选。
   • 使用 log stream --style compact --predicate 'process == "AppName"' 在终端中实时验证。
   • 如果已知子系统／类别，优先使用更精确的谓词： log stream --style compact --predicate 'subsystem == "com.example.app" && category == "Sidebar"'

5. 精简或移除埋点。

   • 如果事件已触发，只保留对今后调试仍有用的日志。
   • 如果事件未触发，将日志移近疑似的控制路径并重新运行。

验证清单

• 应用在遥测变更后能够构建。
• 相关操作恰好输出一条清晰的日志，或一小段有界序列。
• 可以按进程、子系统或类别筛选日志。
• 统一日志中不包含敏感负载。
• 完成前，移除临时嘈杂的调试日志，或降低其日志级别。

防护原则

• 不要在 macOS 应用代码中使用 print 作为主要的应用遥测机制。
• 不要在每次状态变更周围留下密集且永久的调试日志。
• 在通过 Console、log stream 或捕获的进程输出找到具体验证路径之前，不要声称事件已正确接入。
• 如果调试任务主要涉及崩溃／回溯分析，而不是操作遥测，请切换到 build-run-debug。