外观
Perfowl 技术术语速查
知识库会保留必要的 iOS 性能与 Perfowl 工程术语，但不要求读者第一次看到就已经熟悉。站点会在每篇知识文章中自动为少量高价值工程术语的首次出现补上 ⓘ 悬浮解释（每页有数量上限，代码、链接和标题不注入），需要更完整定义时再回到本页。
Scope
Scope = 指标作用范围。 它回答“这个数值描述谁”：目标 App 进程、整台设备，还是目标 App 位于前台时的屏幕/图形表现。
Perfowl 当前常见三类：
process：目标 App 进程自身；device：整台 iPhone；foreground-device：目标 App 前台期间的显示或设备级图形事实。
Registry
Registry = 指标注册表 / 指标合同源。 它保存正式 metricID、显示名、Scope、单位、source、sourceKey 与 definitionVersion 等字段，用于让 Swift、Python、报告和文档对“这个指标到底是什么”保持一致。
它是工程合同，不是普通读者必须先理解的入口。
Canonical
Canonical = 当前唯一权威定义。 某个 metricID 的 Canonical 页面负责解释它的业务定义、公式、质量、证据和版本边界。历史实现可以保留，但不能同时出现两套互相冲突的当前定义。
Source
Source = 原始事实来源。 例如 sysmontap、Graphics、CoreProfile、ActivityTrace、Diagnostics。Source 是“数据从哪里来”，Metric 是“产品最终向用户表达什么”，二者不是同一层。
Source Contract
Source Contract = 指标与数据源之间的正式映射合同。 它规定某个 metricID 由哪一类 adapter/source 提供，并参与 CapturePlan 合法性检查。
Evidence / E1–E4
Evidence = 当前结论验证到哪一层。 Perfowl 开发记录常用 E1–E4 区分静态证据、离线/集成证据和真实设备证据。最重要的原则是：某个 source 在一台 iOS 17 真机 E4，不等于所有派生 metric、所有 iOS 版本都自动 E4。
Warmup
Warmup = 数据源已经开始工作，但算法前提还没建立。 例如 Counter 需要前一个计数点，FrameTime 在 source restart 后需要先建立第一帧 anchor。Warmup 不是 0，也不是 source 失效。
Missing
Missing = 当前没有足够事实得到可信数值。 Perfowl 不用 0 伪装 missing，也不长期保持旧值制造假连续曲线。
Discontinuity
Discontinuity = 前后数据不能安全连续计算。 例如 PID 重启、sourceEpoch 改变、display 切换或 prev_frame 链断裂。遇到断链后，依赖前值/窗口的算法通常重新 warmup。
Source Epoch / Reconnect Generation
它们用于标识“这条 source 连续流是否仍属于同一次连接/生命周期”。只要 epoch 或 reconnect generation 改变，就不能无条件拿断开前最后一个样本和重连后第一个样本做差。
Definition Version
definitionVersion = 指标定义版本。 当 source ownership、公式、窗口、Scope、单位、quality 或 reset 规则发生会改变指标语义的变化时，应升级 definitionVersion，让历史 Session 可以按原定义回放，而不是被新公式静默重写。
Legacy
Legacy = 仍保留兼容价值，但不再承担当前新 Session 主职责。 例如 Display Performance 切到 ActivityTrace FrameLifetime 后，旧 CoreProfile Presented Frame decoder 仍可以用于历史 Session replay 或受控比较。
Gauge
Gauge = 瞬时快照值。 每次采样独立成立，不依赖前一个点（如 APP CPU、Thread Count、Energy Cost）。Gauge 缺失时应保持 missing，不能用上一个点的值填充制造假连续。
Cumulative Counter
Cumulative Counter = 只增不减的累计计数器。 例如 Context Switch、Interrupt Wakeup、Network/Disk 的累计字节。产品指标通常不是这个原始累计值本身，而是相邻两点差分得到的速率（见 Interval Rate）；进程重启或计数器回绕会造成 counter-reset，此时不能直接差分，需要重新 warmup。
Interval Rate
Interval Rate = 用两次采样之间的差值除以经过时间得到的速率。 rate = (current - previous) / elapsed。首个点没有前值，标记为 warmup；elapsed 异常（如时钟回退、窗口过短）时应保持 missing 而不是产出失真的尖峰值。
Source-native
Source-native = 原样保留系统/工具给出的值和单位，不擅自加工或换算。 例如 Energy Cost 是 Apple 私有加权分值（source-native-cost），不换算成瓦特/焦耳；GPU Dynamic Counter 的 counter name 与单位未经证据确认前不猜测物理含义。Source-native 是一种诚实边界，不是"偷懒不做计算"。
Presentation
Presentation = 显示管线记录的一次画面呈现事实/时间点。 它区别于“App 提交了一帧数据”的时刻；Perfowl 的 FrameTime/FPS 依据 Presentation 相关时间戳计算。这里描述的是系统显示管线事件，不是光子到眼（photon-to-eye）的物理测量。
Compositor
Compositor（合成器）= 系统负责把多个图层/表面组合进最终显示管线的组件。 App 渲染内容需要经过系统合成与显示调度才能形成 Presentation；Compositor 相关时间不等同于 App 自身 CPU/GPU 某个单独阶段的耗时。
Mach Timebase
Mach Timebase = XNU 内核用于把 mach 时钟 tick 转换为纳秒的换算系数。 不同 source（Host Monotonic、Device Mach、Source-native Cocoa 时间戳）使用不同的 clock domain，跨 source 换算时必须使用正确的 timebase，不能假设 1 tick = 1 纳秒。
Jetsam / memorystatus
Jetsam = iOS 在内存压力下强制终止进程的系统机制（内核 memorystatus 子系统的一部分）。Physical Footprint 逼近某个阈值只是提示 Jetsam 风险上升的候选信号之一，不是 Jetsam 判定的唯一依据；真正的 Jetsam 判定逻辑由内核按当前系统整体内存压力动态决定，不是 App 可预先精确计算的固定红线。
Resident / Footprint
Resident（驻留内存）≠ Physical Footprint。 两者是不同的内存统计口径：Resident 更接近当前驻留页规模，Physical Footprint 是 Apple 内存记账体系中的 footprint 口径，常用于分析进程内存压力。二者不能互相替代，也不能仅凭差值推导“泄漏”或 Jetsam 原因。详见 Physical Footprint 与 Real Memory。
QoS
QoS（Quality of Service）= 提交给系统调度器的任务优先级/能效提示。 常见等级如 UserInteractive、UserInitiated、Utility、Background。QoS 不是把某类任务固定绑定到某类核心（P-Core/E-Core）的静态规则——具体调度到哪个核心由内核结合系统负载、热状态等因素动态决定。
DTX / Lockdown / RSD
DTX = Apple Instruments 使用的私有传输协议（Distributed Test eXecution），Perfowl 通过 pymobiledevice3 复用该协议连接 com.apple.instruments.server.services.* 等服务。Lockdown = iOS 设备侧的服务发现与握手协议，早期 iOS 版本的多数系统服务通过它启动。RSD（Remote Service Discovery）= 较新 iOS 版本（无线/网络场景）下替代部分 Lockdown 职责的服务发现机制。 三者是不同层级的连接基础设施，不是同一个协议的不同名字。
Lifecycle Span
Lifecycle Span = 应用生命周期中一个有明确起止点的阶段区间（如 System Interface Initialization、UIKit Initialization）。Startup Phases 的各项指标本质上是对应 Lifecycle Span 的时长；一个 Span 是否出现取决于真实的应用生命周期路径，不是所有 App 在所有场景下都会经过全部 Span。
Endpoint Provenance
Endpoint Provenance = 一段耗时测量的起点和终点分别来自什么证据源。 例如 App Launch Total 的起点/终点分别绑定到哪个系统事件，必须明确标注，不能笼统地说"从点击图标到首帧"而不说明具体锚点的证据来源，否则跨版本、跨机型的耗时无法保证口径一致。
Phase Coverage
Phase Coverage = 本次启动实际形成可信 span 的阶段覆盖情况。 Coverage 不完整（例如 5/9）不等于 Total 必然无效；但缺失既可能是该生命周期路径确实不适用，也可能是观测/配对缺失。只有存在独立证据时才能标记 not-applicable，否则应保持 missing。详见 Startup Phases。
Battery-only
Battery-only = 设备处于真正纯电池放电状态的判定条件（ExternalConnected=false 且 IsCharging=false 且电流方向为放电）。Battery Current/Voltage/Power 只有在这个门禁成立时才有物理意义；USB 连接时这些值应保持 missing，不能展示为 0 或符号不明的数值。详见 Battery Electrical。