名称： instruments-profiling
描述： 使用 Instruments/xctrace 对原生 macOS 或 iOS 应用进行性能分析时使用。涵盖正确的二进制文件选择、CLI 参数、导出以及常见问题。
元数据：
short-description: 适用于 macOS/iOS 应用的 Instruments 性能分析

Instruments 性能分析 (macOS/iOS)

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

快速开始 (CLI)

• 列出模板：xcrun xctrace list templates
• 记录时间分析器（启动应用）：
• xcrun xctrace record --template 'Time Profiler' --time-limit 60s --output /tmp/App.trace --launch -- /path/To/App.app
• 记录时间分析器（附加到进程）：
• 自行启动应用，获取 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 图形界面工作流

• 模板：时间分析器
• 使用“录制”并捕获慢速路径（启动阶段 vs 稳定状态）
• 调用树使用技巧：
• 隐藏系统库
• 反转调用树
• 按线程分离
• 关注热点帧和调用次数

常见问题与解决方案

• 分析了错误的应用：LaunchServices 解析到了已安装的应用而非本地构建版本。
• 解决方案：使用直接的二进制文件路径，或使用已知 PID 进行 --attach。
• 没有样本 / 空追踪文件：应用退出过快或从未执行到目标工作负载。
• 解决方案：延长捕获时间，在录制期间触发工作负载。
• 隐私提示：xctrace 可能需要开发者工具权限。
• 解决方案：系统设置 → 隐私与安全性 → 开发者工具 → 允许终端/Xcode。
• 大型 XML 导出文件：time-profile 导出的文件可能非常庞大。
• 解决方案：使用 XPath 进行过滤并在离线状态下聚合；不要直接输出到终端。

iOS 特定说明

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

验证清单

• 确认追踪文件中的进程路径与目标构建版本匹配。
• 确认堆栈显示了预期的应用帧。
• 捕获覆盖了慢速操作（启动/刷新）。
• 如果进行优化，导出堆栈以便进行自动化差异比较。