Research 04 · First-party Profiler
Apple Instruments：Perfowl 的“诊断真值与产品架构老师”，不是可直接复制的实时采集 SDK
专项补齐 Instruments 本体调研：它是什么、如何采集和建模、模板与 Instrument 如何组合、xctrace 能自动化到什么程度、指标有什么语义边界，以及 Perfowl 应采用 xctrace、DVT 还是混合路线。
Executive conclusion
结论先行
推荐定位
独立 DVT 采集承担日常实时监控；xctrace 承担深度诊断、真值对照和 Trace 导入；Signpost/自定义指标承担业务语义。
不推荐定位
把 xctrace 当作可分发、跨平台、实时 JSON 数据源，或把 Core Animation FPS 直接等价成 PerfDog FrameTime/Jank。
调研范围与本机证据
- 官方资料：Apple 的 Instruments 教程、Performance and Metrics、响应性/卡顿/Metal/内存文档、WWDC Instruments 课程及 Xcode 命令行工具说明。
- 当前环境：
Xcode 26.6 (17F113)；xctrace 16.0 (17F113)。本机列出 25 个标准模板、61 个标准 Instrument。 - 设备枚举：当前只有 Mac 在线；xctrace 识别到 17 个离线物理设备记录及多个 Simulator。报告只保留数量，不记录设备名称和 UDID。
- 本机冒烟：用 Time Profiler 模板启动
/bin/sleep 1，录制约 2.27 秒并成功导出 TOC XML；Trace 为 6.3 MB，TOC 为 8,289 字节，目标正常退出。 - 冒烟 TOC 显示 Time Profiler 模板并非单一 CPU 数字：同一 Trace 同时包含 Hangs、Points of Interest、OSLog/Signpost、run loop、dyld、GCD、thread/process info、time sample 与 time profile 等 Schema。
- 未完成 iOS 真机录制、PerfDog 同场对照、xctrace 长会话开销、动态刷新率与跨 Xcode Schema 兼容，本报告不会把 Mac 冒烟外推成这些结论。
What Instruments is
产品定位：性能诊断工作台
Instruments 随 Xcode 提供，是 Apple 平台的一方性能分析工具。Apple 对它的公开定位是：实时观察 CPU、磁盘、内存、GPU 等图形 Track，定位瓶颈并下钻到代码；既可分析单个 App，也能以较低开销采样整个系统，还支持自定义 Instrument 和可视化。
它擅长
同一时间轴组合多个信号；查看调用树、Flame Graph、线程状态、系统调用、分配栈、Render Loop 和 GPU；通过符号化从地址回到源码；用 Run 对比修改前后。
它不等于
面向测试团队的任务平台、跨平台统一监控、云报告/RBAC、无需 Xcode 的可分发采集器、稳定的实时 JSON API，或已定义好业务阈值的 Pass/Fail 系统。
推荐工作方式
先定义性能症状与场景，使用 Release/优化构建在真机复现，选择匹配模板录制，缩小时间区间，从 Track 下钻根因，修改后用相同场景再次录制并比较。
结果是什么
.trace 是包含一个或多个 Run 的复合诊断产物。它保留目标、设备、模板、采集设置、Schema/Table、原始事件、模型结果、符号与展示元数据，而不只是 CSV。
Capture → Model → Diagnose
Instruments 的概念架构
Template 与 Instrument 的关系
Template 是问题导向的录制配方，Instrument 是可组合的采集/分析单元。例如 Game Performance 模板同时组合 Points of Interest、System Load、Thread State Trace、System Call Trace、Virtual Memory Trace、Time Profiler、Thermal State、Metal Resource Events、Metal Application、GPU 与 Display。用户仍可在模板上增减 Instrument、调整 Counter 和录制选项。
采集、模型和展示分离
原始数据可能来自定时 CPU 采样、内核 tracepoint、内存分配事件、统一日志、Signpost、渲染系统和设备服务。Modeler 再把事件变成更高层的 Hang、Hitch、Region of Interest 或建议；UI 负责按时间线、层级 Track、表格、调用树和 Inspector 展示。这种分离是 Perfowl 最应借鉴的架构原则。
远程 iOS 与 DVT 的边界
Instruments/xctrace 是 Apple 支持的公开工具入口；设备端开发服务、远程传输和部分 Instrument 服务属于 Xcode 内部实现。pymobiledevice3、go-ios、py-ios-device 所实现的 DVT/DTX 服务，是对这些内部协议的开源实现，不等价于 Apple 对其提供稳定公共 SDK 承诺。因此“基于 Instruments”必须区分：调用 xctrace、解析 .trace、独立实现 DVT 服务三条完全不同的路线。
Xcode 26.6 inventory
本机模板与能力盘点
| 问题域 | 本机模板 / Instrument | 能回答的问题 | 对 Perfowl 的价值 |
|---|---|---|---|
| CPU / 代码热点 | Time Profiler、CPU Profiler、CPU Counters、Processor Trace、System Trace | 哪些线程/函数占用 CPU；是否忙等、竞争、阻塞；硬件事件与指令路径 | 深度诊断与基准真值；日常采集不需要复刻全部栈采样 |
| 响应性 | Hangs、Hitches、Animation Hitches、Runloops、Thread State Trace、System Call Trace | 主线程是忙还是阻塞；Commit/Render Hitch 在哪个阶段发生 | 为 Perfowl 区分 Hang、Hitch、Frame Drop、Jank，避免只看 FPS |
| 渲染 / 游戏 | Game Performance、Game Performance Overview、Core Animation FPS、Display、Frame Lifetimes、GPU、Metal Application、Metal GPU Counters | Frame 生命周期、VSync、CPU/GPU 阶段、资源与 GPU Counter 瓶颈 | FrameTime/Jank 真值实验与 GPU 字段语义基准 |
| 内存 | Allocations、Leaks、VM Tracker、Game Memory、Data Faults | 对象何处分配、是否泄漏、虚拟内存与 Page Fault 如何变化 | 解释 Footprint 峰值的原因；区别“容量监控”和“分配诊断” |
| 启动 / 动态加载 | App Launch、dyld Activity、Time Profiler、Thread State Trace | pre-main/post-main 在运行、等待或加载什么 | 建立可重放启动场景及阶段 Marker，而非只给单一启动秒数 |
| 网络 / I/O | Network、HTTP Traffic、Network Connections、File Activity、Filesystem Activity、Disk I/O Latency | 连接、HTTP 事务、字节、RTT、文件与磁盘延迟 | 网络与存储专项；注意 HTTP 可见性和系统权限边界 |
| 能耗 / 热 | Power Profiler、System Load、Thermal State、Location Energy Model | 资源活动与能耗/热状态怎样关联 | 作为相对诊断信号，不直接冒充物理电流/电压 |
| Swift / 框架 | Swift Concurrency、Swift Tasks、Swift Actors、SwiftUI、Core ML、Foundation Models、RealityKit | 框架特有的任务、Actor、View Update、模型与渲染语义 | 证明能力应以插件/Adapter 扩展，不能把平台差异压成固定列 |
| 业务语义 | Points of Interest、os_signpost、os_log、Logging、stdout/stderr | 峰值发生在哪个用户场景、业务区间或事件 | 直接对应 Perfowl Marker、Scene、Note 与 Extension SDK |
xcodeVersion、instrumentsVersion、模板/Instrument 能力快照和解析器版本。Metric semantics
指标语义：Instruments 能作为真值老师，但不能盲抄数字
| 指标 | Instruments 视角 | 容易误解 | Perfowl 决策 |
|---|---|---|---|
| CPU | Time Profiler 通过周期采样建立调用栈的统计图；System Trace 补充线程调度、等待与系统调用 | 采样命中率不是精确执行时长；CPU 低也可能因锁/I/O 阻塞而卡顿 | 日常 CPU 曲线与深度 CPU Trace 分层；保留采样配置、目标范围和核数口径 |
| 内存 | Allocations/Leaks 回答分配与引用问题；VM/Footprint 回答进程内存压力 | Allocations 总量、Resident、Footprint、Compressed、Xcode Gauge 不是同一个值 | 每种内存独立命名和解释，不用一个“Memory”字段覆盖所有语义 |
| FPS / Hitch | Display、Frame Lifetimes、Hitches 把 App Commit、Render Server、GPU 与 VSync 放在一条帧生命周期上 | 掉帧只是系统恢复迟帧的一种方式；并非每个 Hitch 都必然表现为 frame drop | 以逐帧事件和刷新率解释体验；PerfDog Jank 另作为版本化算法，不冒充 Apple Hitch |
| Hang | 关注主 Run Loop 长时间无法处理事件；Hangs 可由忙线程或等待资源造成 | 用户感知延迟还包含事件传递和渲染；默认报告阈值不等于所有产品场景阈值 | 分开 main-runloop busy、blocked、interaction latency；阈值携带来源与版本 |
| GPU | Game/Metal 模板同时提供 GPU 活动、Frame、资源和可选 Counter | 单个“GPU %”不能解释 Renderer/Tiler、带宽、Shader、同步或热限制 | General MVP 只给明确单位的利用率；深度模式单独记录 Counter Set 与芯片能力 |
| Energy | Power/Thermal 将 CPU、GPU、网络、位置、显示等活动关联到能源影响 | Energy Impact/模型分数不自动等于瓦特、电流或单帧焦耳 | relative score 与 physical measurement 分字段、分来源展示 |
| Network | 连接、HTTP 和字节流可作为 Trace Table；xctrace 支持 HAR 导出模式 | 加密、系统栈、第三方协议和权限可能造成字段缺失 | 声明事务级/连接级/进程累计量的 coverage，不把不可见流量算作 0 |
Supported automation surface
xctrace：官方自动化入口与边界
Apple 的 Xcode 命令行说明将 xctrace 定义为管理 Instruments 文件的工具。本机版本支持七类命令：
| 命令 | 能力 | Perfowl 可用方式 |
|---|---|---|
record | 按模板/Instrument 录制；Launch、Attach、All Processes；选择设备；时间上限、尾部窗口、追加 Run、加载 Package | 深度诊断任务和真值对照，不作为 1 Hz 主曲线唯一来源 |
list | 列出 Devices、Templates、Instruments | 建立 capability snapshot，启动前明确 supported/unsupported |
export | 导出 TOC、按 XPath 导出 XML；支持 HAR 模式 | Trace 导入管线：先读 TOC 再按 Schema 选择解析器 |
import | 把支持的文件导入 .trace，例如 logarchive / ktrace，并可指定模板 | 导入系统日志、Tailspin 等证据，与 Perfowl Session 关联 |
symbolicate | 使用 dSYM 符号化 Trace | 在有符号权限时把地址还原到函数；报告保留符号质量 |
remodel | 用当前安装的 Modeler 重新处理 Trace，可加载 Instruments Package | 解析器/模型升级后的离线重算，但必须保留原 Trace 和工具版本 |
version | 报告 xctrace 版本 | 写入 Session manifest，作为 Schema 与行为兼容键 |
重要自动化限制
- xctrace 的稳定产物是
.trace与导出文件，不是官方承诺的通用实时 JSON 流。若为了实时图表频繁停止/导出 Trace，时延与开销都不可接受。 - XPath 依赖 Trace TOC 的 Schema；模板、Instrument、Schema 和 Modeler 会随 Xcode 版本变化。解析必须 capability-first，不能写死一套 XPath 后假设永久有效。
- 它依赖 macOS 上已安装并选中的完整 Xcode。作为 Perfowl 产品依赖时，还要单独确认 Xcode 许可、安装体积、版本管理、用户权限和不可打包重分发的边界。
- 真机录制依赖设备在线、Developer Mode、信任/配对、Device Support 与相关系统服务；“xctrace 命令存在”不等于任意 iOS 版本和任意 App 都能稳定采集。
- 符号化深度取决于目标 App 和系统符号的可用性。对第三方 App 的黑盒测试通常只有进程/系统层信息，无法保证业务源码级根因。
Different products, different strengths
Instruments、PerfDog 与 Perfowl 的关系
| 维度 | Apple Instruments | PerfDog | Perfowl 应选择 |
|---|---|---|---|
| 核心目标 | 开发者深度诊断和根因定位 | 低门槛持续采集、测试、报告和对比 | General Monitoring + On-demand Diagnosis 双层产品 |
| 数据模型 | Trace / Run / Schema / Track / Detail / Inspector | Project / Task / Metric / Scene / Report | Session 内保留 Trace 思维，Workspace 提供测试任务思维 |
| 采集范围 | Apple 平台；大量一方系统与框架信号 | 多平台统一体验 | 先 iOS 正确，再用 Adapter 扩平台 |
| 自动化 | xctrace 面向录制、导入、导出、符号化 | Service、CLI、CI、批量设备 | 自建稳定 Service API；深度任务内部可调 xctrace |
| 实时曲线 | 强诊断 UI，但自动化输出偏批处理 Trace | 面向测试过程的连续指标曲线 | 独立 DVT 事件流驱动实时曲线，Trace 异步导入 |
| 业务语义 | OSSignpost、Points of Interest、自定义 Instrument | Label、Note、Extension 指标 | 统一成 Marker / Interval / Scene / Custom Metric Contract |
| 可信度 | 平台一方语义，但也受配置、采样和版本影响 | 厂商算法和声明，需黑盒验证 | 保存来源、方法版本、质量和对照证据，不宣称绝对真值 |
Architecture decision
Perfowl 的三条实现路线
| 路线 | 优点 | 缺点 | 结论 |
|---|---|---|---|
| A. xctrace Wrapper 直接录制/导出 | Apple 一方工具；最快获得 CPU 栈、Hitch、Allocations、Metal 等深度数据；可作为真值对照 | 依赖完整 Xcode/macOS；批处理 Trace；Schema 漂移；分发和权限边界；不适合低延迟跨平台主链路 | 只做诊断 Adapter |
| B. 独立 DVT Collector pymobiledevice3/go-ios 等 | 可持续输出结构化实时数据；可控 Session/质量/重连；有机会跨平台 Host | 使用非公开内部协议；iOS/Xcode 演进兼容成本高；深度诊断覆盖难追平 Instruments | 做 General Core |
| C. 混合架构 DVT + xctrace + Extension | 实时监控、深度诊断和业务语义各用最合适工具；基础层失败不被深度任务拖垮 | 统一时钟、会话关联、能力矩阵和双工具版本管理更复杂 | 推荐 |
DeviceRuntime 管设备与 tunnel；GeneralCollector 用 DVT 输出 CPU/Memory/FPS/GPU/Network 等实时事件；TraceAdapter 按需调用 xctrace 录制 Time Profiler、Hitches、Allocations、Game Performance；ExtensionSDK 写入 Marker/Interval/Custom Metric；全部进入同一 Session manifest 和统一时钟模型。What to borrow
Perfowl 应从 Instruments 借鉴什么
1. 问题导向模板
不是让用户从 100 个指标里盲选，而是提供“流畅度、启动、内存、能耗、网络、长稳”等模板，每个模板声明采集器、开销等级和退出门槛。
2. Session / Run
一次 Session 可含多个重复 Run；配置相同才允许直接比较。修复前后使用同一模板、设备、版本、场景和时间窗口。
3. Track + Detail + Inspector
Overview 先看异常区间；Detail 看样本/事件；Inspector 看当前点的来源、单位、质量、进程、线程和关联证据。
4. 原始与模型分离
原始 Frame/CPU/Memory/Log 不可覆盖；Jank、Hang、规则判定和 AI 解释都是可版本化派生模型，可以离线重算。
5. Points of Interest
Marker 只是时间点，Interval 表达阶段，Scene 表达业务区间；三者需要稳定 ID、嵌套关系和跨源时钟误差。
6. 能力协商
启动前列出设备、平台、版本支持的 Collector/Metric/Trace Template；Unsupported 是显式状态，不是零值或空白曲线。
7. 符号化质量
保存 UUID、dSYM、系统符号和符号化状态；调用栈报告要区分已符号化、部分符号化和纯地址。
8. Profile → Fix → Verify
报告不仅展示峰值，还应保存基线、变更、复测 Run、差异和证据，形成持续改进闭环。
Revised gap assessment
补充 Instruments 后，阶段 0A 还要增加什么
| 新增工作 | 目的 | 交付物 | 完成条件 |
|---|---|---|---|
| P0 Trace Schema 基线 | 理解 xctrace TOC 与核心表，不把第三方库字段误当真值 | Time Profiler、Animation Hitches、Game Performance、Allocations 的版本化 Schema 样本 | 每个模板都有可重放 Trace、TOC、XPath、解析器和缺失字段测试 |
| P0 Frame 真值对照 | 确定 Display/Frame Lifetimes/Hitches 与 DVT Graphics 的对应关系 | 60/120Hz、静止/滚动/动画/人为卡顿场景的同场时间线 | 能解释每个迟帧、Hitch、FPS 窗口和 PerfDog Jank 的差异 |
| P0 CPU/Memory 口径对照 | 区分 Sysmontap 容量指标与 Instruments 诊断指标 | CPU 原值/归一化、Footprint/Resident/Compressed/Allocation 的字段映射 | 每个 UI 指标有 source、scope、unit、methodVersion 与误差区间 |
| P1 xctrace Adapter Spike | 验证可控录制、取消、超时、导出、符号化和产物管理 | 只用于研究的命令契约与错误矩阵，不进入产品代码 | 成功、权限拒绝、设备断开、App 退出、Trace 损坏均有明确状态 |
| P1 Xcode 兼容矩阵 | 控制模板/Schema/Modeler 漂移 | Xcode 版本 × OS × 设备 × 模板 × Schema 清单 | 旧 Trace 可读、不能读时可解释，升级不会静默改口径 |
| P1 依赖与许可决策 | 决定 xctrace 是否能成为正式产品可选依赖 | 安装检测、xcode-select、许可/分发、离线与最小版本方案 | 明确哪些能力自带、哪些复用系统 Xcode、哪些不可打包 |
Research-only next step
建议的 Instruments 专项验证计划
- I0 · 本机能力与 CLI 冒烟
已完成：Xcode/xctrace 版本、模板/Instrument 数量、Time Profiler 2 秒 Trace、TOC 导出。只证明官方 CLI 基本链路在当前 Mac 可用。
- I1 · 四类模板静态与样本解剖
Time Profiler、Animation Hitches、Game Performance、Allocations 各建立一份 Trace/TOC/Schema 字典，标注原始表、模型表、作用域、单位、采样率和版本。
- I2 · iOS 真机场景对照
选择 iOS 16、17+ 与一台 120Hz 设备，对静止、滚动、动画、CPU 压力、内存增长、App 重启做 Instruments + DVT + PerfDog 对照。
- I3 · 自动化与故障实验
验证 record/list/export/symbolicate 的取消、超时、设备断开、目标退出、权限弹窗、Trace 损坏、Xcode 切换和长会话资源占用。
- I4 · 架构决策
以测量结果决定 GeneralCollector 主实现、xctrace 诊断 Adapter 范围、Extension Contract 和首版不支持项，再提交开发计划等待批准。
主要来源
- Apple Xcode — Instruments 产品说明：实时 Track、CPU/磁盘/内存/GPU、系统采样和自定义 Instrument。
- Profiling apps using Instruments：官方 Instruments 教程入口。
- Xcode command-line tool reference：xctrace 的官方定位。
- Performance and metrics：Instruments、Organizer、响应性和性能主题总览。
- Improving your app’s performance：按 CPU、内存、能耗和 I/O 症状选择模板。
- Improving app responsiveness、Understanding hitches：Hang/Hitch、刷新周期和真机分析边界。
- Analyzing the performance of your Metal app：Game Performance 模板、Display/Thread/System/Metal/GPU 构成。
- Gathering information about memory use：内存 Gauge、Allocations 与内存风险。
- OSSignposter：业务区间与 Points of Interest。
- XCTest Performance Tests：CPU、Clock、Hitch、Memory、Signpost、Storage、Launch 指标与基线回归。
- Getting Started with Instruments、Developing a Great Profiling Experience：问题驱动工作流、自定义 Instrument 与层级 Track。
- 本机命令证据：
xcodebuild -version、xcrun xctrace version、xcrun xctrace list templates|instruments|devices、xcrun xctrace record/export（2026-09-01）。