3. 现场调试的观测体系

现场调试最怕的不是问题复杂，而是“看不见”。当MERLIC应用在客户产线上出现偶发漏检、节拍抖动或相机掉线时，如果只盯着界面上的最终结果，往往无法判断问题出在图像采集、算子执行、通信交互还是系统资源。观测体系的价值，就是把这些不可见的内部过程变成可读、可比较、可追溯的数据。本节围绕四类观测手段展开：日志、性能计数器、MERLIC内置诊断工具，以及外部监控手段，并说明它们如何协同定位问题。

一、四类观测手段的分工

这四类手段不是互相替代，而是覆盖不同粒度与不同时间尺度。日志回答“发生了什么”，性能计数器回答“消耗了多少”，MERLIC内置诊断工具回答“MERLIC自己怎么看”，外部监控回答“系统环境是否稳定”。

• 日志（Log）：记录事件、错误、警告与状态切换，适合事后追溯。MERLIC的日志通常包含时间戳、模块名、严重级别和消息体，是定位“第一次异常出现在哪一步”的首选。
• 性能计数器：以数值形式持续反映CPU占用、内存增长、句柄数、线程数、GPU显存、网络吞吐等，适合观察趋势和发现缓慢劣化。
• MERLIC内置诊断工具：包括Recipe执行时间统计、工具级耗时、图像采集状态、通信连接状态等，直接对应MERLIC内部对象，粒度最贴近视觉流程。
• 外部监控手段：Windows性能监视器、任务管理器、Process Explorer、Wireshark、相机厂商SDK诊断、PLC侧通信计数等，用于验证MERLIC之外的系统因素。

协同使用的核心原则是：先建立基线，再触发问题，然后交叉比对。没有基线的观测数据，只能看到“高”或“低”，无法判断是否异常。

二、日志：从时间线还原现场

MERLIC日志按严重级别通常分为Info、Warning、Error、Fatal。现场调试时，建议先把日志级别调到Info或Debug，复现问题后再调回，避免长期写入影响磁盘I/O。查看日志时不要只搜“Error”，因为很多故障的前兆是Warning，例如相机连接重试、通信超时、图像获取延迟。

一个实用的做法是：在日志中先定位第一次出现异常的时间点，然后向前后各扩展30秒，观察同一时间段内是否有相机重连、Recipe切换、PLC信号变化或内存告警。日志的时间戳必须与外部监控工具的时间戳对齐，否则无法交叉验证。若MERLIC与PLC存在时间偏差，应先做NTP同步，或在记录时手动标注偏差量。

示例日志片段（教学示例，非实测）：
2025-03-11 14:22:31.204 INFO  ImageSource  Camera 0 acquisition started
2025-03-11 14:22:31.487 WARN  ImageSource  Camera 0 frame timeout, retry 1/3
2025-03-11 14:22:31.902 WARN  ImageSource  Camera 0 frame timeout, retry 2/3
2025-03-11 14:22:32.315 ERROR ImageSource  Camera 0 acquisition failed
2025-03-11 14:22:32.316 INFO  RecipeEngine  Recipe paused due to image source error

这段日志说明：问题起点是相机取流超时，而不是Recipe本身。若只看最终“Recipe paused”，容易误判为流程逻辑问题。

三、性能计数器：看趋势而不是看瞬时值

性能计数器适合用“基线—异常—恢复”三段式观察。以Windows性能监视器为例，可添加以下计数器：

• Processor(_Total)\% Processor Time：观察CPU总占用，MERLIC多线程执行时可能接近满载。
• Process(MERLIC)\Private Bytes：观察MERLIC进程私有内存，持续上升可能意味着图像缓存或结果对象未释放。
• Process(MERLIC)\Handle Count：句柄数持续增长通常与相机、文件或通信资源未释放有关。
• Process(MERLIC)\Thread Count：线程数异常波动可能对应算子并发或通信重连。
• Network Interface\Bytes Received/sec：GigE相机场景下，带宽接近上限会导致丢包和取流超时。

判断依据不是“某个值高”，而是“相对基线是否持续偏移”。例如基线CPU为45%，异常时升到85%并持续，同时Recipe耗时从80ms升到140ms，这就形成了可解释的因果链。若CPU升高但Recipe耗时不变，则可能是外部进程干扰，而非MERLIC本身。

四、MERLIC内置诊断工具与外部监控的协同

MERLIC内置诊断工具提供工具级耗时、Recipe执行状态、图像源状态和通信状态。它最擅长回答“哪个工具变慢了”。外部监控则回答“为什么变慢”。两者结合，才能从现象走到根因。

图中左侧是MERLIC内部观测，右侧是外部监控，中间是交叉比对。实际使用时，建议先固定一个“异常窗口”，例如从日志中定位到14:22:31的相机超时，然后拉取同一时间段的CPU、网络和相机SDK状态。如果网络吞吐在超时前达到950Mbps，而相机配置为1000Mbps全双工，则根因指向带宽饱和；如果网络正常但句柄数持续上升，则根因指向资源泄漏。

五、协同使用的操作要点

1. 先建基线：在产线正常运行时，记录Recipe平均耗时、CPU峰值、内存稳定值、网络吞吐和相机帧率。基线不需要非常精确，但必须来自同一台设备、同一套Recipe、同一光照条件。
2. 统一时间：MERLIC主机、PLC、相机和监控工具尽量使用同一时间源。若无法同步，记录偏差并在分析时补偿。
3. 分层排查：先看日志确定“哪一步异常”，再看内置诊断确定“哪个工具变慢”，最后用外部监控确认“是MERLIC内部还是系统外部”。
4. 控制变量：复现问题时，一次只改变一个条件，例如只调整曝光时间或只增加一个通信连接，避免多个变量同时变化导致无法归因。
5. 保留证据：日志、计数器截图、诊断导出和网络抓包应打包保存，便于后续复盘或向厂商支持提交。

观测体系的最终目的不是收集尽可能多的数据，而是用最少的数据回答最关键的问题：异常发生在哪一层、从什么时候开始、与哪个资源或事件相关、是否可复现。当日志、性能计数器、MERLIC内置诊断和外部监控形成闭环后，现场调试就从“凭经验猜”转变为“按证据判断”，这也是MERLIC应用性能优化能够持续进行的基础。