企业官网建设流程全解析

PanWatch 日志板与 DEBUG 模式完全指南：排查 Agent 调度与采集问题的正确姿势

【免费下载链接】PanWatchPanWatch — AI stock monitoring for A-shares, HK & US markets, powered by TradingAgents. Portfolio insights, real-time alerts & automated reports.｜盯盘侠：覆盖 A股/港股/美股的 AI 盯盘、持仓分析、实时提醒与自动报告。项目地址: https://gitcode.com/GitHub_Trending/pa/PanWatch

PanWatch（盯盘侠）是一款覆盖 A股/港股/美股 的 AI 盯盘工具，提供持仓分析、实时提醒与自动报告。当 Agent 没有按时运行、行情数据拉取失败、价格提醒没发出时，内置的日志板与DEBUG 模式就是你排查问题的第一站。本文带你用 4 步定位一次 Agent 调度的完整链路，并快速确认数据采集到底卡在哪。

一、准备工作：启动你的 PanWatch 实例

在项目根目录执行：

git clone https://gitcode.com/GitHub_Trending/pa/PanWatch cd PanWatch python server.py

启动后打开 Web 界面即可。日志体系由三部分组成：

二、日志体系是怎么工作的：DEBUG 全量落库 + 分级降噪

PanWatch 的日志策略是"全量入库、按需降噪"：

• 根日志级别恒为 DEBUG：所有 DEBUG 记录都会被数据库 handler 收录，UI 日志板永远能查到最完整的细节，包括 httpx 请求、调度心跳。
• 控制台按LOG_LEVEL过滤：默认INFO，并自动丢弃httpx、httpcore、uvicorn.access等三方库的低级别噪音（WARNING 及以上仍会显示）。
• 自动保留策略：日志总量上限 12 万条，基础设施噪音（httpx 等）单独限 3 万条，业务日志优先保留；缓冲 80 条、每 1 秒或遇到 ERROR 时立即刷盘。详见 log_handler.py。

💡 关键结论：你不需要改任何配置就能看到 DEBUG 日志——数据库里本来就有。LOG_LEVEL=DEBUG只影响控制台输出多少。

三、如何用 DEBUG 模式打开完整细节

1. 查看 UI 日志板：在 Web 界面的日志中心中，按级别、关键词、Logger、时间范围过滤；支持 SSE 实时推送（2 秒一推），断线可凭Last-Event-ID自动续读。
2. 控制台打开 DEBUG：设置环境变量LOG_LEVEL=DEBUG后重启，终端即可看到 DEBUG 级输出，适合本地开发时盯进程。
3. 按字段精确过滤：日志列表端点支持level、q（关键词）、logger、trace_id、run_id、agent_name、event、notify_status、domain、since/until等参数，接口定义见 src/modules/administration/api/logs.py。

四、4 步定位一次 Agent 调度：trace_id 是金钥匙

PanWatch 的 Agent 调度器（日报、盘中监测、盘前展望、TradingAgents 等）每次执行都会生成唯一trace_id（格式sch-<agent名>-<毫秒时间戳>），并通过 contextvars 把它绑定到该次运行内的所有日志上。调度入口见 src/modules/automation/agent_scheduler.py。

排查步骤：

1. 拿到 trace_id：在 Agents 页面的 Runs 记录（或手动"立即运行"）中找到那次执行的 trace_id；
2. 按 trace_id 过滤：在日志板输入该 trace_id，即可看到这次调度从"开始执行"到数据拉取、AI 调用、通知发送的完整时间线；
3. 只看错误：叠加level=ERROR，直接锁定异常栈；
4. 看运行结论：每次调度结束后会写入 AgentRun 记录（状态、耗时、错误摘要、通知是否发出），与日志互相印证。

五、排查数据采集与提醒问题：分清业务域与通知状态

日志板把日志分为两个域：

• business（业务域）：PanWatch 自身逻辑——调度、采集、分析、提醒；
• infra（基础设施域）：httpx / sqlalchemy 等底层请求。查"数据源是不是挂了"时切到domain=infra，能看到每一次对外请求的结果。

针对提醒没发出去这类问题，还有notify_status字段（attempted/skipped/sent/failed）和notify_reason，一眼判断是"被静默时段跳过"还是"发送失败"。

六、一键健康自检：日志写入器是否在掉数据？

如果怀疑日志本身没写进库，访问两个自检端点（源码见 logs.py）：

• GET /api/logs/health：日志库总量、业务/基础设施条数、最旧最新时间，以及写入器状态（待刷盘条数、丢弃条数、刷盘错误）；
• GET /api/logs/meta：级别分布、Top Logger、Top 事件，快速发现"谁在刷屏"。

写入器dropped_entries持续增长，说明刷盘速度跟不上日志产生速度，此时应减少 DEBUG 噪音或检查磁盘性能。

常见问题速查

• Agent 明明启用了却没跑？→ 看日志中"非交易时段"跳过提示（单只模式会跳过非交易时间的市场）；检查调度表达式与时区设置。
• 美股/港股行情拉不到？→ 切 infra 域过滤httpx，多数情况是网络或代理问题（http_proxy设置）。
• 日志面板没有 DEBUG？→ 数据库恒为 DEBUG 全量，若看不到请确认过滤条件里level没被限制成 ERROR。
• 控制台太吵/太静？→ 调LOG_LEVEL（DEBUG/INFO/WARNING/ERROR），只影响终端，不影响 UI 日志板。

掌握"trace_id 串链路、domain 分噪音、notify_status 看结果"这三件套，PanWatch 的 Agent 调度与数据采集问题基本都能 5 分钟内定位。

【免费下载链接】PanWatchPanWatch — AI stock monitoring for A-shares, HK & US markets, powered by TradingAgents. Portfolio insights, real-time alerts & automated reports.｜盯盘侠：覆盖 A股/港股/美股的 AI 盯盘、持仓分析、实时提醒与自动报告。项目地址: https://gitcode.com/GitHub_Trending/pa/PanWatch