instruments-profiling

Instruments 性能分析（macOS/iOS）

当用户需要对原生应用进行性能分析或堆栈分析时，使用此技能。 重点：Time Profiler、xctrace CLI，以及选择正确的二进制文件／应用实例。

快速入门（CLI）

• 列出模板：xcrun xctrace list templates
• 录制 Time Profiler（启动应用）：
  • xcrun xctrace record --template 'Time Profiler' --time-limit 60s --output /tmp/App.trace --launch -- /path/To/App.app
• 录制 Time Profiler（附加到进程）：
  • 手动启动应用，获取 PID，然后：
  • xcrun xctrace record --template 'Time Profiler' --time-limit 60s --output /tmp/App.trace --attach <pid>
• 在 Instruments 中打开跟踪文件：
  • open -a Instruments /tmp/App.trace

注意：xcrun xctrace --help 不是有效的子命令。请使用 xcrun xctrace help record。

选择正确的二进制文件（至关重要）

注意：Instruments 可能会分析错误的应用（例如 /Applications 中的应用），因为 LaunchServices 可能解析到其他应用包。 请遵循以下规则：

• 优先使用二进制文件的直接路径，以确保启动目标明确：
  • xcrun xctrace record ... --launch -- /path/App.app/Contents/MacOS/App
• 如果启动 .app，请确保它是目标应用包：
  • open -n /path/App.app
  • 使用 ps -p <pid> -o comm= -o command= 验证
• 如果 /Applications/App.app 和本地构建版本同时存在，请明确指定本地构建版本的路径。
• 启动后，先确认进程路径，再采信跟踪结果。

命令参数（xctrace）

• --template 'Time Profiler'：模板名称，来自 xctrace list templates。
• --launch -- <cmd>：-- 后的所有内容都是目标命令（二进制文件或应用包）。
• --attach <pid|name>：附加到正在运行的进程。
• --output <path>：.trace 输出路径。若省略，文件会保存到当前工作目录。
• --time-limit 60s|5m：设置采集时长。
• --device <name|UDID>：在 iOS 设备上运行时必需。
• --target-stdout -：将已启动进程的标准输出流式传输到终端（适用于 CLI 工具）。

导出堆栈（CLI）

• 检查跟踪表：
  • xcrun xctrace export --input /tmp/App.trace --toc
• 导出原始时间分析样本：
  • xcrun xctrace export --input /tmp/App.trace --xpath '/trace-toc/run[@number="1"]/data/table[@schema="time-profile"]' --output /tmp/time-profile.xml
• 使用脚本（Python/Rust）进行后处理，汇总堆栈。

Instruments UI 工作流

• 模板：Time Profiler
• 使用“Record”并采集运行缓慢的路径（启动与稳定运行阶段）
• 调用树提示：
  • 隐藏系统库
  • 反转调用树
  • 按线程分开
  • 重点查看热点帧和调用次数

注意事项与修复方法

• 分析了错误的应用：LaunchServices 解析到已安装的应用，而不是本地构建版本。
  • 修复：使用二进制文件的直接路径，或通过已知 PID 使用 --attach。
• 没有样本／跟踪为空：应用快速退出，或没有执行任何工作。
  • 修复：延长采集时间，并在录制期间触发工作负载。
• 隐私提示：xctrace 可能需要“开发者工具”权限。
  • 修复：系统设置 → 隐私与安全性 → 开发者工具 → 允许 Terminal/Xcode。
• XML 导出文件过大：time-profile 导出的文件可能非常大。
  • 修复：使用 XPath 进行筛选，并离线汇总；不要输出到终端。

iOS 特定说明

• 设备：使用 xcrun xctrace list devices 和 --device <UDID>。
• 如有需要，通过 Xcode 启动；使用 xctrace --attach 附加到进程。
• 确保有调试符号，以便获得有意义的堆栈。

验证清单

• 确认跟踪进程路径与目标构建版本一致。
• 确认堆栈中显示了预期的应用帧。
• 确认采集覆盖了运行缓慢的操作（启动／刷新）。
• 如果正在进行优化，请导出堆栈以便自动比较。