Skip to content

日志来源、历史读取与筛选 ​

UI/ColorVision.UI/LogImp/ 负责托管日志显示、历史解析和搜索;业务模块产生的日志、文件输出与当前可见文本是不同层。界面为空、被清空或没有某条记录,都不能单独证明设备命令、文件写入或流程动作没有发生;完成判据仍应核对对应模块的执行契约。

查找一次运行的日志 ​

  1. 打开“帮助 > 日志”,或使用默认快捷键 Ctrl+Alt+L。独立窗口默认读取当前日志文件中的启动后记录,再接收新的托管事件;主窗口嵌入的日志面板只接收新事件。
  2. 若要查看当前文件中今天较早的记录,在日志窗口右键选择“通用设置”,将 LogLoadState 设为 AllToday,然后关闭并重新打开日志窗口。历史只在初始化时加载,修改此选项不会立即重读;跨天或滚动归档需另查对应源文件。
  3. 右键选择“搜索”或按 Ctrl+F,输入错误关键词。多词用空格分隔,例如 camera timeout。具体规则见下文搜索与失败语义。
  4. 要停留查看一条记录,关闭“自动滚动”;继续保留“自动刷新”才能接收之后的新 UI 事件。搜索框变红时先修正或清空条件;记录缺失时再核对历史范围、容量限制和源文件。

日志从哪里来 ​

独立日志窗口进入后聚焦日志查看区域,Esc 先收起已打开的搜索栏,再关闭窗口。按 Alt+V 后按 N 可打开原生日志窗口。窗口进入后聚焦等级选择,下拉列表先处理 Esc,随后 Esc 可关闭窗口并释放采集会话。两个窗口的 Tab / Shift+Tab 均在窗口内循环。独立日志窗口的菜单访问键见帮助菜单。

入口数据来源与边界
帮助 > 日志(WindowLog,快捷键可配置)给 log4net 根 logger 附加 LogViewerAppender 接收新事件,并在初始化时读取当前文件历史;每次菜单执行创建新窗口
视图 > 日志(主窗口 LogOutput)按需打开,接收 log4net 新事件,本身不加载文件历史;ModuleLogViewerBinder 的模块面板只接受指定 logger 名或其点分隔子名称
视图 > 原生日志(NativeLogWindow)独立的 NativeLogBridge 回调与采集会话
WindowLogLocal / LogLocalOutput读取调用方指定的外部文件,不接收 log4net 事件;编码可由调用方指定,默认 Encoding.Default

主窗口“视图 > 日志”面板右上角的齿轮可打开本面板的“通用设置”。

主程序通过 EntryClass.cs 的 XmlConfigurator 加载并监视 ColorVision/log4net.config。当前配置包含控制台和按日期滚动的 UTF-8 文件输出,文件配置前缀为 log\;当入口检查到当前工作目录包含 C:\Program Files 时,会改到应用数据目录下的 ColorVision\Log\。定位应读取当前 appender 的 File,不能只猜安装目录或将主面板当作完整日志文件。

反馈打包的应用日志范围 ​

AppLogCollector 同时收集 %APPDATA%\ColorVision\Log、当前程序安装目录下的 log,以及当前文件 appender 所在目录。安装目录从 AppDomain.CurrentDomain.BaseDirectory 获取,覆盖安装在 C:\Program Files 下的程序,不扫描其他软件目录。更新后重启和正常启动可能选择不同日志目录,反馈不能只收当前正在写入的位置。

目录转为绝对路径、忽略大小写和末尾分隔符后去重。ZIP 中分别使用 AppLogs/AppData/、AppLogs/Installation/ 和 AppLogs/Current/,保留不同目录内同名的日志;当前目录与前两者重合时只收一次。所有来源沿用所选时间范围(默认最近 7 天)、按 LastWriteTimeUtc 过滤、单文件不超过 50 MiB 和只读顶层文件的规则。缺失目录会跳过,某个目录无法读取或某个文件复制失败不会阻止收集其他来源。“打开日志目录”仍指向当前 appender 所在目录,打包范围更广。

全局输出等级不是本地筛选 ​

WindowLog、LogOutput 右键菜单中的“日志等级”调用 LogConfig.LogLevel,进而由 SetLog() 修改 Hierarchy.Root.Level。这会影响继承根等级的后续 log4net 事件及其文件/控制台/UI 输出,不会重新筛选已显示的历史,更不能补回此前没有产生的低等级事件。配置文件初始为 All,但主程序初始化配置后会调用 LogConfig.Instance.SetLog();该配置默认 Info,实际值还取决于已保存配置。

若只想缩小当前可见范围,应使用搜索;不要为了看得清而把提高全局等级当作无副作用的显示操作。改变等级、开启真实采集或重现业务动作,应属于当前任务明确授权的排障范围。

配置也不是所有窗口各自隔离:WindowLog 使用 LogConfig.Instance,主面板显式使用独立的 LogPanelConfig.Instance,默认构造的 LogOutput 使用新的 RealtimeLogViewConfig。外部文件视图共享 WindowLogLocalConfig,且其模式、字符上限和颜色仍绑定 LogConfig.Instance。持久化规则见配置注册、保存与恢复。

历史读取、时间与大小限制 ​

托管日志窗口 ​

WindowLog.LoadLogHistory() 只取根 logger 上第一个 RollingFileAppender.File,以 FileShare.ReadWrite 打开当前文件,不遍历滚动归档。LogLoadState 默认 SinceStartup:

  • SinceStartup:保留时间戳不早于当前进程启动时间的记录。
  • AllToday:保留时间戳日期等于本机当天日期的记录;不是读取所有历史文件。
  • None:跳过此次历史读取,不禁止实时事件;该窗口实时刷新初始为开启。

LogHistoryReader 逐行扫描,以行首精确格式 yyyy-MM-dd HH:mm:ss,fff 划分记录;后续无时间戳行并入前一条,文件开头没有可识别时间戳的行不会进入这条历史读取链。倒序按整条记录反转,不反转异常堆栈内部行。初始化读取是同步的;字符上限不是文件字节上限,也不是只扫描文件尾部的保证。文件不存在时不会加载历史;读取异常弹窗提示,不会证明实时 appender 也失效。

MaxChars 默认 -1,当前实现只有值大于 1000 才裁剪。历史读取先淘汰较旧整条记录,ReadEntries 至少保留一条,因此单条超长记录仍可越限;TextBox 路径最后还会硬截字符,可能截断一条记录。MaxEntries 是控件条目集合上限:完整窗口默认 10000、实时配置默认 1000,非正数不限;TextBox 历史由 SetText 写入,不能用条目上限承诺初次历史读取已受限。虚拟化模式也不是完整日志归档或严格内存上限。

外部日志文件 ​

LogLocalOutput 初次读取默认保留末尾 1000 行,再按记录解析;MaxLines <= 0 才读全量。适用编码使用向后查找换行的尾读,UTF-16/UTF-32 等情形退回从头读取。限制的是物理行,边界可能切掉一条多行记录的开头,不保证整条异常都在视图中。

自动刷新通过定时器(默认 500 ms)和文件监视跟踪变化。文件变短或可读取的文件标识改变时重新加载,同一文件追加内容则从已读取的字节位置继续。尾部读取和增量读取沿用文件 BOM 检出的编码。原文件原地截断后若在两次读取之间恢复长度,仍可能需要手动刷新。初次文件缺失或读取失败会显示消息,后续读取异常可能表现为暂无新日志。

刷新、滚动、清空与生命周期 ​

  • 托管 LogViewerAppender 默认约每 100 ms 将缓冲调度到 UI;刷新间隔可配置。关闭其自动刷新会直接跳过这段时间的新 UI 事件,并非无损暂停队列;重新开启只接收之后的事件,不自动补读文件。文件输出是否继续取决于日志源与文件 appender,不由 UI 刷新开关决定。
  • 外部文件的自动刷新暂停的是读取,读取位置保留;恢复后可以读尚在同一文件中的追加内容,仍受轮转与显示裁剪限制。不要把这与托管事件跳过或 native 暂停混为一谈。
  • AutoScrollToEnd 只决定追加后的视口跟随,不控制日志产生、接收或落盘;鼠标选择/滚轮会临时暂停跟随,约两秒后解除暂停。关闭自动滚动也不防止旧内容被容量裁剪。
  • “清空”只清除控件文本、条目和选择,不删除源文件、不停止业务或全局日志,也不等于清空 appender 尚待刷新的缓冲。复制只取得当前显示中选中的内容,不是完整日志导出;本页这些查看控件没有自动保存当前视图的契约。
  • LogOutput 在加载/卸载时挂接/移除 appender,Dispose 另解除事件与搜索控制器;WindowLog 关闭时移除并释放 appender。模块 binder 也必须释放,否则仍订阅根 logger。LogLocalOutput 卸载时停止定时器/监视器,最终 Dispose 才解除配置订阅并释放监视器,独立窗口关闭会调用它。

LogViewerControl 默认 TextBox;Virtualized 使用条目视图与等级颜色。模式在控件第一次 Loaded 后锁定,修改配置需新建相应控件/窗口才能切换。视图中被裁掉的内容不能靠清空搜索恢复;要追溯应按权限读取仍保留的源文件。

搜索与失败语义 ​

托管/外部文件视图通过右键“搜索”或 Ctrl+F 打开搜索栏;Esc 或关闭按钮清空搜索并隐藏栏。输入有约 200 ms 防抖,清空立即应用。不要套用其他模块顶部搜索框的响应式隐藏规则。

LogTextViewController 同时在所属键盘目标上注册标准 ApplicationCommands.Find,执行仍是显示同一搜索栏;Detach 时解除命令绑定。这样主窗口可配置的场景查找能直接复用当前日志视图的局部搜索,而不先打开应用功能搜索,也不模拟 Ctrl+F。此适配不改变过滤算法、日志源或全局日志等级。

  • 普通搜索按空格拆词,每个词必须在同一被匹配文本中出现,忽略大小写。TextBox 按行过滤,Virtualized 按整条 LogEntry.Text 过滤,因此多行异常的匹配和保留范围会不同。
  • 含 . * + ? ^ $ ( ) [ ] { } | \ 中任一字符就自动转为正则;不存在独立的“纯文本/正则”开关,文件名中的点和 Windows 路径也会触发。要匹配文件名中的字面点可写 camera\.log;error|fatal 表示任一关键词。正则使用 IgnoreCase,每次匹配超时为 250 ms,不是全量搜索总时限。
  • UI 的 NormalizeSearchText 会先按当前文化转成小写,再传给 helper;不能承诺任意正则原样执行,例如 \D 会变为 \d。复杂模式需核对这条调用链,不能只看 helper 测试。
  • 正则解析失败或匹配超时时返回 false;直接应用搜索时边框变红,控件保留原可见结果,而不是显示“匹配为零”。无效搜索串仍是当前搜索条件,后续追加可能继续筛选失败;先修正或清空再判断日志是否缺失。

LogSearchHelper 仅缓存最近的有效正则及无效模式,不缓存完整文件或历史搜索结果。控件另保留原始条目/文本与可见结果,清空搜索只能恢复当前仍在内存中的内容。

Native 采集是另一条控制链 ​

NativeLogWindowService 复用已打开的 native 窗口,窗口会话初始不采集;“开始捕获”才调用 NativeLogCaptureController.Start 初始化/启用可用 native 日志源,可能加载 DLL。其等级影响进程级 NativeLogBridge,不等于 log4net 根等级或本地筛选。当前控制器传入 sink: null、enableNativeSink: false,不能据此承诺保存到托管日志文件;桥接层允许其他调用方提供 sink,但该窗口不安装文件输出。

native 的“暂停显示”仅暂停显示队列取出,采集仍继续;“继续显示”恢复取出。待显示缓冲上限 8192,溢出丢最旧记录并累加“已丢弃”(Dropped);每次刷新最多取 512 条。“停止捕获”或关闭窗口会请求禁用 bridge,而清空会清待显示缓冲、丢弃计数和当前视图。这些操作都不是停止算法/设备的命令。实际采集需先确认授权,排障文档不授权启动产品或触发硬件。

证据与验证缺口 ​

用实际宿主核对搜索反馈、标准查找焦点和窗口生命周期。原生日志还须核对生产 DLL、有效回调和日志源。反馈收集在目标账户权限及实际日志目录下验证。

当前主题未声明外部文件轮转/编码组合、实际文件写入保留、UI 生命周期压力或生产日志不丢失的端到端覆盖。最小人工复核应使用获准的合成日志与隔离环境;不为文档校验开启真实采集。对外分享前脱敏路径、客户标识、设备数据与凭据,不删除现场日志来“清理”排障证据。

基于 MIT License 发布。