Unity 云日志系统

给 B 站虚拟直播项目自建 Unity 云日志系统：端上结构化采集 + 采样上报 + 云端按用户检索，把线上问题排查周期从 5 天压到 1 天，开发不再依赖「用户复述问题」。

排查周期5 天 → 1 天

面捕采样每 60 帧 1 次

信息来源用户描述 → 结构化日志

背景

B 站虚拟直播项目在线上出问题时，排查流程极度低效：

1. 用户反馈「面捕不动了」→ 客服转运营 → 运营转产品 → 产品转开发。
2. 开发想远程登录用户机器？不可能。
3. 只能让用户复现 + 截图 + 文字描述 → 猜问题 → 尝试修复 → 发包 → 让用户再试。

一个来回就是5 天，而且每一步转述都在丢信息：到开发手里时，「面捕不动了」可能是 Mediapipe 丢帧、模型下载失败、驱动框架切换异常中的任何一种，三种修法完全不同。

问题

• 信息源头不可靠：用户描述的是体感（「不动」「卡」），不是事实（丢帧率、BS 值、耗时）。
• 沟通链路太长：客服-产品-开发-用户四层转述，时间和信息双重损耗。
• 客户端是黑盒：面捕引擎、驱动框架、下载框架都在用户机器上跑，没有任何可观测性。

方案

思路一句话：让用户机器上的关键状态自己说话。端上做结构化日志采集，HTTPS 上报云端，开发按用户 ID + 时间范围直接查。

flowchart LR
    A["面捕引擎<br>Mediapipe 帧率/丢帧/BS 值"] --> D["端上结构化采集"]
    B["驱动框架<br>模型类型/BS 更新耗时"] --> D
    C["性能与异常<br>FPS/CPU/内存/堆栈"] --> D
    D --> E["采样 + 批量<br>HTTPS 上报"]
    E --> F["云端存储"]
    F --> G["按用户 ID + 时间查询<br>关键字过滤 / 异常高亮"]

采什么、多久采一次

类别	记录内容	频率
面捕引擎	Mediapipe 输出帧率、丢帧数、BS 值范围	每 60 帧 1 次
驱动框架	当前模型类型、BlendShape 更新耗时	切换时
下载框架	MLive 下载状态、失败重试次数	事件驱动
性能	FPS、CPU、内存	每 5 分钟
异常	Exception 堆栈 + 上下文快照	触发时

这张表的核心是分级频率：状态类数据（面捕）低频采样看趋势，事件类数据（下载、切换）触发即记，异常全量带堆栈。全量直传会把服务器和客户端都压垮，关键事件 + 低频快照才是平衡解。

每个字段都对应一类线上症状的判定：BS 值范围不动说明表情识别卡死而非渲染问题；丢帧数持续上涨指向 Mediapipe 输入侧；BlendShape 更新耗时飙高是驱动框架的性能问题；MLive 重试次数多则是模型下载的网络问题。用户一句「面捕不动了」，在日志里是四种可分流的结论。

查询体验

• 按用户 ID + 时间范围定位到具体用户的具体时段。
• 关键字过滤（Mediapipe / MLive / Exception）。
• 异常日志红色高亮，先看异常再看前后文。

关键实现

• 结构化优先：每条日志带类别、时间戳、关键字段，不写自由文本——因为要按字段过滤，不是给人读小作文。
• 上下文快照：异常发生时把当前模型类型、面捕状态、最近性能快照一起打包，单条日志就能还原现场，不用跨表拼凑。
• 采样率可接受为前提：面捕每 60 帧记一次，丢帧趋势看得出来，开销可以忽略；真出异常时临时提频，不常态高频。

一个真实的触发场景

2023 年 4 月面捕替换版本上线后，多个用户面捕启动失败，而团队没有线上可观测手段：只能先回滚版本，再逐一向用户收集日志，与合作方来回对齐，靠冒烟测试确认修复——整个过程就是「背景」里那条 5 天链路的完整出演（详见面捕失败事故复盘）。复盘结论里「收集用户日志数据以备查看」这一条，直接催生了云日志系统：与其事故后挨个找用户要日志，不如让日志平时就在云端。

指标

指标	优化前	优化后
排查周期	5 天	1 天
沟通成本	客服-产品-开发-用户多次转达	开发直接看日志
问题复现	依赖用户描述和截图	日志还原现场
误判率	高（信息不全，靠猜）	低（结构化数据）

「5 天 → 1 天」里省掉的主要是等待和转述：以前是「发包给用户再试」的循环，现在是用户报问题时报个 ID，开发当天就能定位到是面捕丢帧还是下载失败。

复盘

1. 不要等用户描述问题。结构化日志比用户描述可靠 100 倍——这不是夸张，「面捕不动」四个字和「Mediapipe 输出帧率从 30 掉到 0、丢帧数持续上涨」之间隔着整个排查周期。
2. 采样的艺术：全量日志会压垮服务器和客户端，「关键事件全量 + 状态低频快照」是客户端日志的通用解。
3. 可观测性要建在问题之前。这套系统是在被线上问题反复折磨之后才建的；后来的项目里，日志和监控变成了上线 checklist 的第一项，而不是出事后补的债。这套思路也完整迁移到了后来小鹏车机的监控上报链路——车机同样摸不到用户现场，同样需要「让机器自己说话」。