日志
SRA 使用 loguru 统一记录日志,所有诊断信息都经过同一套 sink 输出到终端、
文件,并可同步到服务端的日志流。任务与扩展的排查都依赖这些日志,因此代码中不应使用 print。
本文介绍日志的初始化、输出位置、级别配置、日志流接口与常见调试组合。
日志由 SRACore/util/logger.py 的 setup_logger() 统一配置:
def setup_logger( path: str = "log/SRA{time:YYYYMMDD}.log", level: str = "TRACE", queue: Any = None,) -> None:它的行为:
logger.remove()移除所有已注册的 sink;- 注册 stderr sink(交互式终端可见,检测到 TTY 时着色);
- 注册文件 sink,按天生成
log/SRA20261120.log这类文件,UTF-8 编码,保留最近 7 个文件; - 若传入
queue,则额外注册一个 sink,把每条日志通过queue.put写入该队列; - 创建
log/ocr与log/screenshot目录。
所有 sink 默认 enqueue=True,因此多线程写日志是安全的。
| 位置 | 内容 | 说明 |
|---|---|---|
| 终端(stderr) | 与文件相同的日志行 | 交互式 CLI 直接可见 |
log/SRA<日期>.log |
全部日志 | 按天命名,保留最近 7 个文件 |
log/screenshot/ |
任务失败截图 | 由 on_failed 保存为 <任务名>_lastfailed.png |
log/ocr/ |
OCR 标注图、矩形检测调试图 | 需开启开发者模式或传 trace=True |
| 服务端日志流 | 最近 500 条 + 实时推送 | 见日志流 |
日志目录来自 SRACore/util/const.py:
LogsDir = Path("log").absolute() # 相对于当前工作目录LogsOCRDir = LogsDir / "ocr"LogsScreenshotDir = LogsDir / "screenshot"因此从仓库根目录运行时会写到仓库内的 log/(已在 .gitignore 中),
从其他目录运行时则写到该目录下的 log/。
输出格式固定为:
15:33:07 | INFO | 执行任务:领取邮件即「时间 | 级别(宽 5) | 消息」,文件 sink 不着色,<green> 等标记会被 loguru 自动去除。
loguru 的级别从低到高为:TRACE、DEBUG、INFO、SUCCESS、WARNING、ERROR、CRITICAL。
级别越高,输出越少。
配置方式:
| 场景 | 方式 | 默认值 |
|---|---|---|
| CLI | python main.py --log-level DEBUG |
TRACE |
| 服务端 | 环境变量 SRA_LOG_LEVEL 或 server.toml 的 log_level |
DEBUG |
| 代码 | AppContext(log_level="INFO", log_format=...) |
INFO |
在代码中使用
Section titled “在代码中使用”从统一入口导入,不要使用标准库 logging 或 print:
from SRACore.util.logger import logger
logger.info("执行任务:领取邮件")logger.debug(f"OCR 结果: {boxes}")logger.trace(f"ImageNotFound: {template}")级别使用约定:
| 级别 | 用途 |
|---|---|
TRACE |
识图/OCR 的逐次结果、未命中原因等高频细节 |
DEBUG |
流程分支、参数、重试次数 |
INFO |
面向用户的进度与结果,如「任务完成:xxx」 |
WARNING |
不影响继续执行的异常,如配置值可疑、拉取失败回退 |
ERROR |
任务失败、页面状态异常等 |
记录可预期的失败时,仓库习惯把 SRAError 作为消息输出,便于同时带上错误码与上下文:
from SRACore.util.errors import ErrorCode, SRAError
logger.error(SRAError(ErrorCode.WAIT_TIMEOUT, "等待主界面超时"))服务端运行时,AppContext(with_log_stream=True) 会把日志额外写入 LogStreamService:
- 环形缓冲保存最近 500 条日志;
- 支持多订阅者,sink 可在任意线程调用(内部通过事件循环调度);
- 对应 HTTP 接口:
GET /api/backend/logs?count=100 # 获取最近 N 条GET /api/backend/logs/stream # SSE 实时日志流WebUI 的日志页即通过这两个接口展示,不依赖子进程的 stdout/stderr。
常见调试组合
Section titled “常见调试组合”| 目的 | 组合 |
|---|---|
| 查看识别过程 | --log-level TRACE |
| 检查 OCR 识别框 | 开发者模式 + developerMode.saveOcrImage,查看 log/ocr/<时间戳>.png |
| 检查矩形检测 | rectangle_detect(..., trace=True),查看 log/ocr/rectangle_detect_<时间戳>.png |
| 查看任务失败现场 | 失败后查看 log/screenshot/<任务名>_lastfailed.png 与对应日志 |
任务失败时 BaseTask.on_failed 还会自动检查可能的失败原因(分辨率不是 1920×1080、模板匹配置信度异常),
并以 WARNING 输出,排查时优先看这几行。
- 工作目录决定日志位置:
LogsDir是相对路径,务必从仓库根目录运行,否则tasks/与resources/也会找不到; - 高频日志有成本:
ocr()的trace=True会打印完整识别结果,循环中应关掉或使用更高阈值; - 不要依赖早期 sink:
setup_logger会重置 sink,扩展中需要独立文件时自行logger.add并在结束时logger.remove(id); - 敏感信息:日志会包含账号、路径等信息,提交 issue 前请先脱敏。
