高效管理鸿蒙日志：Bugly 日志诊断能力适配实践

导语：Bugly 是专业的监控定位分析平台，属于腾讯端服务（Tencent Device-oriented Service）产品联盟的重要成员，提供研发全流程、全平台、智能化的监控定位分析解决方案，助力全球开发者高效地构建高质量应用。

在鸿蒙应用开发过程中，日志管理是问题定位、性能优化和用户体验提升的关键环节。原生 HiLog 工具虽然功能完备，但在实际的企业级应用开发中仍然存在诸多局限性。基于此，本文将分享 Bugly 如何基于微信 Xlog 内核，结合平台日志管理能力，提供一套完整的鸿蒙企业级日志诊断解决方案。

一、鸿蒙原生日志系统痛点与挑战

鸿蒙原生 HiLog 工具类似 Android Logcat，在打印能力和本地调试上的能力已经比较完备了，但在实际开发中仍面临不少挑战：

•  线上调试困难：缺乏远程日志收集能力，线上问题难以还原现场和定位。

•  日志分散混杂：三方 SDK 日志、系统日志与业务自身日志混杂，不便于查阅分析。

•  打印长度限制：HiLog 打印日志存在长度限制，关键信息可能被截断。

Bugly 鸿蒙日志诊断适配实践

针对上述挑战，Bugly 鸿蒙日志组件针对 HarmonyOS NEXT 深度适配，结合平台诊断捞取与上报能力，提供一套完整的日志诊断解决方案。

鸿蒙日志诊断能力主要由两大模块组成：

1、TDLog(日志引擎)：基于高性能的微信开源 Xlog 方案，提供本地打日志能力。

微信开源 Xlog 方案在网络上已经有比较多的介绍了，基本原理是通过 mmap 和流式压缩的方式，实现高效且安全的日志打印，在此不再赘述，相关原理可参考：https://cloud.tencent.com/developer/article/1005575

源码可参考：

https://github.com/Tencent/mars/tree/master

Xlog 本身是一个跨平台方案，Bugly 诊断日志在 Android、iOS、Windows 等平台上均有实现，这也为顺利迁移到鸿蒙平台提供了技术支撑。适配鸿蒙端主要分三步：

1）编译脚本适配

Xlog 工程由 CMake 进行编译，与鸿蒙 Native 的编译方式没有区别，因此可以直接将必要的日志文件引入进来。

在其他引入编译的 CMake 文件中，利用鸿蒙 CMake 条件增加鸿蒙平台的宏定义。

2）源码逻辑适配

使用鸿蒙工具链交叉编译的 openssl 库并引入，同时补充鸿蒙平台的实现差异。

补充鸿蒙层的系统 HiLog 日志输出实现。

3）ArkTs 层封装与桥接

如果需要在 ArkTs 层使用日志打印能力，可以对 Xlog 日志进一步封装和桥接。

主要需对于日志的写入、刷新、参数设置等创建 NAPI 接口，即可在 ArkTs 层实现日志的实例创建与打印。

Bugly 为便于管理，在 ArkTs 上层做了类似 Android Xlog 的进一步封装。应用开发者也可以自行适配 Xlog，在鸿蒙端定制化日志打印能力。

2、TDDiag(诊断捞取)：提供日志捞取、日志染色、条件采集等端上日志服务。

TDDiag 是 Bugly 鸿蒙日志诊断能力中的单独模块，与日志打印能力 TDLog 独立区分，可分别初始化。

TDDiag 主要功能包括日志上报、日志捞取、日志染色等模块，核心架构如下。

日志管理后台负责日志的存储、解密及指令的下发管理。日志 SDK 部分主要包括日志上报、配置拉取及日志等级的远程调控。两个模块可独立运行，通过接口适配桥接。

在 Bugly 鸿蒙 SDK TDDiag 诊断捞取模块适配时，采用核心逻辑 Native 跨端 + 线程安全调用 Ts API 方法的方式，极大减少了适配的工作量。

与 Android 不同，在鸿蒙系统开发中，当从 Native 层回调至 ArkTS 层时，必须采用线程安全的机制（如 libuv）确保执行上下文切换至主线程。这一约束是鸿蒙架构的核心要求，任何跨 ArkTS-Native 边界的交互都必须严格遵循此线程模型，否则将引发线程上下文不一致导致的未定义行为。该规范适用于所有涉及 ArkTS 与 Native 层交互的业务场景。

三、Bugly 日志诊断业务应用场景

鸿蒙原生日志系统在企业级应用开发中存在诸多痛点和挑战，那么 Bugly 日志诊断组件在哪些场景可以帮助我们提效呢？

场景一：线上问题诊断效率提升

问题：用户设备上的崩溃、Freeze、卡顿等问题难以复现，采集的 HiLog 日志又太少，无法还原现场和定位问题。

方案：

1. 平台下发捞取指令：在 Bugly 平台指定设备 Guid 和时间范围下发捞取指令。

2. 自动配置拉取：SDK 定期或主动拉取配置。

3. 日志打包上传：SDK 自动收集指定时间段内的日志文件并上报。

4. 异常联合诊断：Bugly 平台已经全面打通日志能力，支持在异常页面一键创建异常发生前后 1 小时的日志捞取指令，快速帮助还原问题现场。

5. 日志 AI 分析：引入基于 AI 大模型的异常问题诊断工作台（内测中），一键分析采集的异常日志，工作台同时支持导入 Bugly 平台采集的异常现场，智能识别关键日志行，总结问题归因，提升诊断分析效率。

场景二：动态日志级别调整

问题：线上问题需要更详细的日志，但无法远程调试。

方案：

1. 平台创建染色指令：在 Bugly 管理端创建染色任务，指定日志级别和设备范围。

2. 设备自动响应：设备拉取配置后自动调整日志级别。

3. 日志上传或捞取：SDK 主动上传或通过捞取指令获取调试级别的详细日志。

场景三：日志分层定位清晰

问题：业务与三方 SDK，ArkTS 与 Native 层日志混合，查找关键信息、问题定位困难。

解决方案：

1. 多实例日志管理：为第三方 SDK 或不同业务层创建独立日志实例，避免主日志污染。

2. Native 层日志写入：提供 Native API 日志打印与刷新接口，无需 ArkTs 桥接，对跨端业务友好，打印日志更加高效。

场景四：日志隐私安全保障

问题：业务日志涉及用户隐私，怎么保障日志中的隐私数据不泄漏。

解决方案：

1. 日志逐行加密：基于 Xlog 的流式方式对单行日志进行压缩加密，保障日志的隐私与完整性。

2. 在线日志解密：Bugly 平台提供自动化的解密流程，上传日志可一键解密，拖拽解密，非常快捷方便。

四、结语

日志管理是鸿蒙应用开发中不可或缺的一环，良好的日志实践可以显著提升问题定位效率和用户体验。如果您是鸿蒙应用的开发者，希望本文能为您的鸿蒙应用日志设计管理提供实用参考。

Bugly 鸿蒙日志 SDK 提供了一套高效的解决方案，帮助开发者应对各种复杂场景下的诊断挑战。欢迎您尝试 Bugly 鸿蒙日志能力（当前鸿蒙端产品免费支持），享受高效诊断的便利！

当然，如果您已经有一套本地的日志系统，或者希望自行建设打日志的能力，也都可以接入 Bugly 鸿蒙日志 SDK，初始化 TDDiag 诊断捞取能力，Bugly 只作为日志平台帮助您管理和捞取所需的日志。

接入方式：https://bugly.tds.qq.com/docs/sdk/harmony/

腾讯端服务官网：https://tds.qq.com/

腾讯 Bugly 专业版官网：https://bugly.tds.qq.com