PDF 渲染池诊断设计¶
上下文¶
在 Windows 上,受管本地解析在等待 PDF 图像渲染时可能会超时,尽管直接 pypdfium2 渲染和单独调用同一渲染辅助函数都能快速完成。当前的超时仅报告页码范围和时间,因此无法区分任务提交问题、worker 启动失败、worker 侧停滞,或 worker 结果从未到达父进程的情况。
决策¶
在现有进程池边界添加诊断,而不改变渲染行为:
- 在父进程中以 debug 级别记录任务提交,包括父进程 PID、线程、executor 标识和页码范围。
- 通过 Loguru 记录 worker 进入、完成和异常,包括 worker PID、页码范围、耗时和输出数量。
- 发生超时时,记录一条警告,包含每个 future 的状态以及每个已知 worker 的 PID、存活状态和退出码。
- 在 debug 级别记录成功完成及总耗时。
- 不要记录文件名、路径、PDF 内容或图像内容。
现有的超时、进程数量、任务调度、executor 回收和抛出的异常保持不变。
故障隔离¶
组合日志可识别失败阶段:
- 没有 worker 进入日志表示提交的任务未开始执行。
- 有 worker 进入但无完成或异常日志,表示 worker 侧渲染停滞。
- 有 worker 完成但无完成的 future,表示结果序列化或 IPC 投递出现问题。
- 带有退出码的已死 worker 表示进程在正常任务完成前被终止。
诊断收集必须是尽力而为的。检查 executor 内部实现绝不能替代或掩盖原始渲染超时。
测试¶
单元测试覆盖确定性的 future 和 worker 状态快照、worker 生命周期日志记录,以及使用假 executor 的超时日志记录。现有的 PDF 渲染测试继续覆盖行为;新测试不得启动真实子进程或等待生产超时。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 mi/MinerU