外观
StartupTiming 启动阶段指标 v5
定义
StartupTiming 同时保留两条互不替代的时间线：
- CoreProfile App Launch Lifecycle：CoreProfile 在受控冷启动前就绪，按目标 PID/TID 还原 App Launch Total 与九类内部阶段。
- 外部观察：从 Perfowl 发送 launch 请求到轮询观察到进程或前台的耗时，带 polling 误差上界。
v5 增加跨版本事件映射审计口径。审计结果用于决定某个 KDebug code 是否有资格进入阶段映射，不直接生成新的业务指标值。
metricID、scope、unit 与来源字段
| metricID | 定义 | scope | unit | 来源字段 |
|---|---|---|---|---|
ios.process.startup.app_launch_total_ms | App Launch 完整首尾耗时 | process | milliseconds | System Interface begin → 与 Initial Frame begin 配对的 terminal |
ios.process.startup.system_interface_ms | System Interface Initialization | process | milliseconds | 版本化 lifecycle mapping 的完整 Span |
ios.process.startup.static_runtime_ms | Static Runtime Initialization | process | milliseconds | 版本化 lifecycle mapping 的完整 Span |
ios.process.startup.uikit_initialization_ms | UIKit Initialization | process | milliseconds | 版本化 lifecycle mapping 的完整 Span |
ios.process.startup.uikit_scene_creation_ms | UIKit Scene Creation 完整 Span 之和 | process | milliseconds | 同 generation 的全部完整同名 Span |
ios.process.startup.will_finish_launching_ms | willFinishLaunchingWithOptions() | process | milliseconds | 版本化 lifecycle mapping 的完整 Span |
ios.process.startup.did_finish_launching_ms | didFinishLaunchingWithOptions() | process | milliseconds | 版本化 lifecycle mapping 的完整 Span |
ios.process.startup.scene_will_connect_ms | sceneWillConnectTo() | process | milliseconds | 版本化 lifecycle mapping 的完整 Span |
ios.process.startup.scene_will_enter_foreground_ms | sceneWillEnterForeground() | process | milliseconds | 版本化 lifecycle mapping 的完整 Span |
ios.process.startup.initial_frame_rendering_ms | Initial Frame Rendering | process | milliseconds | UIKit begin → 与该 begin 配对的呈现 terminal |
ios.process.startup.observed_running_ms | launch 请求到观察到进程 | process | milliseconds | launch.requested.raw → observed-running/rebound |
ios.process.startup.foreground_ready_ms | launch 请求到观察到前台 | process | milliseconds | launch.requested.raw → observed-foreground |
Registry 事实源：MacApp/Sources/PerfowlCore/PerformanceModels.swift。CoreProfile 源为 dvt.coreprofilesessiontap.kdebug；外部观察源为 lifecycle-observer。
计算、窗口、差分/聚合与取整
阶段指标算法继续使用 core-profile-app-lifecycle.candidate.v2：
text
timestampNs = floor(machTicks × timebaseNumer / timebaseDenom)
spanDurationMs = (endTimestampNs - startTimestampNs) / 1,000,000
phaseTotalMs = sum(同 phase 的所有完整 Span durationMs)
appLaunchTotalMs = (initialFrameEndTimestampNs - systemInterfaceBeginTimestampNs) / 1,000,000- 窗口是一次
controlled-cold-launch的单一 PID/generation，不跨启动聚合。 - 同名阶段按线程内 stack 配对；重复 UIKit Scene Creation 保留原始 Span，指标值为完整 Span 求和。
- App Launch Total 使用完整首尾锚点差，不把可能重叠的阶段相加。
- 跨 CPU/分块记录先按 Mach timestamp 排序；同 timestamp 使用到达序号，transition 固定 END 在 BEGIN 前处理。
- 计算保留 Double；UI 仅格式化显示。缺值为 null/—，不写 0。
映射审计算法 startup-mapping-audit.candidate.v1：
text
baseDebugID = debugID & 0xFFFFFFFC
func = debugID & 0x3
code = (debugID & 0xFFFC) >> 2
relativeOffsetMs = (eventTimestampNs - firstTargetLifecycleTimestampNs) / 1,000,000
occurrenceRate = sessionsContainingFingerprint / eligibleSessionCount- fingerprint 为
baseDebugID + func；arg0不参与主键，避免把同一事件的长度、计数或地址拆成大量伪 code。 - 每个 fingerprint 另存
arg0直方图：0...65535范围内保留整数，否则写large-or-pointer。arg0 只能辅助定义 predicate，不能单独赋予阶段语义。 - 只聚合 identity verified、drop=0、raw 严格校验通过的 Session。
- 晋级门槛为同一系统小版本至少 3 次冷启动、至少 2 个不同 App，并具有 xctrace/Fixture/Apple 符号之一的独立语义证据。
质量语义
candidate：目标归因、首尾闭合和 Span 完整；私有映射仍需跨版本校准。partial：至少有已接受 Span/marker，但存在缺 BEGIN/END；只有完整 Span 产生时长。missing：未绑定目标 PID，或目标 lifecycle 事件未观察到。unsupported-schema：RAW v2 header、Mach timebase 或时间范围违反冻结契约。unmapped：事件已通过目标归因进入 census，但没有达到映射晋级门槛；它不是指标值。mapping-eligible：只表示重复性和独立证据门禁均满足，仍需代码评审和匹配测试后才能成为正式 mapping。
当前校准状态
- E1：py-ios-device
2.4.26的 CoreProfile 协议及旧映射已核对；该映射不是 Apple 公开稳定契约。 - E2：受控启动、唯一 DTX owner、RAW v2、PID/TID、Span、最终质量和九阶段 UI 已实现。
- E4 partial：iOS 17/18 的采集、身份、停止和最终派生链已通过，但旧 code 不能完整解释当前事件，App Launch Total 正确保持 null。
- Mapping v3 进行中：先生成匿名 code census；没有独立语义证据时，不根据相邻顺序添加新映射。
当前入口仍是“条件可用”。外部 Running/Foreground 可独立显示；内部阶段只有在当前系统/App 的事件被版本化 mapping 完整闭合时才显示。
版本历史
- v5（2026-09-06）：冻结
startup-mapping-audit.candidate.v1、fingerprint、跨 Session 聚合和映射晋级门槛。来源：Startup Mapping v3 方案。 - v4（2026-09-06）：新增 CoreProfile App Launch Total + 9 类阶段及最终质量链。
- v3（2026-09-06）：两项启动外部观察值进入实时 wire 与工作台。
- v2（2026-09-05）：起点前移到 launch 发送之前，加入身份核验。
- v1（2026-09-05）：建立两项启动观察耗时。