使用 User Timing API 测量浏览器性能
用标记和测量记录自有应用流程，理解噪声结果，并以最少数据完成隐私友好的性能分析。
BotBrowser Team
User Timing API 允许应用为自己的工作命名起点和终点，并测量两点之间的间隔。它适合回答“本版本结账校验用了多久”这类明确问题，而不是设备基准、身份信号或收集用户全部计时值的许可。有效测量从可见结果开始，在应用能够解释的边界打点，并且只记录决策所需字段。
性能标记与测量
performance.mark(name) 在文档时间线上记录命名点。performance.measure(name, startMark, endMark) 根据两个标记创建区间。名称属于应用，应描述稳定的用户步骤，例如 cart-submit-start、results-visible 和 payment-validation-complete。只有当起止点代表同一个版本负责的契约时，测量才有意义。
performance.mark('cart-submit-start');
try {
await validateCart();
performance.mark('cart-submit-end');
performance.measure('cart-submit', 'cart-submit-start', 'cart-submit-end');
} finally {
performance.clearMarks('cart-submit-start');
performance.clearMarks('cart-submit-end');
}
W3C User Timing Level 3 定义标记和测量条目，MDN User Timing API 说明浏览器方法和可用性。请先检查方法是否存在，并在标记缺失或操作失败时保持主任务可用。一次时长不能证明硬件类别。
使用 try/finally 清理成功、失败和取消路径的标记。否则异常前创建的测量会留在时间线上，干扰下一次运行。并发工作应使用运行范围名称或本地拥有清理权的对象；不要用通用名称清除其他组件的标记。
测量自有流程
先定义用户流程和接受结果。搜索流程可以测量从提交到结果可见，再按需记录请求、解析和渲染区间。导航计时、资源计时与 User Timing 要分开：应用创建的标记不能证明网络或服务器耗时相同。
在团队负责的边界打标。组件可在内容可见时标记，API 客户端可标记请求发送和响应处理。第三方组件控制的结束点应标记为观察，不要声称拥有。保留取消和重试语义，并使用短 fixture id，不记录页面内容或账号标识。
可复制产物是上面的 fixture 和下表。它覆盖成功、错误、取消、API 不支持和延迟结果。预期行为是每种情况页面仍可用；只有两个标记存在时才产生一次有界测量；清理后不保留标记。
| 结果 | 记录 | 用户动作 |
|---|---|---|
| 两个标记存在 | 时长和运行标签 | 正常继续 |
| API 不可用 | measurement-unavailable | 不测量也继续 |
| 校验失败 | 状态及可用的有界时长 | 显示错误和重试 |
| 用户取消 | 取消状态，不伪造时长 | 保留输入并停止 |
| 过期完成 | 运行已过期则忽略 | 保持当前视图 |
BotBrowser 的受控上下文可以运行授权流程并比较声明浏览器设置下的可见结果。BotBrowser 不会让应用工作变得确定、不改变 User Timing 规范，也不证明时长代表用户设备。能力证据要和产品性能结论分开。
BotBrowser 受控上下文支持在声明的浏览器配置下重复运行已授权的自有流程并比较可见结果。它不会让应用工作变成确定过程、不会替应用定义标记，也不证明某个时长代表用户设备或业务结果。
数据最小化
只收集决策需要的字段：测量名称、时长分桶或聚合、版本标签、fixture id 和结果。避免 URL、查询字符串、文本、账号标识和长期用户计时历史。诊断窗口内可使用短运行 id 关联浏览器、服务器和网关记录，之后过期。不要把标记与其他浏览器属性组合成画像。
导出条目前，先明确接收系统、访问权限组、保留期限和删除路径。即使时长不含文本，按时间戳或其他记录关联的重复事件仍可能描述某个会话。若决策不需要逐次诊断，优先在传输前聚合。临时诊断仅在事件或测试窗口内开放访问并设置到期时间，之后删除关联键和详细追踪。performance.getEntriesByName() 与 getEntriesByType() 会暴露页面中的条目，宽泛导出可能包含其他组件；使用名称白名单，只复制所需字段。组件完成后清理自己拥有的条目。
精度降低和缺失数据是正常情况。往返缓存恢复、预渲染、服务工作线程响应或页面可见性变化都可能改变生命周期。把它们作为不同上下文标签处理，不能用“典型时长”填补缺失值。
解释噪声结果
缓存、网络、服务器负载、CPU 调度、页面状态、浏览器版本和并发工作都会改变分布。比较相同 fixture、路由、版本和观察窗口，使用百分位和样本数，而不是单一平均值。中位数不变而 p95 变慢可能是尾部问题；所有百分位移动可能是版本或环境变化。
先验证结果可见、输入保留和清理完成，再看时长聚合。不要从一台机器制定通用阈值或发布检测阈值。超时、缺少标记和 Promise 拒绝都应是有回退的普通应用结果。
结果变化时，先重跑最小 fixture，再比较服务器时间、资源条目、队列延迟和浏览器版本。User Timing 能定位回归边界，却不能单独证明原因。记录负面证据，避免未来维护者因不完整样本删除回退。
并发运行需要各自的名称；通用名称可能把错误的起点和终点配在一起。
被拒绝的 Promise 可能跳过终点标记，因此要保留错误状态并清理起始标记。
取消时应先让运行失效，避免晚到的响应修改当前视图。
API 不存在时应记录 not-measured，它不等于零时长，流程仍应继续。
fixture 应声明合成输入、有限等待和可重置方式，不能给下一次测试留下条目。
每次运行前只删除属于该 fixture 前缀的标记，不要清空其他组件的时间线。
可重复测量不要求时长完全相同，而是要求状态转换和清理规则相同。
应说明区间是否包含重试、排队、动画或渲染等待，并在版本间保持定义稳定。
标记不应阻塞提交；清理失败也不应替换原有的应用错误。
先比较功能结果，再查看时长分布，以决定调查方向。
记录 fixture 修订、路由类别、浏览器版本、观察窗口和样本数量。
将结果摘要与详细诊断分开，并在授权窗口结束后删除临时标识。
若标签含义发生变化，应开始新的序列，不要把不同区间混在同一图表中。
从提交到结果可见的流程回答产品问题，但不能说明设备是否快速。
superseded 状态可以解释缺少测量，而不伪造时长。
缺失条目可能是取消、错误或页面切换的有效证据。
发布清单
冻结标记名称、边界所有者、fixture 输入、浏览器设置、样本窗口、聚合方式和保留期限。测试支持和不支持路径、错误、取消、重试、重复运行、本地化和恢复页面。确认清理不会删除其他组件条目，并在桌面与移动宽度检查可见结果。
安全顺序是：定义一个自有问题；标记边界；只有两点存在才测量；清理；聚合可比运行；保留最少证据。这样可以解释性能而不把应用计时变成隐蔽测量。
