生产级应用可观测性完整解读 Scanner 的 Serilog 日志与 AppCenter 崩溃上报体系【免费下载链接】scannerAn all-in-one scanner app for Windows项目地址: https://gitcode.com/gh_mirrors/scanner/scannerScanner 是一款面向 Windows 的全功能扫描仪应用All-in-one Scanner App而它真正让开发者眼前一亮的是底层的质量工程基于Serilog 日志与Microsoft App Center 崩溃上报构建的完整应用可观测性体系。本文带你快速看懂这套体系的设计思路即使你是新手也能收获一套可直接借鉴的生产级实践清单。为什么 Windows 扫描仪应用最需要可观测性扫描仪应用有一个特殊之处运行环境千差万别。同一份代码要面对不同厂商的扫描仪驱动、不同分辨率的平板床/进纸器、不同的 Windows 版本与系统架构。用户报告扫描失败时开发者最怕听到的是我这里复现不了。这正是 Scanner 把可观测性Observability当作一级公民的原因日志回答发生了什么把每次扫描的参数、设备状态、系统环境完整记录下来崩溃上报回答哪里出了问题应用崩溃时自动把上下文和日志发送到云端事件分析回答用户怎么用追踪用户的核心操作路径理解真实使用场景整体架构LogService 与 AppCenterService 两大支柱Scanner 采用清晰的接口 依赖注入架构两个核心服务在应用构造时注册为单例见 Scanner/App.xaml.cs服务接口职责LogServiceILogService管理 Serilog 日志器、日志文件列表与导出AppCenterServiceIAppCenterService崩溃上报、错误附件、用户行为分析事件两个服务互相协作又各自独立日志服务负责留痕App Center 服务负责传话而崩溃发生时日志文件会自动附在崩溃报告后面——这是整个体系最精妙的地方。Serilog 日志配置5 个生产级细节日志系统的核心实现在 Scanner/Services/LogService.cs 的InitializeAsync方法中短短几十行配置藏着不少巧思1️⃣ JSON 格式 异步写入日志使用CompactJsonFormatter以紧凑 JSON 写入文件并用WriteTo.Async包裹文件 Sink。JSON 便于程序化处理比如自动附到崩溃报告异步写入则保证高频日志不阻塞 UI 线程。2️⃣ 按天滚动 三重容量控制LogService.cs每天自动滚动一个新日志文件最多保留8 个历史文件单文件上限6.9 MB—— 注释写明原因Microsoft App Center supports attachments up to 7 MB这个 6.9MB 的魔数是刻意设计的让单个日志文件刚好能作为崩溃附件完整上传。很多项目的日志配置是拍脑袋定的而这里的每个数字都有明确的工程理由。3️⃣ 异常细节增强通过Enrich.WithExceptionDetails()来自 Serilog.Exceptions异常日志会完整记录堆栈、内部异常链、变量值而不是只有一句System.InvalidOperationException。4️⃣ 自定义 Destructure把复杂对象打平直接序列化 Windows 的DeviceInformation或内部的DiscoveredScanner对象会产生几百个无意义的属性。Scanner 为 ScanOptions、DiscoveredScanner、ScanResolution 等 6 个核心模型逐一编写了ByTransforming转换规则只保留排查问题真正需要的字段分辨率、色彩模式、自动裁剪能力等。5️⃣ 开机即写入环境元数据日志初始化后立刻记录三行关键上下文LogService.cs应用版本、操作系统版本/架构/语言、设备系列/型号/厂商。这样任何人拿到日志第一屏就知道这台机器是什么配置。AppCenter 崩溃上报把日志自动钉在崩溃报告上Scanner Windows 扫描应用宣传图上报逻辑集中在 Scanner/Services/AppCenterService.cs有三个值得学习的设计 用户可关闭的隐私开关初始化时先读取设置项SettingErrorStatistics通过AppCenter.SetEnabledAsync控制整体开关并在用户切换设置时实时响应AppCenterService.cs。遥测数据默认尊重用户意愿是生产应用的必备素养。App Center 的密钥也不硬编码在代码里而是从应用资源中提取见 Utilities.cs 的GetSecret方法。 智能附件匹配崩溃时自动带上案发日志CreateErrorAttachmentAsync方法AppCenterService.cs的匹配逻辑非常聪明关闭并刷新当前日志文件CloseAndFlush再重新初始化确保崩溃前的内容全部落盘按创建时间倒序遍历logs文件夹找到创建时间早于崩溃时间的日志文件作为log.json二进制附件上传任何环节失败都有兜底返回一条说明文本如 LogService unavailable.而不是让附件逻辑本身崩溃配合前面单文件不超 7MB的日志配置形成完整闭环每次崩溃报告 异常堆栈 崩溃前完整日志。 28 个用户行为事件AppCenterEvent枚举IAppCenterService.cs覆盖了扫描完成、裁剪、删除页面、分享、自动旋转纠正等 28 个关键操作且事件名通过集中式字典映射管理。开发者可据此分析用户最常用的功能哪个功能路径最容易出错。此外还提供了GenerateTestCrash方法——一键触发测试崩溃来验证上报管线是否正常工作这是很多团队忽略的运维细节。崩溃闭环从 UnhandledException 到云端报告整套体系在 Scanner/App.xaml.cs 中完成装配整个生命周期只有四步启动时OnLaunched中先注册UnhandledException处理器再按顺序初始化LogService→SettingsService→AppCenterServiceApp.xaml.cs。日志必须最先就绪这样 App Center 初始化过程中的问题也能被记录运行中业务代码通过注入的ILogger记录带上下文的日志崩溃瞬间全局异常处理器执行Log.Fatal(e.Exception, CRASH)并CloseAndFlush落盘App.xaml.cs下次启动App Center 客户端读取本地缓存的崩溃报告附上案发日志上传到云端用户侧还有配套能力通过日志导出对话框LogExportDialogViewModel.cs可以浏览logs目录下所有历史日志由 LogFile 模型封装文件大小与时间并一键导出到桌面——开发者回复 Issue 时再也不必求用户把日志发我一下。新手速查清单这套体系的 6 条可借鉴经验#经验Scanner 的做法1日志格式选机器友好的 JSONCompactJsonFormatter2容量限制要有可解释的理由6.9MB 对齐 App Center 附件上限3复杂对象用 Destructure 打平6 个核心模型逐一转换4崩溃报告必须带上下文按时间匹配自动附加日志文件5遥测必须可关闭、密钥不落盘设置开关 资源读取密钥6上报管线要能自测GenerateTestCrash 一键验证相关依赖版本Serilog 4.1.0、Serilog.Sinks.File 6.0.0、Microsoft.AppCenter 5.0.3 等可在 Scanner/Scanner.csproj 中查阅第三方组件的许可证文本完整收录在 Scanner/License Texts/ 目录这也是开源项目应有的规范。获取源码动手看看git clone https://gitcode.com/gh_mirrors/scanner/scanner打开后重点阅读这两个文件一小时内就能吃透整套可观测性设计日志Scanner/Services/LogService.cs崩溃上报Scanner/Services/AppCenterService.cs可观测性不是大厂的专利。Scanner 用不到 400 行代码就把记录—上报—闭环三件事做到了教科书级别。希望这份指南能帮助你在自己的项目中搭建起同样可靠的日志与崩溃上报体系。【免费下载链接】scannerAn all-in-one scanner app for Windows项目地址: https://gitcode.com/gh_mirrors/scanner/scanner创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考