数据记录与可观测性

1. 职责与边界

本模块记录运行过程，保存音频与时间线，提供会话文件读取和离线分析能力。会话继续转换所需的状态及清理流程见会话与状态管理，对外消息合同见会话数据 API，评测方法见评测指南。

主要源码：session.py、logging_config.py、ws.py 的 ConnectionMonitor 与处理日志、session_data_manager.py、timeline_analyzer.py。

2. 输入与输出

记录来源	保存或呈现形式	含义
Buffer 追加音频	SEND 时间线事件	客户端方向送入服务的 PCM 时长，Opus 解码后记录
流水线入口与出口	输入 / 输出音频记录	输入为已缓冲和重采样的推理块；输出为协议采样率下的浮点音频
路由发送完成	RECV 时间线事件	服务已向客户端方向发送转换结果，不等于客户端已播放
逐块处理、连接与进程	日志、阶段耗时、连接计数	运行诊断信息
已保存文件	会话数据包与离线分析结果	历史数据读取和测量依据

SEND / RECV 名称采用客户端视角，事件记录位置仍在服务端。不能按服务端收发方向倒置解释，也不能据此认定记录了客户端实际接收时间。

3. 音频保存与数据读取

3.1 保存内容

save_input / save_output 控制转换入口与出口是否将音频加入会话记录。保存目录为 save_dir/YYYY/MM/DD/，存在相应记录时写入：

文件	内容与采样率
{session_id}_input.wav	经过缓冲、预填充 / 补齐和输入重采样后送入推理的音频，使用 session.sr_in
{session_id}_output.wav	流水线输出的音频，使用 session.ws_sr_out
{session_id}_timeline.json	会话 ID 与 SEND / RECV 事件组成的 merged_timeline

输入文件不保存原始 WebSocket 字节。输出记录位于流水线结束处，早于路由发送成功确认，因此录音存在不证明客户端完整收到。输出数组会逐块复用，记录方法复制数组以保留各块内容。

保存日期取实际保存时服务进程的本地时钟，不采用文档 changelog 的北京时间约定。关闭输入和输出音频记录不会自动关闭时间线事件记录。

3.2 完成与保存时序

正常协议路径先处理尾块并发完成消息，随后在退出清理中创建后台保存任务。async_save_and_cleanup() 在线程中调用保存与清理方法。

因此 complete 不表示文件已经落盘，紧接完成响应查询 HTTP 会话接口可能尚无完整文件。异常断联后会尝试保存已记录部分，不保证未处理尾块被转换；进程强制退出也可能中断后台保存。

3.3 文件读取与离线工具

SessionDataManager 从配置的保存目录查找文件，可用日期缩小搜索范围；当前按会话 ID 前缀匹配文件，唯一且不易混淆的标识有助于区分结果。读取结果依次经过 ZIP、GZIP 和 Base64 编码，由 HTTP 工具路由返回，编码合同见会话数据 API。

TimelineAnalyzer 在离线阶段分析时间线。音高分析、音色相似度与质量评测等辅助工具位于 tools，不在实时请求主链路中。当前没有 /tools/performance-report 路由，工具调用与复现条件由评测指南维护。

4. 日志、时间线与连接统计

4.1 日志与阶段耗时

日志包括 Worker、会话、处理阶段耗时和 SLOW 标记。流水线使用 perf_counter() 记录阶段耗时，日志展示时转换为毫秒。

路由的 E2E 日志计取块、转换和发送的执行段，未包含此前输入累积、采集或之后客户端播放。模型耗时、首个输出等待、尾部收发差值和采集到播放时延应分别解释。

4.2 时间线

Session 记录事件时写入服务端时间戳、累计音频时长、事件类型和会话 ID。输入累计时长来自追加 PCM 的样本数；预填充不是客户端输入事件，尾部补齐也不代表客户端额外发送。

分析前需明确时间线来自服务端还是客户端，并核对采样率、预填充、补齐和计时位置。完整指标计算方式见评测指南。

4.3 连接统计与运行文件

ConnectionMonitor 使用进程内集合统计活跃会话 ID，并通过带文件锁的相对路径 temp/connections.json 汇总不同 PID 的记录。它按会话 ID 去重，重复 ID 可能使计数不能反映实际连接数。

CLI 的 PID 文件和其连接文件辅助函数按端口命名，WebSocket 监控却仍使用上述公共文件。同一工作目录下多个服务的连接统计可能混合；端口分离不表示所有运行文件已隔离。日志和音频输出也需按实例配置不同目录，部署方式见配置与部署。

5. 当前测量限制

• 路由记录输出音频时长时固定除以 16000；当 sample_rate_out 不为 16000 Hz 时，服务端时间线累计时长存在偏差。
• 路由的 VC_SLOW 比较使用秒计时值，配置阈值按毫秒命名和说明；该标记不能独立作为时延验收依据。
• 内部处理异常可能仅写日志或补静音；协议完成不证明音频质量或逐块成功，错误路径见接入与协议适配。
• 连接计数、服务端事件和录音分别反映不同阶段，不能代替客户端接收、播放或完整的压力测试结果。

以上是按当前源码记录的限制，本轮未修复实现。性能与音质结论需附有效配置、输入、参考、硬件及测量方法；历史报告和单次试听不作为当前生产保证。