Frame、逐帧来源与流畅度报告指标 v3

定义与 Registry

定义	metricID	scope	unit	来源字段
单帧耗时	`ios.frame.time`	foreground-device	milliseconds	相邻 accepted CoreProfile presented-frame `timestampNs`
平均帧率	`ios.frame.fps.average`	foreground-device	frames-per-second	`1000 / mean(FTime)`
帧率阈值占比	`ios.frame.fps.at_least_18_percent` / `ios.frame.fps.at_least_25_percent`	foreground-device	percent	`1000/FTime`
大帧与突增	`ios.frame.ftime_ge_100_percent` / `ios.frame.ftime_positive_delta_gt_100_per_hour`	foreground-device	percent / count-per-hour	FTime 与相邻正向差值
Drop / MedRange / 1% Low	`ios.frame.drop_per_hour` / `ios.frame.med_range_percent` / `ios.frame.one_percent_low_fps`	foreground-device	count-per-hour / percent / fps	FPS 序列、最慢 `ceil(N×1%)` 个 FTime
三档卡顿	`ios.frame.small_jank_per_10min` / `ios.frame.jank_per_10min` / `ios.frame.big_jank_per_10min`	foreground-device	count-per-10-minutes	当前 FTime 与前三帧均值
卡顿占时	`ios.frame.stutter_percent`	foreground-device	percent	Jank 超额耗时 / presented 时间跨度
未知定义	`ios.frame.tiny_jank_per_10min` / `ios.frame.smooth`	foreground-device	count-per-10-minutes / score	`unsupported-definition`

来源、转换与窗口

text

timestampNs = floor(machTicks × numer / denom)
frameTimeMs = (timestampNs[i] - timestampNs[i-1]) / 1,000,000
instantaneousFPS = 1,000 / frameTimeMs

RAW v2 先核验 magic、thread count 与 288 + threadCount × 32 最小边界，再从下一个绝对 64-byte 边界开始、在 8 MiB 有界窗口内寻找第一段有效 kd_buf。候选段至少连续 4 条、最多检查 32 条；timestamp 必须为正且非递减、debugid 非零、CPU ID 有效、unused=0。起点之前记为 metadataByteCount，不作为事件；起点之后仅接受 exact debugid 0x31800318。

版本：decoder core-profile-v2-presented-frame.candidate.v2；时基 mach-timebase-floor-ns.candidate.v1；汇总 frame-report.candidate.v2。首帧 warmup；窗口为单 Session 的 accepted presented-frame 序列；计算层保留 double，不做 UI 取整。

质量语义

exact debugid 为 accepted；非白名单合法记录为 rejected；header、边界、时基或残余字节失败为 unknown 并 fail closed；stackshot/bplist 为 ignored。
逆序为 out-of-order；空输入为 missing；refresh rate 缺独立来源时保持 missing。
scope 固定 foreground-device，不声明目标 PID 专属；TinyJank、Smooth 固定 Unsupported。

当前校准状态

系统	accepted / interval	unknown	结论
iOS 16 历史 raw 重放	21 / 20	0 chunk / 0 byte	E4 source，双重重放哈希一致
iOS 17.0 真机短 Trace	9 / 8	0 / 0	E4 source，双重重放哈希一致
iOS 18.2 真机短 Trace	35 / 34	0 / 0	E4 source，双重重放哈希一致

这只验证来源与算法可重放；目标 App 专属归因、长时连续性和 PerfDog 同窗数值一致性仍为 candidate。

版本历史

v3（2026-09-05）：decoder v2 支持非零 metadata；补齐 iOS 17/18 E4 与三版本确定性重放。来源：CORE-18。
v2（2026-09-05）：RAW v2/kd_buf/debugid/timebase 初版，已被本页取代。

Frame、逐帧来源与流畅度报告指标 v3 ​

定义与 Registry ​

来源、转换与窗口 ​

质量语义 ​

当前校准状态 ​