2026-10-18 · 知识契约正文收口

## Documentation closeout · 2026-10-18 · Canonical正文与最新策略一致

首提交5be5962后的发布前复读发现：Canonical TotalCPU最新增量已说明同源分母，但原§三正文仍把旧缓存规则写成当前规则、版本历史仍标v4当前，容易误读。仅更新可演进知识页的当前契约/显示入口/CPUCount量程和RawMetricEngine类名，旧缓存明确限历史回放，追加v5来源；旧验收数字/结论/归档逐字保留，另新增本收口快照，不回改旧HTML。代码、测试包、五轮原件与验收结论不变；独立窄docs提交后再双推一次同一最终提交并发布，不先上线矛盾正文。

---
type: knowledge
title: TotalCPU 指标说明
date: 2026-09-18
status: published
metric: ios.device.cpu.total, ios.device.cpu.total.normalized
knowledgeRole: metric-canonical
---

# TotalCPU（整机 CPU 使用率）

**最新整机Normalized CPU · 2026-10-18（candidate限定E4）**：五新生命/Session固定240机会/120槽，显式值/同窗分母/TotalCPU图形输入别名与独立counter异常、连续性门通过，留存16/66（启动12/12、新非启动4/54）。内部b184已覆盖；下方旧Raw记录中的“下一Normalized”由本条承接，下一仅PerCore。[记录](/devlog/p4-fixture-lab-device-cpu-normalized-plan-2026-10-18)。


**最新整机Raw CPU · 2026-10-18（candidate限定E4）**：五新生命/Session固定240机会/120槽通过来源一次发表、连续性与独立counter包络异常门，留存15/66，启动12/12、新非启动3/54。旧失败保留，normalized/实际图形不顺带通过；下一仅Normalized。[记录](/devlog/p4-fixture-lab-device-cpu-raw-plan-2026-10-17)。


## 来源修复进行中 · 2026-10-17

新设计当前整机Raw仍待验收，不把既有真机记录当新的五轮通过。软件诊断已在当前源码及安装归档分别复现单源旧值重复、非法总量与初始化零值放行。拟采用`device-total-cpu-raw-source-once.v1`：每个原生设备窗口只发布一次，双角色合并待发上限6、500ms周期的host收包TTL为1.5秒，过期/未就绪/非法输入保持missing。host收包新鲜不等于设备读点已证。

新marker的Raw须有CPUCount整数1..64、EnabledCPUs整数1..CPUCount、等长逐核有限0..100及总量0..100×CPUCount，总量与逐核和容差1e-6×CPUCount；首次EnabledCPUs=0且全零明确warmup，合法零必须元数据就绪。其他CPU_UserLoad/SystemLoad为负哨兵不等于CPU_TotalLoad无效；只对所用字段验证。公式仍为原字段，不把负载线程占空比当测得值。

消费者边界：旧Swift有`totalCPURaw ?? totalCPU`兼容回退，而当前totalCPU是normalized旧别名。新marker下Raw缺失时将这个歧义别名一并置missing，保留独立totalCPUNormalized字段及既有公式；否则缺值会悄悄变成不同口径数值。历史无marker重放不变。本规则不代表normalized/per-core已验收，亦不是物理精度校准。[当前方案](/devlog/p4-fixture-lab-device-cpu-raw-plan-2026-10-17)。

**当前共享采集源（2026-10-07 G84）**：产品 `SysmontapRawAdapter._make_stream` 先用同一个 pymobiledevice3 原生 `DeviceInfo` 查询时钟与支持列，再用原生 `Sysmontap` 构造器建立完整14消费者固定依赖闭包（11进程列、3系统列）；默认 `intervalMs=500`、`ur=500 ms`、`sampleInterval=500000000 ns`，保留CPU元数据与原生时钟。必需列缺失、非法类型或重复时明确失败，不以减少指标、补值或旧值续点降级。此为采集配置修复，**不改变本页数值公式、scope、单位、质量/候选标签与独立误差门**；完整54项与正式五轮仍待验，源码/安装验证不等于本指标数值校准。[方案与验证](/devlog/p4-nonstartup-g84-shared-sysmontap-field-closure-repair-plan-2026-10-07)。

**作用域属性**：`[设备级 · 整机系统环境]`（Device Scope）
**当前状态**：Raw 口径已有真机证据；Normalized 口径的 `definitionVersion` 仍为 `candidate`，两者不能合并描述为统一的“Verified”。

TotalCPU 衡量的是**手机整机 CPU 使用率**，包含被测 App、系统进程、其他 App 与内核活动。Raw 口径采用多核未归一化累加表示，因此可以超过 100%；Normalized 口径再按 `EnabledCPUs` 归一到 0%~100% 尺度。

> 💡 **测试人员核心定位**：
> TotalCPU **不用于衡量 App 自身的代码质量**，而是用于**评估当前的测试环境是否受到严重的系统后台干扰**。当被测 App 出现卡顿时，若 TotalCPU 居高不下而 APPCpu 极低，提示可能存在外部环境争抢，是缩小排查范围的候选方向之一；仍建议清理后台、复测对比后再下结论，不能仅凭这一组合直接把责任排除给外部环境。

---

## 一、 指标核心规范与双口径说明

Perfowl 同时提供两种计算口径以满足不同的分析习惯：

| 属性项 | 物理多核总负载 (Raw) | 核心数归一化 (Normalized) |
| :--- | :--- | :--- |
| **metricID** | `ios.device.cpu.total` | `ios.device.cpu.total.normalized` |
| **数据与显示** | 显式 `totalCPURaw` / 导出；不是当前普通图入口 | 显式 `totalCPUNormalized`；普通 TotalCPU 图读同值别名 `totalCPUPercent` |
| **作用域 (Scope)** | **device**（设备级） | **device**（设备级） |
| **测量单位 (Unit)** | `percent`（百分比 %） | `percent`（百分比 %） |
| **数学公式** | `RawTotal = SystemCPUUsage.CPU_TotalLoad` | `NormalizedTotal = RawTotal / EnabledCPUs` |
| **量程范围** | 0% ~ N × 100%（N 为该原始记录的 CPUCount） | 0% ~ 100%（按 `EnabledCPUs` 归一） |
| **最佳用途** | 观察整机多核 CPU 使用率的未归一化累加值 | 将同一统计口径压到 0%~100% 尺度便于阅读；**不代表不同 SoC 的实际性能等价** |

---

## 二、 联合 APP CPU 交叉排查指南

Perfowl 不为 TotalCPU 维护跨 App、跨设备通用的“健康百分比”。更可靠的方法是在**同设备、同系统、同业务脚本、同运行条件**下比较 APP CPU 与 TotalCPU 的历史分布：

| 场景 | APP CPU（process） | TotalCPU（device） | 候选解释与下一步 |
| :--- | :--- | :--- | :--- |
| **同场基线稳定** | 与历史分布接近 | 与历史分布接近 | 环境一致性较好；仍结合质量字段、温控和后台状态确认 |
| **目标进程算力压力候选** | 相对历史基线持续显著升高 | 同窗同步升高 | 提示目标 App 算力消耗增加；用 Time Profiler / 调用栈确认具体热点 |
| **外部系统争抢候选** | 接近历史基线或偏低 | 相对历史基线明显升高 | 提示系统或其他进程负载增加；清理后台并重复同场实验 |
| **热状态影响候选** | 与正常温控轮次出现背离 | 整机负载与性能表现同时变化 | 结合 Thermal Status、GPU、FrameTime 与冷却后复测，不直接宣布发生降频 |

Raw 口径的“单核 100%”和 Normalized 口径的“整机 100%”是单位定义，不是性能好坏阈值。正式团队 SLA 应来自自己的稳定历史分布与事故数据，并注明适用设备、iOS、场景和 definitionVersion。

---

## 三、 底层数据来源与质量保证

1. **底层通道**：通过 DVT 专属协议读取 `com.apple.instruments.server.services.sysmontap` 系统快照向量，pymobiledevice3 原生 `Sysmontap(provider, process_attributes, system_attributes, interval_ms=intervalMs)` 返回；解析实现于 `MacApp/Sidecar/perfowl_collector_core/metric_engine.py::RawMetricEngine._system_metrics`；
2. **当前同源正整数核数保护（2026-10-18）**：新marker `device-total-cpu-normalized-source-once.v1` 下，只使用同一条已通过Raw来源门记录的严格整型 `EnabledCPUs`（1..CPUCount）作分母；结果须有限且0..100，缺源、缺分母、错marker或越界即 `missing`，解释字段和图形别名同步为空，绝不借缓存续点。无新marker的历史回放才保留旧 `raw-dvt-divided-by-enabled-cpu-count.candidate.v2` 缓存规则；历史规则不代表当前可信度。公式不取整，CSV误差≤1e−6。

---

## 技术溯源与十要素契约

| 要素维度 | 详细规范与技术证据 |
| :--- | :--- |
| **定义与概念** | 衡量整机 CPU 使用率，用于观察全局计算负载与识别系统后台噪声候选 |
| **metricID / scope / 单位 (unit)** | `ios.device.cpu.total` / `ios.device.cpu.total.normalized` / `device` (设备级) / percent (百分比) |
| **底层系统服务与通信通道** | 系统服务 `com.apple.instruments.server.services.sysmontap`，通过 DTX 通道 |
| **采集命令与调用实现** | 采集命令与调用实现：pymobiledevice3 `Sysmontap(provider, process_attributes, system_attributes, interval_ms=intervalMs)` 读取 `SystemCPUUsage` |
| **计算方式与精确公式** | 精确计算公式与计算方式：`RawTotal = SystemCPUUsage.CPU_TotalLoad`；`NormalizedTotal = RawTotal / EnabledCPUs` |
| **数据质量语义 (含 missing)** | 新来源严格通过时为 candidate，0合法但初始化0仅warmup；无新源、过期/复用、非法核数或Normalized越界保持missing，不补0、不续旧点 |
| **当前校准状态与证据等级 (E1~E4)** | Raw与Normalized分别以五新轮通过本场景来源/异常/连续性限定E4；Normalized另核实际Swift图形输入，均为candidate，非物理精度/任意环境保证；逐核和进程CPU不顺带通过 |

## 版本历史

| 版本 | 日期 | 修订要点 |
| :--- | :--- | :--- |
| **v5（当前）** | 2026-10-18 | Raw与Normalized分项限定E4；新marker下同窗分母、一次发布及显示元数据，旧缓存仅历史回放；[当前验收](/devlog/p4-fixture-lab-device-cpu-normalized-plan-2026-10-18)。 |
| **v4** | 2026-09-18 | 统一“CPU 使用率”术语；删除通用健康百分比阈值改为历史分布对照；修正 Normalized 公式表格；拆分 Raw/Normalized 证据状态并删除“跨芯片算力等价”暗示。 |
| **v3** | 2026-09-15 | 全面转向性能测试实战视角：明确双口径区别、交叉诊断表与测试防干扰要求。 |
| **v2** | 2026-09-08 | 规范整机原始与归一化双口径公式。 |
| **v1** | 2026-09-04 | 首次发布整机 CPU 指标定义。 |


## 采集源版本更新 · 2026-10-07

G84将SDK全列factory改为固定共享11+3列、输出与采样节拍一致；原生服务/DTX通道不变，支持列仍由SDK查询，传输及指标转换为Perfowl适配层，SDK来源和自研计算分开。初missing、counter warmup/reset、VM近似质量等原边界保留，不外推其他设备/场景持续100%。[来源批次](/devlog/p4-nonstartup-g84-shared-sysmontap-field-closure-repair-plan-2026-10-07)。

## 验收方法积累 · 2026-10-17 · 独立counter参考与工具开销

**已验证方法及限制**：自有测试台通过普通Mach host端口读取六核USER/SYSTEM/IDLE/NICE累计uint32计数，取原始位值、设备调用前后时钟及缓冲/端口释放结果；用两侧读数的单调性给出原生源窗口的busy比例包络，不用忙闲负载设定值冒充测量。固定包络宽与端点距离门在正式采集前冻结，参考缺失/太宽记unassessed，不能用0..600的无信息区间证明数值无异常。系统服务与参考可能共享内核统计，独立调用不等于物理仪器或完整私有实现等价。CPU具体误差与新五轮仍待验收。[来源方案](/devlog/p4-fixture-lab-device-cpu-raw-plan-2026-10-17)。

**真实坑与复现**：首个36秒100Hz参考对照，工具CPU增量约1.781个百分点和内存约76KiB满足资源差门，但完整read/encode/append P95为1.040792ms，超过预定1ms。仅看资源比较JSON的withinDeclaredBudget会漏掉另一个独立失败门。判断时应分别核对绝对值/增量、完整路径mean/P95/max、调用与编码写入测量边界，最后按全部条件合取。当前正在优化固定CPU整数事件编码，未改1ms门、100Hz或数据分母；这一方法积累不是指标验收通过。工具E4、产品正式E4与最终分发门分别报告。

### 双连接CPU快照与连接局部起点 · 2026-10-17（故障证据E4，修复待验收）

同一整机CPU终点在两个独立连接中可带不同开始tick：首正式轮原始两行start差61ticks（约2.542微秒），但终点/六核/启用核数/总量/逐核完全相同。把start也列入相同快照冲突指纹会误清待发布缓存并制造missing。判断要分开“单条源窗是否合法”“是否已消费同终点”和“CPU值是否真实冲突”；保留先到记录自身窗口，不融合边界，不复制旧值续线。修复只对严格同CPU/end重复移除start相等要求，任何不一致数值或非法窗口仍拒绝。原正式轮已停止、原评估保留，离线重放不改判历史失败；新诊断与五轮未通过前本项仍未验收。[方案与故障记录](/devlog/p4-fixture-lab-device-cpu-raw-plan-2026-10-17)。

## 整机Raw CPU限定范围验收 · 2026-10-18（E4 candidate）

仅1×25%/2×35%/2×50%受控低—中负载，原持续4×75%高负载未完成、不纳入交付声明；五新生命/Session以固定15..135秒、240机会/120槽通过来源/连续性和候选异常包络门；原失败首轮、诊断与新R4分列，不借样本或提高门限。真实Swift模型/Codable/CSV/JSONL、在线wire、SQLite封口及派生报告逐点核同。Raw为每核百分比累加，六核上限600%，不是normalized或目标进程CPU，正常UI TotalCPU图仍读normalized别名。本项不能顺带宣称该图或Normalized已通过。

### 来源一次发表与缺值保护

明确marker `device-total-cpu-raw-source-once.v1`后，同cohort/角色内双序列/原始时窗/时基绑定；CPUCount整型1..64、EnabledCPUs整型1..CPUCount、完整逐核0..100、总量0..100×核数、内部和容差1e−6×核数，首角色初始化零仅warmup一次，普通合法0保留。pending上限6、TTL1.5秒，源不可重复发表、过期必须missing，不能把旧scalar当新源续线。相同CPU/end跨角色重复只保留首到原始窗口；不同CPU值/拓扑仍拒绝，不拼接边界。

Swift历史Raw fallback会读旧normalized别名totalCPU，因此新marker缺Raw时显式隔离该歧义别名与quality，`totalCPUNormalized`显式字段及公式不变；无marker历史回放保留。Raw与Normalized显示解耦仍需下一项单独验收，不将隔离后空值说成被归一值“修复”。

### 原生参考、耗时与边界

自有App独立调用host_processor_info保存整数CPU tick，busy=USER+SYSTEM+NICE；按设备时间两侧counter构建每核busy/(busy+idle)上下界并累加100倍。端点及内部API gap≤30ms、Raw宽≤18点；普通外扩max(3点,15%)、严重max(6点,30%)。任何缺侧/重置/释放失败/太宽都是不可评估而非正常；不按产品值择近参考或插值。它是独立API调用的明显异常门，不是物理仪器、本机私有语义等价或所有场景零误差保证。

完整参考耗时必须包含原生读取、编码与追加写入，而非仅API调用；用下一事件携带上一点已完成耗时，避免自引用。旧通用编码P95 1.040792ms实际超门，固定整数schema优化并与真实Codable逐对象等价核同后旧.10 P95 .313250ms准入。随后发现now+10ms的逐点重新起算造成迟到累积、声明100Hz实际86.5–87.3Hz，参考包络过宽导致R3停止。新.11绝对deadline相位不漂移、跳过已过机会且不追赶/不造counter；实际诊断99.946Hz。新OFF/ON CPU增量.386793个百分点、footprint163323B，完整mean/P95/max=.201165/.297083/10.999792ms合取通过，正式轮亦逐轮核门；旧失败保留，资格的11ms级长尾不隐去；正式五轮最大完整耗时另在本批记录逐项披露（最大61.377083ms），不承诺每点≤1ms。所有原始counter与新失败不可删除，质量candidate、deviceReadPointProven=false保持。完整正式数字及资源/限制见[本批记录](/devlog/p4-fixture-lab-device-cpu-raw-plan-2026-10-17)和[不可变快照](/archive/validation/fixture-lab-device-cpu-raw-five-rounds-20261017.html)。

| 版本 | 日期 | 变更与证据 |
| --- | --- | --- |
| source-once.v1 · Raw限定验收 | 2026-10-18 | 新五轮限定E4；双角色同CPU/end起点差误拒绝修复；主线源码2288、归档426适用方法；Normalized/PerCore/实际图形与物理精度另列。 |

## 同源归一化与兼容别名的排查方法 · 2026-10-18（E1/E2，非验收）

现象：Raw断源已为missing、图形别名也为missing，仍可能在显式Normalized或派生链看到旧值；不能只看曲线断线便断言所有消费者都已隔离。当前主线与实际安装归档的独立单源夹具均观察到一次60/6=10后10秒显式Normalized继续10；另有负原量、小数分母、合法后缺分母仍复用缓存的对照。这里是小型软件夹具，不是真机五轮或物理误差结论。

方法：同时逐点比较原始同窗口CPU_TotalLoad/EnabledCPUs、Raw、显式Normalized、旧totalCPU别名、quality与消费者导出；禁止把缓存核数当同窗分母。归一化公式要求数据与分母来自同一已验证来源窗口；源时序/代际/缺失门与除法算术分开验证，合法0与初始化0分开。历史无新marker回放需保留旧语义，不能用新规则追认旧数据。新策略与实际验证进度见[单项方案](/devlog/p4-fixture-lab-device-cpu-normalized-plan-2026-10-18)；当前Normalized仍未验收，Raw既有限定结论不变。

## 同源Normalized与TotalCPU图形输入 · 2026-10-18（限定E4 candidate）

metricID `ios.device.cpu.total.normalized`、device scope、percent。唯一新公式是同一个已接受的新Raw原始记录的CPU_TotalLoad/EnabledCPUs，无取整/截断；CPUCount严格整型1..64、Enabled严格整型1..CPUCount、完整每核0..100与总和验证同Raw门。marker `sysmontapDeviceTotalCPUNormalizedPublicationPolicy=device-total-cpu-normalized-source-once.v1`由自研Sysmontap adapter明确增加，采集仍为既有pymobiledevice3 DTX Sysmontap双角色连接，不新开服务/不注入目标。

### 数值正确不代表解释字段正确

表现：合法一次源后无新源仍可显示旧Normalized，或两条pending记录分母6/3时首窗数值10正确、wire核数却写成3。原因是旧显式Normalized和Enabled元数据独立缓存，不能以Raw缺值保护或图形某个别名空就宣称所有消费者安全。判断方法：对原始记录、原生窗口与持久序列逐项绑定，分别核显式Normalized、totalCPU别名、cpuCoreCount/enabledCPUCount/公式标签、quality/scope/unit及实际Swift/CSV/JSONL，不只看一条曲线。

新策略全部数值与元数据只从同次Raw发布audit投影O(1)，不重新consume/开服务；无新源/未知或缺marker/非法分母/结果>100均missing且解释字段空，合法0保留、初始化0只warmup。Raw>100仍可合法；Normalized超100独立missing不反向改Raw。无新marker历史回放原样保留，不追认历史可信度。正常TotalCPU图读actual Swift `totalCPUPercent`，该兼容别名必须与显式Normalized同值同缺，不能把它当Raw多核总量。全GUI未从main重建与像素级渲染精度不在该输入链路证明范围内。

### 原生参考和验收范围

五个新生命/Session、不借Raw轮，140秒低中负载、15..135秒240机会/120槽；新源≥238、完整≥119、普通≥228、gap≤1.5秒，来源拒绝/违规与严重含尾部0。独立整数counter Raw包络先须宽≤18点、端点/内部gap≤30ms，再除同源Enabled；普通外扩max(3个百分点,15%)、严重max(6个百分点,30%)。未知窗口/缺侧/参考太宽是不可评估，不填正常或按值选参考。它是明显偏离与来源/连续性门，不是物理仪器、本机私有API等价或任意环境100%保证；持续高负载仍未验。

源码132/2315、453适用归档与独立13+4控制通过；真实36Core Swift对1460正式sample逐个验证输入别名/显式值/Raw/同窗元数据和Codable/CSV/JSONL。未重验的旧7项不与本轮新16/66相加。完整原始结果与限制见[本批记录](/devlog/p4-fixture-lab-device-cpu-normalized-plan-2026-10-18)及[不可变快照](/archive/validation/fixture-lab-device-cpu-normalized-five-rounds-20261018.html)。

| 版本 | 日期 | 变更与证据 |
| --- | --- | --- |
| normalized-source-once.v1 | 2026-10-18 | 五新轮限定E4：同窗分母/一次发表、显示输入及元数据同缺；历史无marker不变；物理精度/高持续负载/逐核及进程CPU另列。 |